README

PHP 语言编写的 DPD 快递公司 Web 服务客户端

PackageService（注册包裹、打印标签和交接协议、预约快递员收取包裹）
AppService（处理第三方收件订单）
InfoService（跟踪包裹）

安装

最简单的方式是使用 Composer 进行安装（https://getcomposer.org.cn）。

通过 composer.json 文件

{
    "require": {
        "GTools/dpd-pl-api-php": "^0"
    }
}

或命令行

composer require GTools/dpd-pl-api-php

该库使用 httplug 作为 HTTP 客户端抽象，不包含任何默认实现。在包含该库的项目中，负责提供符合 PSR-18 规范的 HTTP 客户端。更多信息请参阅：http://docs.php-http.org/en/latest/httplug/users.html

如果你的项目已经包含由 httplug 支持的 HTTP 客户端（http://docs.php-http.org/en/latest/clients.html），则只需与库一起安装相应的适配器即可。

例如，对于 curl

composer require php-http/curl-client:^1 GTools/dpd-pl-api-php

如果你在代码中还没有使用任何兼容的 HTTP 客户端，则需要与适配器一起安装它。

例如，guzzle

composer require php-http/guzzle6-adapter:^1 guzzlehttp/guzzle:~6.0 GTools/dpd-pl-api-php

使用方法

要使用 DPD API 正确发送包裹，需要遵循以下步骤（以下部分将详细说明）：

注册包裹/包裹（方法 generatePackageNumbers()）

向此方法发送构成包裹的物理包裹数据、发件人和收件人数据、额外订购的服务（例如取件、送货保证等）。作为响应，我们为每个包裹获取运输单号。
为包裹生成标签（方法 generateLabels()）

将上一步骤中获得的运输单号发送到此方法，作为响应，我们将获得包含标签的 PDF 文件，可以粘贴到包裹上。
为包裹生成交接协议（方法 generateProtocol()）

与上述方法类似，向此方法发送要一起发送的包裹的运输单号。作为响应，API 返回包含准备好的交接协议的 PDF 文件。
检查快递员在所需发货日的可用时间（方法 getCourierAvailability()）

该方法在发送发件人地址的邮政编码后，将返回快递员在接下来的几天内的可用时间区间。
通过快递员预约收件（TODO）

向此方法发送从上述方法获得的日期和时间区间以及收件地点，作为响应，我们将收到收件确认。快递员将根据步骤 2 中生成的标签收货，并确认步骤 3 中生成的交接协议。

除了上述基本包裹处理方法外，该库还允许以下操作：

由第三方安排收件
获取配送点列表（TODO）
跟踪包裹

0. 连接到 API

要开始使用 API，需要包含以下三个认证参数的数据

用户名
密码
FID 号码

这些数据在签订合同并声明希望使用 API 后，可从您的客户经理处获取。这些数据用于在本文档开头提到的所有三个 Web 服务中认证。这些数据同样用于认证。

通过构建以下类的对象来使用 API：GTools\Dpd\Api

require_once __DIR__.'/vendor/autoload.php';

$login = 'testlogin';
$password = 'testpassword';
$fid = 12345;

$api = new \GTools\Dpd\Api($login, $password, $fid);

默认情况下，库会连接到生产端点，但对于大多数API服务，DPD还提供了测试端点，允许您安全地测试自己的代码与Web服务的集成。要启用它们的使用，需要在Api对象上调用setSandboxMode方法。

$api->setSandboxMode(true);

从现在起，所有请求都将被定向到测试端点。对于不提供测试版本的服务，使用sandbox模式将导致SandboxNotAvailableException异常。

测试API需要单独的登录信息（这些信息由DPD IT部门与文档包一起提供，客户提出API集成意愿后）。使用生产数据登录到测试端点将导致认证错误。

要禁用测试模式，当然可以使用

$api->setSandboxMode(false);

1. 注册包裹

GeneratePackageNumbersRequest

通过generatePackageNumbers方法分配包裹号码，该方法接受一个GeneratePackageNumbersRequest类型的参数

use \GTools\Dpd\Request\GeneratePackageNumbersRequest;

/** @var GeneratePackageNumbersRequest $request */
$response = $api->generatePackageNumbers($request);

请求对象基于传递给制造方法fromPackage或fromPackages（对于由多个包裹组成的请求）的包裹/包裹数据构建

$singlePackageRequest = GeneratePackageNumbersRequest::fromPackage($package);
$multiplePackagesRequest = GeneratePackageNumbersRequest::fromPackages([$package1, $package2]);

