glancu/dpd-pl-api-php

PHP DPD API 客户端

维护者

详情

github.com/Glancu/dpd-pl-api-php

源代码

安装: 244

依赖: 0

建议者: 0

安全: 0

星级: 0

关注者: 1

分支: 23

1.0.6 2022-06-30 10:49 UTC

Requires

Requires (Dev)

MIT 490146b0e5d0a29487cbe33b5c9848fd7964cbc8

  • Tomasz Konarski <tomasz.woop@konar.ski>

This package is not auto-updated.

Last update: 2024-09-19 21:09:03 UTC

README

用于与 DPD 快递公司以下 Web 服务进行通信的 PHP API 客户端

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

安装

最简单的方法是使用 Composer 安装（http://getcomposer.org）。

通过 composer.json 文件

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

或者通过命令行

composer require t3ko/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 t3ko/dpd-pl-api-php

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

例如，guzzle

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

使用方法

使用方式

为了使用 DPD API 正确发送包裹，需要按照以下步骤进行（以下步骤将在后续部分详细说明）

  1. 注册包裹（方法 generatePackageNumbers()）

    向该方法发送构成包裹的物理数据包、寄件人和收件人的数据、额外订购的服务（例如，取件、交付保证等）。作为响应，我们为每个包裹分配运单号。

  2. 为包裹生成标签（方法 generateLabels()）

    在上一步骤中获得的运单号被发送到该方法，从而可以获取用于粘贴在包裹上的标签的 PDF 文件。

  3. 为包裹生成交付给快递员的协议（方法 generateProtocol()）

    与上面一样，将需要发送要一起发送的包裹的运单号。作为响应，API 返回用于将包裹交付给快递员的准备好的协议的 PDF 文件。

  4. 检查快递员在预定投递日期的可用时间（方法 getCourierAvailability()）

    该方法在发送投递地点的邮政编码后，将返回快递员在最近几天内的可用时间段。

  5. 通过快递员预约取件（待定）

    向该方法传递从上面方法获得的日期和时间区间以及取件地点。作为响应，我们将获得取件预约确认。快递员将取走带有步骤 2 中生成的标签的包裹，并签署步骤 3 中生成的交接协议。

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

  • 委托第三方取件
  • 获取投递点列表（待定）
  • 跟踪包裹

0. 连接到 API

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

  • 用户名
  • 密码
  • FID 编号

这些数据在签署协议并声明愿意使用 API 后，可以从您的客户经理处获得。这些数据用于所有三个在本文档开头列出的 Web 服务的认证。

通过构建以下方式使用 API 的 T3ko\Dpd\Api 类对象

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

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

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

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

$api->setSandboxMode(true);

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

测试API需要单独的登录数据（这些数据与客户请求集成API时一起由DPD IT提供）。使用生产数据访问测试端点将导致认证错误。

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

$api->setSandboxMode(false);

1. 注册包裹

GeneratePackageNumbersRequest

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

use \T3ko\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 T3ko\Dpd\Objects\Sender;
use T3ko\Dpd\Objects\Receiver;
use T3ko\Dpd\Objects\Parcel;
use T3ko\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 \T3ko\Dpd\Request\GenerateLabelsRequest;

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

GenerateLabelsRequest

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

  • 使用步骤1中生成的运单号码。
use \T3ko\Dpd\Request\GenerateLabelsRequest;

$request = GenerateLabelsRequest::fromWaybills(['0000092494467Q']);
  • 使用步骤1中DPD分配的包裹识别号码。
use \T3ko\Dpd\Request\GenerateLabelsRequest;

$parcelId = $parcel->getId();
$request = GenerateLabelsRequest::fromParcelIds([$parcelId]);
  • 或使用包裹的reference字段
use \T3ko\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 \T3ko\Dpd\Request\GenerateProtocolRequest;

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

GenerateProtocolRequest

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

use \T3ko\Dpd\Request\GenerateProtocolRequest;

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

GenerateProtocolResponse

将这样构建的请求发送到API将给我们一个类型为GenerateProtocolResponse的对象作为响应，其中同样有一个包含PDF文件内容的fileContent字段

/** @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(\T3ko\Dpd\Objects\Enum\PayerType::THIRD_PARTY());

以及提供此付款人的 FID 号码（实际上与我们用于连接 API 的相同）

$package->setThirdPartyFid(123);

CollectionOrderRequest

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

use \T3ko\Dpd\Request\CollectionOrderRequest;

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

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

use \T3ko\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 \T3ko\Dpd\Request\GetParcelTrackingRequest;

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

GetParcelTrackingRequest

我们将传递运单号来创建传递给此方法的请求对象

use \T3ko\Dpd\Request\GetParcelTrackingRequest;

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

可选地，我们可以指定我们是要查看快递的完整历史记录还是只想查看与它相关联的最新事件

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

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

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

GetParcelTrackingResponse

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

use \T3ko\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