onetikk/ot-ups-api

PHP UPS API

维护者

详细信息

github.com/OnetikkConsultants/ot-ups-api

源代码

问题

安装次数: 5

依赖项: 0

建议者: 0

安全性: 0

星标: 0

关注者: 2

分支: 0

开放问题: 0

1.2.0 2021-03-18 09:05 UTC

Requires

Requires (Dev)

Suggests

  • ext-soap: Required if you need the Tradeability API of UPS

MIT 794943ade3d267245b987bc5017e25eb2a6ad557

  • dileep <dileep.woop@onetikk.com>

apishippingups

This package is auto-updated.

Last update: 2024-09-29 05:43:10 UTC

README

UPS PHP Api

这是 gabrielbull 的 PHP UPS API 的修改版本，还包括 Laravel 包装器。根据我们的需求进行了一些自定义更改。如果您想使用 gabrielbull 的 PHP API，请访问 gabrielbull/php-ups-api

此库将所有 UPS API 包装成一个简单易用的 PHP 库。目前它涵盖了 Quantum View®、跟踪 API、运输 API、计费 API 和运输时间 API。欢迎贡献。

目录

  1. 要求
  2. 安装
  3. 地址验证类
  4. 简单地址验证类
  5. QuantumView 类
  6. 跟踪类
  7. 计费类
  8. 计费时间类
  9. 运输时间类
  10. 定位器类
  11. 可交易性类
  12. 运输类
  13. 日志记录
  14. 许可证

要求

此库使用 PHP 7.1+。

要使用 UPS API，您必须从 UPS 请求访问密钥。对于每个请求，您都必须提供访问密钥、您的 UPS 用户 ID 和密码。