Package

用于构建上述请求的加密对象是Package类型的对象，包含包裹的配置。构建它至少需要三个数据 - 发件人Sender对象、收件人Receiver对象和一个或多个表示组成包裹的物理包裹的Parcel类的实例。下面是一个创建Package对象的示例代码

use GTools\Dpd\Objects\Sender;
use GTools\Dpd\Objects\Receiver;
use GTools\Dpd\Objects\Parcel;
use GTools\Dpd\Objects\Package;

$sender = new Sender(12345, 501100100, 'Jan Kowalski', 'Puławska 1', '02566', 'Warszawa', 'PL');
$receiver = new Receiver(605600600, 'Piotr Nowak', 'Kwiatowa 2', '60814', 'Poznań', 'PL');

$parcel = new Parcel(30, 30, 15, 1.5);

$package = new Package($sender, $receiver, [$parcel]);

Sender和Receiver对象以类似的方式初始化，使用地址数据和必填的电话号码。此外，还向Sender对象传递用于登录的FID号码（该API假设包裹的发送者是API客户）

$sender = new Sender(
    $fid,          //numer FID
    $phone,        //telefon
    $name,         //imię i nazwisko
    $address,      //adres
    $postalCode,   //kod pocztowy
    $city,         //miasto
    $countryCode,  //kod kraju
    $company,      //nazwa firmy (opcjonalnie)
    $email         //email (opcjonalnie)
    );
    
$receiver = new Receiver(
    $phone,        //telefon
    $name,         //imię i nazwisko
    $address,      //adres
    $postalCode,   //kod pocztowy
    $city,         //miasto
    $countryCode,  //kod kraju
    $company,      //nazwa firmy (opcjonalnie)
    $email         //email (opcjonalnie)
    );

Parcel对象是按以下方式构建的

$parcel = new Parcel(
    $sizeX,          //szerokość w cm
    $sizeY,          //wysokość w cm
    $sizeZ,          //głębokość w cm
    $weight,         //masa w kg
    $reference,      //unikalna referencja paczki
    $contents,       //opis zawartości
    $customerNotes   //notatka dla kuriera
    );

GeneratePackageNumbersResponse

generatePackageNumbers方法返回一个GeneratePackageNumbersResponse类型的对象

/** @var GeneratePackageNumbersResponse $response */
$response = $api->generatePackageNumbers($request);

内部我们有注册包裹的列表 - RegisteredPackage类型的对象数组

/** @var RegisteredPackage[] $packages */
$packages = $response->getPackages()

在每个包裹中 - 注册包裹的列表，带有分配的运单号码

list($package) = $packages;

/** @var RegisteredParcel[] $parcels */
$parcels = $package->getParcels();
list($parcel) = $parcels;
 
$parcel->getWaybill(); //numer listu przewozowego, np. 0000092494467Q

2. 下载标签

使用generateLabels方法打印标签，该方法接受一个GenerateLabelsRequest类型的对象

use \GTools\Dpd\Request\GenerateLabelsRequest;

/** @var GenerateLabelsRequest $request */
$response = $api->generateLabels($request);

GenerateLabelsRequest

请求对象可以以三种方式构建

使用步骤1中生成的运单号码

use \GTools\Dpd\Request\GenerateLabelsRequest;

$request = GenerateLabelsRequest::fromWaybills(['0000092494467Q']);

使用步骤1中分配的包裹标识符

use \GTools\Dpd\Request\GenerateLabelsRequest;

$parcelId = $parcel->getId();
$request = GenerateLabelsRequest::fromParcelIds([$parcelId]);

或使用包裹的reference字段

use \GTools\Dpd\Request\GenerateLabelsRequest;

$parcelRef = $parcel->getReference();
$request = GenerateLabelsRequest::fromReferences([$parcelRef]);

（当然，在这里要注意，reference字段是我们想与包裹关联的任意字符串，例如订单编号等 - 因此，如果在步骤1中注册包裹时没有传递任何此字段的值，则无法使用它）

GenerateLabelsResponse

在构建请求并使用generateLabels方法将其发送到API后，我们将获得一个GenerateLabelsResponse类型的对象作为响应

/** @var GenerateLabelsResponse $response */
$response = $api->generateLabels($request);

内部我们有包含标签/标签的PDF文件二进制数据的fileContent字段。下面的示例展示了将标签写入etykieta.pdf文件的代码

