README

入门指南

该库提供了获取不同配送方式成本的功能。库中集成了USPS API，但所有计算均由库本身完成。

对于某些类的工作，需要定义PSR-3 logger，该logger将在容器中以 Psr\Log\LoggerInterface 的名字可用。

配送方式

• RM-DS
• RM-PickUp (USPS)
• PU-DS
• PU-PickUp (USPS)
• WPS-DS
• TR-DS
• SLT-DS
• AU-DS
• AU-DS-COVID19

DataStore: shipping-all-costs

该库提供了 shipping-all-costs DataStore，该DataStore返回所有配置的配送方法的成本。

查询示例

http://SOME_URL/api/datastore/shipping-all-costs?and(eq(ZipOrigination,10005),eq(ZipDestination,91730),eq(Width,2),eq(Length,2),eq(Height,5),eq(Pounds,2),ne(cost,null()))&sort(+cost)&limit(50)
http://SOME_URL/api/datastore/shipping-all-costs?and(eq(ZipOrigination,28790),eq(ZipDestination,91730),eq(Width,2),eq(Length,2),eq(Height,1),eq(Pounds,2),eq(attr_CommodityCode,301),ne(cost,null()))&sort(+cost)&limit(50)
http://SOME_URL/api/datastore/shipping-all-costs?ZipOrigination=91601&ZipDestination=91730&Width=1&Length=10&Height=5&Pounds=0.5&Click_N_Shipp=Priority%20Mail
http://SOME_URL/api/datastore/shipping-all-costs?ZipOrigination=91601&ZipDestination=91730&Width=1&Length=10&Height=5&Pounds=1&like(id,*FtCls*)&limit(2,1)&select(id)

可以向配送方法发送额外的属性。为此，在请求中指定 ...,eq(attr_CommodityCode,301),...，这意味着所有配送方法都将获得CommodityCode值为301的属性。

添加自定义配送方式

该库提供了添加自定义配送方式的功能。所有可能的配送方式都必须在 RootShippingProvider 中声明，因为这里使用的是树形结构，而树的根是root。

以下是一个通过配置添加名为 FixedPrice1 的配送方式的示例。

<?php
use rollun\Entity\Product\Container\Box; 
use rollun\Entity\Shipping\Method\FixedPrice;
use service\Entity\Rollun\Shipping\Method\Provider\Root as RootShippingProvider;
use rollun\Entity\Shipping\Method\Provider\PickUp\RmPickUp;

return [
   'ShippingMethod' => [
       'Root' => [
           'class' => RootShippingProvider::class, // указываем элемент сервис менеджера
           'shortName' => 'Root', 
           'shippingMethodList' => [
              'RM-PickUp', // добавляем первый способ доставки который по своей сути является еще одним ShippingMethodProvider со своими способами доставки
              'FixedPrice1' // добавляем наш способ доставки
           ]
       ],
       'RM-PickUp' => [ // объявляем ShippingMethodProvider
           'class'                 => RmPickUp::class, // указываем элемент сервис менеджера
              'shortName'          => 'RM-PickUp',
              'shippingMethodList' => [
                 'Usps' // указываем способы доставки
              ]
       ],
       'FixedPrice1' => [ // добавляем наш способ доставки
           'class'            => FixedPrice::class, // указываем элемент сервис менеджера
              'shortName'        => 'FP1',
              'price'            => 8,  // характерно только для FixedPrice::class, указываем цену
              'maxWeight'        => 20, // характерно только для FixedPrice::class, максимально допустимый вес
              'containerService' => 'Fixed Price Box 1' // // характерно только для FixedPrice::class, указываем контейнер
       ],
   ],
   'Container' => [
       'Fixed Price Box 1' => [ // объявляем контейнер
          'class'  => Box::class,
          'Length' => 10,
          'Width'  => 10,
          'Height' => 10
       ],
   ]
];

USPS API

要使用USPS API，需要在.env中指定 USPS_API_PASS（仅在开发模式下需要）USPS_API_PASS="112233445566"

该库会自行进行数据计算，同时也有机会检查内部计算与API响应是否一致。为此，只需运行 unit tests。更详细的内容请参考 phpunit

包装机制

rollun\Entity\Product\Container\Box 容器在检查是否可以将包裹包装到容器的方法中使用 PackagePacker。PackagePacker 是一个提供API的微服务，用于 https://github.com/betterwaysystems/packer。

请在env中指定 PACKAGE_PACKER_API_URL，以便库可以获取API数据。

使用USPS API获取配送区域名称

该方法来自页面 https://postcalc.usps.com/DomesticZoneChart（第二个标签页）。该方法允许获取接收者zip相对于发送者zip的区域。

curl查询示例

curl 'https://postcalc.usps.com/DomesticZoneChart/GetZone?origin=10001&destination=10001&shippingDate=12%2F10%2F2020&_=1607610825151' \
-X 'GET' \
-H 'Accept: application/json, text/javascript, */*; q=0.01' \
-H 'Accept-Language: en-gb' \
-H 'Host: postcalc.usps.com' \
-H 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.3 Safari/605.1.15' \
-H 'Referer: https://postcalc.usps.com/DomesticZoneChart' \
-H 'Accept-Encoding: gzip, deflate, br' \
-H 'Connection: keep-alive' \
-H 'X-Requested-With: XMLHttpRequest'

必需参数

• origin - 发送者zip
• destination - 接收者zip
• shippingDate - 发送日期
• _ - 当前timestamp，带毫秒（例如 - 1607610825151）。没有此参数时，请求将正常工作，但USPS会发送它。

始终期望响应代码为200，即使参数不正确。

响应示例 -

{
  "OriginError":"",
  "DestinationError":"",
  "ShippingDateError":"",
  "PageError":"",
  "EffectiveDate":"December 1, 2020",
  "ZoneInformation":"The Zone is 1. This is a Local zone. The destination ZIP Code is within the same NDC as the origin ZIP Code."
}

ZoneInformation - 区域名称始终是第一行，格式（至少根据测试结果）如下。

The Zone is <zone_number>

错误响应示例，未指定日期 -

{
  "OriginError":"",
  "DestinationError":"",
  "ShippingDateError":"Mailing date is invalid.",
  "PageError":"",
  "EffectiveDate":"",
  "ZoneInformation":""
}

USPS_PACKAGE_COSTS 生成器

生成器脚本，用于生成符合指定尺寸的盒子价格数组，位于 bin/UspsPackageCostsGenerator.php。输入为csv格式，输出为所需数组（data目录中有示例），然后将其插入到类中。