如果不使用 composer，您还必须包括以下库： Guzzle、Guzzle Promises、[Guzzle PSR7] (https://github.com/guzzle/psr7)、PHP-Fig PSR Log 和 PHP-Fig HTTP Message。

地址验证类（街道级别）

地址验证类允许您在街道级别验证地址。当地址无效时，会提供建议。

注意：UPS 有两种地址验证。这是街道级别选项，它包括正常地址验证类的所有选项，并添加了街道级别验证。

目前，仅支持美国和波多黎各。

示例

$address = new \Ups\Entity\Address();
$address->setAttentionName('Test Test');
$address->setBuildingName('Test');
$address->setAddressLine1('Address Line 1');
$address->setAddressLine2('Address Line 2');
$address->setAddressLine3('Address Line 3');
$address->setStateProvinceCode('NY');
$address->setCity('New York');
$address->setCountryCode('US');
$address->setPostalCode('10000');

$xav = new \Ups\AddressValidation($accessKey, $userId, $password);
$xav->activateReturnObjectOnValidate(); //This is optional
try {
    $response = $xav->validate($address, $requestOption = \Ups\AddressValidation::REQUEST_OPTION_ADDRESS_VALIDATION, $maxSuggestion = 15);
} catch (Exception $e) {
    var_dump($e);
}

AddressValidation::validateReturnAVObject()

在上面的代码中 $xav->activateReturnObjectOnValidate() 是完全可选的。调用此方法将导致 AddressValidation::validate() 返回一个 AddressValidationResponse 对象。如果您不调用此方法，validate 将继续按以前的方式运行。如果不调用此方法，将返回一个包含匹配的验证地址（或如果地址模糊不清，则返回第一个候选地址）的单个对象。

AddressValidationResponse 对象提供了一些方法，使您可以更轻松地查询 API 响应以确定结果。继续上面的示例，返回一个 AddressValidationResponse 对象将允许您更具体地处理各种结果

if ($response->noCandidates()) {
    //Do something clever and helpful to let the use know the address is invalid
}
if ($response->isAmbiguous()) {
    $candidateAddresses = $response->getCandidateAddressList();
    foreach($candidateAddresses as $address) {
        //Present user with list of candidate addresses so they can pick the correct one        
    }
}
if ($response->isValid()) {
    $validAddress = $response->getValidatedAddress();
    
    //Show user validated address or update their address with the 'official' address
    //Or do something else helpful...
}

参数

地址验证参数是

  • address 地址对象，如示例中所构造
  • requestOption 三个请求选项之一。请参阅文档。默认 = 地址验证。
  • maxSuggestion 返回的最大建议数。最大 = 50

简单地址验证类

简单地址验证类允许您验证的范围比上一个类更小。它返回所提供地址的质量评分并提供替代方案。

注意：UPS 有两种地址验证。这是简单选项。

目前，仅支持美国和波多黎各。

示例

$address = new \Ups\Entity\Address();
$address->setStateProvinceCode('NY');
$address->setCity('New York');
$address->setCountryCode('US');
$address->setPostalCode('10000');

$av = new \Ups\SimpleAddressValidation($accessKey, $userId, $password);
try {
    $response = $av->validate($address);
    var_dump($response);
} catch (Exception $e) {
    var_dump($e);
}

参数

简单地址验证参数是

  • address 地址对象，如示例中所构造

QuantumView 类

QuantumView 类允许您请求 Quantum View 数据订阅。

示例

$quantumView = new Ups\QuantumView($accessKey, $userId, $password);

try {
	// Get the subscription for all events for the last hour
	$events = $quantumView->getSubscription(null, (time() - 3600));

	foreach($events as $event) {
		// Your code here
		echo $event->Type;
	}

} catch (Exception $e) {
	var_dump($e);
}

参数

QuantumView 参数是

  • name 用户请求的订阅名称。如果为 null，则返回所有事件。
  • beginDateTime 订阅检索条件的开始日期时间。格式：Y-m-d H:i:s 或 Unix 时间戳。
  • endDateTime 订阅检索条件的结束日期时间。格式：Y-m-d H:i:s 或 Unix 时间戳。
  • fileName 用户请求的特定订阅的文件名。
  • bookmark 将文件标记为下次检索。

如果您提供了 beginDateTime，但没有 endDateTime，则 endDateTime 将默认为当前日期时间。

要使用 fileName 参数，不要提供 beginDateTime。

跟踪类

跟踪类允许您使用 UPS 跟踪 API 跟踪运单。

使用跟踪号码/邮件创新跟踪号码的示例

$tracking = new Ups\Tracking($accessKey, $userId, $password);

try {
	$shipment = $tracking->track('TRACKING NUMBER');

	foreach($shipment->Package->Activity as $activity) {
		var_dump($activity);
	}

} catch (Exception $e) {
	var_dump($e);
}

参数

跟踪参数包括

  • trackingNumber 包裹的跟踪号码。
  • requestOption 可选处理。对于邮件创新，唯一有效的选项是最后活动状态和所有活动状态。

使用参考号码的示例

$tracking = new Ups\Tracking($accessKey, $userId, $password);

try {
    $shipment = $tracking->trackByReference('REFERENCE NUMBER');

    foreach($shipment->Package->Activity as $activity) {
        var_dump($activity);
    }

} catch (Exception $e) {
    var_dump($e);
}

参数

跟踪参数包括

  • referenceNumber 通过参考号码跟踪任何 UPS 包裹或运单的能力。参考号码可以是采购订单号码、工作号码等。参考号码在生成运单时提供。
  • requestOption 可选处理。对于邮件创新，唯一有效的选项是最后活动状态和所有活动状态。

使用参考号码和附加参数的示例

$tracking = new Ups\Tracking($accessKey, $userId, $password);

$tracking->setShipperNumber('SHIPPER NUMBER');

$beginDate = new \DateTime('2016-01-01');
$endDate = new \DateTime('2016-01-31');

$tracking->setBeginDate($beginDate);
$tracking->setEndDate($endDate);

try {
    $shipment = $tracking->trackByReference('REFERENCE NUMBER');

    foreach($shipment->Package->Activity as $activity) {
        var_dump($activity);
    }

} catch (Exception $e) {
    var_dump($e);
}

参数 shipperNumber、beginDate 和 endDate 是可选的。可以单独设置任意一个参数。这些参数可以帮助在通过参考号码跟踪时缩小搜索范围，因为可能使用的参考号码不唯一。在通过跟踪号码跟踪时，不需要这些参数，因为跟踪号码是唯一的。

计费类

费率类允许您使用 UPS 费率 API 获取运费。

示例

$rate = new Ups\Rate(
	$accessKey,
	$userId,
	$password
);

try {
    $shipment = new \Ups\Entity\Shipment();

    $shipperAddress = $shipment->getShipper()->getAddress();
    $shipperAddress->setPostalCode('99205');

    $address = new \Ups\Entity\Address();
    $address->setPostalCode('99205');
    $shipFrom = new \Ups\Entity\ShipFrom();
    $shipFrom->setAddress($address);

    $shipment->setShipFrom($shipFrom);

    $shipTo = $shipment->getShipTo();
    $shipTo->setCompanyName('Test Ship To');
    $shipToAddress = $shipTo->getAddress();
    $shipToAddress->setPostalCode('99205');

    $package = new \Ups\Entity\Package();
    $package->getPackagingType()->setCode(\Ups\Entity\PackagingType::PT_PACKAGE);
    $package->getPackageWeight()->setWeight(10);
    
    // if you need this (depends of the shipper country)
    $weightUnit = new \Ups\Entity\UnitOfMeasurement;
    $weightUnit->setCode(\Ups\Entity\UnitOfMeasurement::UOM_KGS);
    $package->getPackageWeight()->setUnitOfMeasurement($weightUnit);

    $dimensions = new \Ups\Entity\Dimensions();
    $dimensions->setHeight(10);
    $dimensions->setWidth(10);
    $dimensions->setLength(10);

    $unit = new \Ups\Entity\UnitOfMeasurement;
    $unit->setCode(\Ups\Entity\UnitOfMeasurement::UOM_IN);

    $dimensions->setUnitOfMeasurement($unit);
    $package->setDimensions($dimensions);

    $shipment->addPackage($package);

    var_dump($rate->getRate($shipment));
} catch (Exception $e) {
    var_dump($e);
}

参数

  • rateRequest 必须的。包含运货行情的 rateRequest 对象

此费率类尚未完成！当完成时将添加参数。

计费时间类

RateTimeInTransit 类允许您获取与 Rate 类相同的运费，但响应还将包括 TimeInTransit 数据。

示例

$rate = new Ups\RateTimeInTransit(
	$accessKey,
	$userId,
	$password
);

try {
    $shipment = new \Ups\Entity\Shipment();

    $shipperAddress = $shipment->getShipper()->getAddress();
    $shipperAddress->setPostalCode('99205');

    $address = new \Ups\Entity\Address();
    $address->setPostalCode('99205');
    $shipFrom = new \Ups\Entity\ShipFrom();
    $shipFrom->setAddress($address);

    $shipment->setShipFrom($shipFrom);

    $shipTo = $shipment->getShipTo();
    $shipTo->setCompanyName('Test Ship To');
    $shipToAddress = $shipTo->getAddress();
    $shipToAddress->setPostalCode('99205');

    $package = new \Ups\Entity\Package();
    $package->getPackagingType()->setCode(\Ups\Entity\PackagingType::PT_PACKAGE);
    $package->getPackageWeight()->setWeight(10);
    
    // if you need this (depends of the shipper country)
    $weightUnit = new \Ups\Entity\UnitOfMeasurement;
    $weightUnit->setCode(\Ups\Entity\UnitOfMeasurement::UOM_KGS);
    $package->getPackageWeight()->setUnitOfMeasurement($weightUnit);

    $dimensions = new \Ups\Entity\Dimensions();
    $dimensions->setHeight(10);
    $dimensions->setWidth(10);
    $dimensions->setLength(10);

    $unit = new \Ups\Entity\UnitOfMeasurement;
    $unit->setCode(\Ups\Entity\UnitOfMeasurement::UOM_IN);

    $dimensions->setUnitOfMeasurement($unit);
    $package->setDimensions($dimensions);

    $shipment->addPackage($package);

    $deliveryTimeInformation = new \Ups\Entity\DeliveryTimeInformation();
    $deliveryTimeInformation->setPackageBillType(\Ups\Entity\DeliveryTimeInformation::PBT_NON_DOCUMENT);
    
    $pickup = new \Ups\Entity\Pickup();
    $pickup->setDate("20170520");
    $pickup->setTime("160000");
    $shipment->setDeliveryTimeInformation($deliveryTimeInformation);

    var_dump($rate->shopRatesTimeInTransit($shipment));
} catch (Exception $e) {
    var_dump($e);
}

参数

  • rateRequest 必须的。包含运货行情的 rateRequest 对象

此 RateTimeInTransit 扩展了尚未完成的 Rate 类！当完成时将添加参数。

运输时间类

TimeInTransit 类允许您使用 UPS TimeInTransit API 获取所有过境时间。

示例

$timeInTransit = new Ups\TimeInTransit($access, $userid, $passwd);

try {
    $request = new \Ups\Entity\TimeInTransitRequest;

    // Addresses
    $from = new \Ups\Entity\AddressArtifactFormat;
    $from->setPoliticalDivision3('Amsterdam');
    $from->setPostcodePrimaryLow('1000AA');
    $from->setCountryCode('NL');
    $request->setTransitFrom($from);

    $to = new \Ups\Entity\AddressArtifactFormat;
    $to->setPoliticalDivision3('Amsterdam');
    $to->setPostcodePrimaryLow('1000AA');
    $to->setCountryCode('NL');
    $request->setTransitTo($to);

    // Weight
    $shipmentWeight = new \Ups\Entity\ShipmentWeight;
    $shipmentWeight->setWeight($totalWeight);
    $unit = new \Ups\Entity\UnitOfMeasurement;
    $unit->setCode(\Ups\Entity\UnitOfMeasurement::UOM_KGS);
    $shipmentWeight->setUnitOfMeasurement($unit);
    $request->setShipmentWeight($shipmentWeight);

    // Packages
    $request->setTotalPackagesInShipment(2);

    // InvoiceLines
    $invoiceLineTotal = new \Ups\Entity\InvoiceLineTotal;
    $invoiceLineTotal->setMonetaryValue(100.00);
    $invoiceLineTotal->setCurrencyCode('EUR');
    $request->setInvoiceLineTotal($invoiceLineTotal);

    // Pickup date
    $request->setPickupDate(new DateTime);

    // Get data
    $times = $timeInTransit->getTimeInTransit($request);

	foreach($times->ServiceSummary as $serviceSummary) {
		var_dump($serviceSummary);
	}

} catch (Exception $e) {
    var_dump($e);
}

参数

  • timeInTransitRequest 必须的。包含运货行情的 timeInTransitRequest 对象，请参阅上面的示例。

定位器类

定位器类允许您搜索 UPS 访问点位置。

示例

$locatorRequest = new \Ups\Entity\LocatorRequest;

$originAddress = new \Ups\Entity\OriginAddress;
$address = new \Ups\Entity\AddressKeyFormat;
$address->setCountryCode('NL');
$originAddress->setAddressKeyFormat($address);

$geocode = new \Ups\Entity\GeoCode;
$geocode->setLatitude(52.0000);
$geocode->setLongitude(4.0000);
$originAddress->setGeoCode($geocode);
$locatorRequest->setOriginAddress($originAddress);

$translate = new \Ups\Entity\Translate;
$translate->setLanguageCode('ENG');
$locatorRequest->setTranslate($translate);

$acccessPointSearch = new \Ups\Entity\AccessPointSearch;
$acccessPointSearch->setAccessPointStatus(\Ups\Entity\AccessPointSearch::STATUS_ACTIVE_AVAILABLE);

$locationSearch = new \Ups\Entity\LocationSearchCriteria;
$locationSearch->setAccessPointSearch($acccessPointSearch);
$locationSearch->setMaximumListSize(25);

$locatorRequest->setLocationSearchCriteria($locationSearch);

$unitOfMeasurement = new \Ups\Entity\UnitOfMeasurement;
$unitOfMeasurement->setCode(\Ups\Entity\UnitOfMeasurement::UOM_KM);
$unitOfMeasurement->setDescription('Kilometers');
$locatorRequest->setUnitOfMeasurement($unitOfMeasurement);

try {
    // Get the locations
    $locator = new Ups\Locator($accessKey, $userId, $password);
    $locations = $locator->getLocations($locatorRequest, \Ups\Locator::OPTION_UPS_ACCESS_POINT_LOCATIONS);

	foreach($locations->SearchResults->DropLocation as $location) {
		// Your code here
		var_dump($location);
	}

} catch (Exception $e) {
	var_dump($e);
}

参数

定位器类参数包括

  • locatorRequest 必须的。包含请求详情的 locatorRequest 对象，请参阅示例
  • requestOption 可选的。您正在搜索的位置类型。

运输类

Shipping 类允许您注册运单。这也包括退货运单。

运输流程包括 2 个步骤

  • 确认：向 UPS 发送信息以获取验证并获取可用于接受运单的摘要。
  • 接受：完成运单，标记为即将发货。获取标签和附加信息。

请注意，这只是一个示例。您的用例可能需要向 UPS 发送更多或更少的信息。

在示例中 $return 用于显示如何处理退货。

示例

// Start shipment
$shipment = new Ups\Entity\Shipment;

// Set shipper
$shipper = $shipment->getShipper();
$shipper->setShipperNumber('XX');
$shipper->setName('XX');
$shipper->setAttentionName('XX');
$shipperAddress = $shipper->getAddress();
$shipperAddress->setAddressLine1('XX');
$shipperAddress->setPostalCode('XX');
$shipperAddress->setCity('XX');
$shipperAddress->setStateProvinceCode('XX'); // required in US
$shipperAddress->setCountryCode('XX');
$shipper->setAddress($shipperAddress);
$shipper->setEmailAddress('XX'); 
$shipper->setPhoneNumber('XX');
$shipment->setShipper($shipper);

// To address
$address = new \Ups\Entity\Address();
$address->setAddressLine1('XX');
$address->setPostalCode('XX');
$address->setCity('XX');
$address->setStateProvinceCode('XX');  // Required in US
$address->setCountryCode('XX');
$shipTo = new \Ups\Entity\ShipTo();
$shipTo->setAddress($address);
$shipTo->setCompanyName('XX');
$shipTo->setAttentionName('XX');
$shipTo->setEmailAddress('XX'); 
$shipTo->setPhoneNumber('XX');
$shipment->setShipTo($shipTo);

// From address
$address = new \Ups\Entity\Address();
$address->setAddressLine1('XX');
$address->setPostalCode('XX');
$address->setCity('XX');
$address->setStateProvinceCode('XX');  
$address->setCountryCode('XX');
$shipFrom = new \Ups\Entity\ShipFrom();
$shipFrom->setAddress($address);
$shipFrom->setName('XX');
$shipFrom->setAttentionName($shipFrom->getName());
$shipFrom->setCompanyName($shipFrom->getName());
$shipFrom->setEmailAddress('XX');
$shipFrom->setPhoneNumber('XX');
$shipment->setShipFrom($shipFrom);

// Sold to
$address = new \Ups\Entity\Address();
$address->setAddressLine1('XX');
$address->setPostalCode('XX');
$address->setCity('XX');
$address->setCountryCode('XX');
$address->setStateProvinceCode('XX');
$soldTo = new \Ups\Entity\SoldTo;
$soldTo->setAddress($address);
$soldTo->setAttentionName('XX');
$soldTo->setCompanyName($soldTo->getAttentionName());
$soldTo->setEmailAddress('XX');
$soldTo->setPhoneNumber('XX');
$shipment->setSoldTo($soldTo);

// Set service
$service = new \Ups\Entity\Service;
$service->setCode(\Ups\Entity\Service::S_STANDARD);
$service->setDescription($service->getName());
$shipment->setService($service);

// Mark as a return (if return)
if ($return) {
    $returnService = new \Ups\Entity\ReturnService;
    $returnService->setCode(\Ups\Entity\ReturnService::PRINT_RETURN_LABEL_PRL);
    $shipment->setReturnService($returnService);
}

// Set description
$shipment->setDescription('XX');

// Add Package
$package = new \Ups\Entity\Package();
$package->getPackagingType()->setCode(\Ups\Entity\PackagingType::PT_PACKAGE);
$package->getPackageWeight()->setWeight(10);
$unit = new \Ups\Entity\UnitOfMeasurement;
$unit->setCode(\Ups\Entity\UnitOfMeasurement::UOM_KGS);
$package->getPackageWeight()->setUnitOfMeasurement($unit);

// Set Package Service Options
$packageServiceOptions = new \Ups\Entity\PackageServiceOptions();
$packageServiceOptions->setShipperReleaseIndicator(true);
$package->setPackageServiceOptions($packageServiceOptions);

// Set dimensions
$dimensions = new \Ups\Entity\Dimensions();
$dimensions->setHeight(50);
$dimensions->setWidth(50);
$dimensions->setLength(50);
$unit = new \Ups\Entity\UnitOfMeasurement;
$unit->setCode(\Ups\Entity\UnitOfMeasurement::UOM_CM);
$dimensions->setUnitOfMeasurement($unit);
$package->setDimensions($dimensions);

// Add descriptions because it is a package
$package->setDescription('XX');

// Add this package
$shipment->addPackage($package);

// Set Reference Number
$referenceNumber = new \Ups\Entity\ReferenceNumber;
if ($return) {
    $referenceNumber->setCode(\Ups\Entity\ReferenceNumber::CODE_RETURN_AUTHORIZATION_NUMBER);
    $referenceNumber->setValue($return_id);
} else {
    $referenceNumber->setCode(\Ups\Entity\ReferenceNumber::CODE_INVOICE_NUMBER);
    $referenceNumber->setValue($order_id);
}
$shipment->setReferenceNumber($referenceNumber);

// Set payment information
$shipment->setPaymentInformation(new \Ups\Entity\PaymentInformation('prepaid', (object)array('AccountNumber' => 'XX')));

// Ask for negotiated rates (optional)
$rateInformation = new \Ups\Entity\RateInformation;
$rateInformation->setNegotiatedRatesIndicator(1);
$shipment->setRateInformation($rateInformation);

// Get shipment info
try {
    $api = new Ups\Shipping($accessKey, $userId, $password); 

    $confirm = $api->confirm(\Ups\Shipping::REQ_VALIDATE, $shipment);
    var_dump($confirm); // Confirm holds the digest you need to accept the result
    
    if ($confirm) {
        $accept = $api->accept($confirm->ShipmentDigest);
        var_dump($accept); // Accept holds the label and additional information
    }
} catch (\Exception $e) {
    var_dump($e);
}

如果您想从 $accept 返回的 UPS 运输标签图像数据创建可打印的文件，您可以使用以下内容

$label_file = $order_id . ".gif"; 
$base64_string = $accept->PackageResults->LabelImage->GraphicImage;
$ifp = fopen($label_file, 'wb');
fwrite($ifp, base64_decode($base64_string));
fclose($ifp);

参数

对于 Shipping confirm 调用，参数包括

  • $validation 一个 UPS_Shipping::REQ_* 常量（或 null）。必需的
  • $shipment 运输数据容器。必需的
  • $labelSpec 标签规范数据。可选的
  • $receiptSpec 运输请求收据规范数据。可选的

对于 Shipping accept 调用，参数包括

  • $shipmentDigest 从 ShipConfirm 请求收到的 UPS 运输摘要。必需的

许可证

PHP UPS API 在 The MIT License (MIT) 下授权。