$response = $api->generateLabels($request);

$fp = fopen('etykieta.pdf', 'wb');
fwrite($fp, $response->getFileContent());
fclose($fp)

3. 生成交付协议

要生成交付给快递员的协议，请使用generateProtocol方法

use \GTools\Dpd\Request\GenerateProtocolRequest;

/** @var GenerateProtocolRequest $request */
$response = $api->generateProtocol($request);

GenerateProtocolRequest

请求对象的创建与生成标签的情况非常相似。在这里，我们也可以以三种方式创建对象，使用运单号码、包裹标识符或包裹引用

use \GTools\Dpd\Request\GenerateProtocolRequest;

$request = GenerateProtocolRequest::fromWaybills([...]);
$request = GenerateProtocolRequest::fromParcelIds([...]);
$request = GenerateProtocolRequest::fromReferences([...]);

GenerateProtocolResponse

将构建好的请求发送到API后，我们将获得一个包含fileContent字段的GenerateProtocolResponse类型的对象，其中包含PDF文件的内容

/** @var GenerateLabelsResponse $response */
$response = $api->generateProtocol($request);

$response->getFileContent()); //treść pliku PDF z protokołem przekazania

4. 检查快递员可用时间

DOC TODO

5. 订单快递员取件

DOC TODO

由第三方安排收件

使用 AppService API 可以发出请求以从第三方接收包裹。为此，需要创建一个或多个描述包裹配置的 Package 类型的对象，就像常规发送一样，记住在 $sender 字段中应包含实际向快递员发出包裹的实体的数据，而不是委托接收的人！

此外，接收委托的端点仅接受已声明第三方支付（即委托接收方）支付的 Package 对象

$package->setPayerType(\GTools\Dpd\Objects\Enum\PayerType::THIRD_PARTY());

以及该支付者的 FID 号码（即实际上我们用于连接 API 的相同号码）

$package->setThirdPartyFid(123);

CollectionOrderRequest

这样构建的 Package 对象用作生成 CollectionOrderRequest 对象的参数

use \GTools\Dpd\Request\CollectionOrderRequest;

$singlePackageRequest = CollectionOrderRequest::fromPackage($package);
$multiplePackagesRequest = CollectionOrderRequest::fromPackages([$package1, $package2]);

通过它我们可以调用 API 的接收委托方法 - collectionOrder()

use \GTools\Dpd\Request\CollectionOrderRequest;

/** @var CollectionOrderRequest $request */
$response = $api->collectionOrder($request);

CollectionOrderResponse

作为响应，我们得到一个类型为 CollectionOrdersResponse 的对象

/** @var CollectionOrderResponse $response */
$response = $api->collectionOrder($request);

其中包含已委托的包裹的列表信息，以 CollectionOrderedPackage 类型的对象数组的形式表示

/** @var CollectionOrderedPackage[] $packages */
$packages = $response->getCollectionOrderedPackages();

list($package) = $packages;

$package->getPackageId();   //identyfikator przesyłki nadany przez DPD
$package->getReference();   //ewentualna referencja klienta nadana wiążąca paczkę z obiektem Package przesłanym w requeście
$package->getParcels();     //tablica obiektów typu CollectionOrderedParcel opisujących zlecona paczki tej przeysyłki
$package->getStatusInfo();  //status tego requestu
$package->getOrderNumber(); //numer zlecenia w systemie DPD

而在从 $package->getParcels() 获取的 CollectionOrderedParcel 对象中，记录了由 DPD 分配的包裹标识符以及该包裹的运单号

list($parcel) = $package->getParcels();

$parcel->getParcelId(); //identyfikator paczki nadany przez DPD
$parcel->getWaybill();  //numer listu przewozowego dla tej paczki

在这一点上，从第三方接收包裹的委托流程结束。不需要打印标签并将其交给发送方或订购快递员 - 这将由 DPD 自动完成。

跟踪包裹

要获取有关特定包裹的信息，我们可以通过 InfoService API 的 getParcelTracking 方法来获取

use \GTools\Dpd\Request\GetParcelTrackingRequest;

/** @var GetParcelTrackingRequest $request */
$response = $api->getParcelTracking($request);

GetParcelTrackingRequest

向该方法传递运单号来创建请求对象

use \GTools\Dpd\Request\GetParcelTrackingRequest;

$request = GetParcelTrackingRequest::fromWaybill(...);

可选地，我们可以指定我们是要查看包裹的完整历史记录还是只查看最近记录的事件

use \GTools\Dpd\Request\GetParcelTrackingRequest;
use GTools\Dpd\Objects\Enum\TrackingEventsCount;

$request = GetParcelTrackingRequest::fromWaybill('01234567890U', TrackingEventsCount::ALL()); 
$request = GetParcelTrackingRequest::fromWaybill('01234567890U', TrackingEventsCount::ONLY_LAST());

其中默认值为 TrackingEventsCount::ALL()，即获取包裹历史中的所有事件。

GetParcelTrackingResponse

作为响应，我们得到一个类型为 GetParcelTrackingResponse 的对象

use \GTools\Dpd\Response\GetParcelTrackingResponse;

/** @var GetParcelTrackingResponse $response */
$response = $api->getParcelTracking($request);

通过 getEvents() 方法，它提供了一个 ParcelEvent 类型的对象数组，表示包裹历史中的单个事件

/** @var GetParcelTrackingResponse $response */
$response = $api->getParcelTracking($request);
foreach ($response->getEvents() as $event) {
    printf("%s - %s - %s - %s - %s (%s %s) (%s) %s",
        $event->getEventTime()->format(DATE_ATOM),  //data zdarzenia
        $event->getWaybill(),                       //numer listu przewozowego
        $event->getPackageReference(),              //dowolne dane powiązane z przesyłką podane przez wysyłającego
        $event->getParcelReference(),               //j.w. związane z pojedynczą paczką
        $event->getCountry(),                       //kod kraju operacji
        $event->getDepot(),                         //numer oddziału DPD 
        $event->getDepotName(),                     //nazwa oddziału DPD
        $event->getBusinessCode(),                  //kod zdarzenia
        $event->getDescription()                    //opis słowny zdarzenia
    );
    $eventAdditionalData = [];
    if (!empty($event->getAdditionalData())) {      //dodatkowe dane zdarzenia
        foreach ($event->getAdditionalData() as $additionalData) {
            $eventAdditionalData[] = $additionalData->getValue();
        }
    }
    if (!empty($eventAdditionalData)) {
        printf(' [%s]', implode(', ', $eventAdditionalData));
    }
    echo "\n";
}

上述调用的示例效果如下

2020-08-26T09:05:18+00:00 - 0123456789012A -  -  - PL (1349 Warszawa3) (190101) Przesyłka doręczona  [Kowalski]
2020-08-26T07:02:15+00:00 - 0123456789012A -  -  - PL (1349 Warszawa3) (170304) Wysłano powiadomienie
2020-08-26T07:01:46+00:00 - 0123456789012A -  -  - PL (1305 Warszawa) (170309) Powiadomienie SMS [+48000000000, DELIVERED]
2020-08-26T06:38:21+00:00 - 0123456789012A -  -  - PL (1305 Warszawa) (170310) Powiadomienie mail [xxx@xxx.pl, SENT]
2020-08-26T06:19:49+00:00 - 0123456789012A -  -  - PL (1349 Warszawa3) (170102) Wydanie przesyłki do doręczenia [LOK9999WAC]
2020-08-26T00:44:23+00:00 - 0123456789012A -  -  - PL (1349 Warszawa3) (330137) Przyjęcie przesyłki w oddziale DPD  [LOK0002WAC]
2020-08-25T16:16:14+00:00 - 0123456789012A -  -  - PL (1320 Piotrków Tryb.) (330135) Przyjęcie przesyłki w oddziale DPD  [LOK0033PTR]
2020-08-25T14:46:29+00:00 - 0123456789012A -  -  - PL (1320 Piotrków Tryb.) (040101) Przesyłka odebrana przez Kuriera
2020-08-24T15:05:48+00:00 - 0123456789012A -  -  -  ( ) (030103) Zarejestrowano dane przesyłki, przesyłka jeszcze nie nadana

g-tools / dpd-pl-api

维护者

详细信息

README

安装

使用方法

使用方法

0. 连接到 API

1. 注册包裹

GeneratePackageNumbersRequest

Package

GeneratePackageNumbersResponse

2. 下载标签

GenerateLabelsRequest

GenerateLabelsResponse

3. 生成交付协议

GenerateProtocolRequest

GenerateProtocolResponse

4. 检查快递员可用时间

5. 订单快递员取件

由第三方安排收件

CollectionOrderRequest

CollectionOrderResponse

跟踪包裹

GetParcelTrackingRequest

GetParcelTrackingResponse