README

这是一个为DHL商业货运SOAP API（版本3.3）编写的PHP非官方库。

特性

此库以面向对象的方式提供对官方DHL商业货运SOAP API提供的功能的访问。

从版本3.2开始，此库还包括DHL货运跟踪API，以获取已发送货物的跟踪数据。

这些功能包括

• 创建、删除和更新货运标签
• 生成出口文件
• 检查货运数据是否有效
• 将指定日期的报表下载为PDF文件

此库提供的其他功能

• 将返回的状态消息映射到对象，而不仅仅是返回字符串
• 将街道名称和街道/门牌号分开。但这是实验性的。
• 国家代码到国家名称的转换
• 内部函数的PHPUnit测试
• 详细的 文档 页面

从版本3.2开始，此库还包括DHL货运跟踪API，以获取已发送货物的跟踪数据。

这引入了以下新特性

• 获取已发送货物的跟踪数据
• 下载已签收货物的签名图像

入门

技术要求

• PHP 5.6=<
• PHP soap扩展
• Composer

身份验证要求

• DHL开发者账户
• 要获取API密钥，请登录您的DHL开发者账户，并在此处注册您的应用程序。对于生产模式，您还需要请求DHL对您的应用程序进行批准。
• DHL商业客户账户，这是用户将登录并订购货运标签的实际账户。
• 对于跟踪：ZT-Token和该令牌的密码。您可以在DHL商业客户门户的“我的数据”>“跟踪”下获取这些信息。

安装

手动将此存储库添加到您的composer.json要求中，或导航到您的存储库并输入以下命令

composer require christoph-schaeffer/dhl-business-shipping

用法

此库中有3个客户端类：ShippingClient、TrackingClient和MultiClient。MultiClient将这两个客户端组合成一个，这通常是您想要的。因此，我们将其用作基本示例。身份验证凭据存储在2个类中。一个用于商业货运API，一个用于跟踪API。这两个API不相同，需要不同的参数进行身份验证。

创建一个货运客户端凭据对象，并用您的凭据填充它。

use ChristophSchaeffer\Dhl\BusinessShipping\Credentials\ShippingClientCredentials; // Autoload the ShippingClientCredentials class

$shippingClientCredentials = new ShippingClientCredentials(
    'appID',        // In sandbox mode this is your developer ID.
    'apiToken',     // In sandbox mode this is your developer account password.
    'login',        // DHL business customer account name. This is optional and defaults to 2222222222_01 (sandbox)
    'password',     // DHL business customer password. This is optional and defaults to pass (sandbox)
);

创建一个跟踪客户端凭据对象，并用您的凭据填充它。

use ChristophSchaeffer\Dhl\BusinessShipping\Credentials\TrackingClientCredentials; // Autoload the TrackingClientCredentials class

$trackingClientCredentials = new TrackingClientCredentials(
    'appID',        // In sandbox mode this is your developer ID.
    'apiToken',     // In sandbox mode this is your developer account password.
    'ztToken',      // DHL business customer ZT Token. This is optional and defaults to zt12345 (sandbox)
    'password',     // DHL business customer ZT Token password. This is optional and defaults to geheim (sandbox)
);

创建一个客户端对象，并用您的凭据填充它。

use ChristophSchaeffer\Dhl\BusinessShipping\MultiClient; // Autoload the MultiClient class

$client = new MultiClient(
    $shippingClientCredentials
    $trackingClientCredentials
    TRUE,                              // isSandbox
    MultiClient::LANGUAGE_LOCALE_ENGLISH_GB // Set the status message language to english(default is german).
);

货运API的用法（创建货运标签）

以下是对createShipmentOrder函数的简单示例用法。但是请记住，还有许多其他附加功能。有关更多详细信息或其他函数的示例，请阅读文档。

为要发送的每份货运创建一个新的货运订单。

$shipmentOrder = new \ChristophSchaeffer\Dhl\BusinessShipping\Resource\ShipmentOrder();

设置货运详细信息。

$shipmentOrder->Shipment->ShipmentDetails->product = 'V01PAK'; // V01PAK = National package
$shipmentOrder->Shipment->ShipmentDetails->accountNumber = '22222222220101'; // DHL bussiness customer account number
$shipmentOrder->Shipment->ShipmentDetails->ShipmentItem->weightInKG = 1.2; // The weight including packaging
$shipmentOrder->Shipment->ShipmentDetails->shipmentDate = '2020-12-08'; // The shipping date. Must not be in the past

设置托运人地址，以防货物无法送达，将退回该地址。

$shipmentOrder->Shipment->Shipper->Name->name1 = 'DHL Paket GmbH';
$shipmentOrder->Shipment->Shipper->Address->streetName = 'Sträßchensweg';
$shipmentOrder->Shipment->Shipper->Address->streetNumber = '10';
$shipmentOrder->Shipment->Shipper->Address->zip = '53113';
$shipmentOrder->Shipment->Shipper->Address->city = 'Bonn';
$shipmentOrder->Shipment->Shipper->Address->Origin->countryISOCode = 'DE';

设置收货人地址。

$shipmentOrder->Shipment->Receiver->name1 = 'DHL Paket GmbH';
$shipmentOrder->Shipment->Receiver->Address->streetName = 'Charles-de-Gaulle-Str.';
$shipmentOrder->Shipment->Receiver->Address->streetNumber = '20';
$shipmentOrder->Shipment->Receiver->Address->zip = '53113';
$shipmentOrder->Shipment->Receiver->Address->city = 'Bonn';
$shipmentOrder->Shipment->Receiver->Address->Origin->countryISOCode = 'DE';

将最多30个装货订单添加到数组中。

$shipmentOrders = [$shipmentOrder]; // It is possible to send up to 30 shipment orders in one request.

设置请求对象，调用创建装货订单函数并获取其响应。

$request = new \ChristophSchaeffer\Dhl\BusinessShipping\Request\Shipping\createShipmentOrder($shipmentOrders);
$response = $client->createShipmentOrder($request);

要检查请求是否成功，请使用hasNoErrors函数。如果请求本身或任何创建状态对象有错误，您可以显示它们的消息。

if($response->hasNoErrors()): // checks if any error status messages have been returned.
    echo 'Success!';
    foreach($response->CreationStates as $creationState):
        echo 'shipment number: '. $creationState->shipmentNumber;
        echo 'shipment label url:'.$creationState->LabelData->labelUrl; // When the label response type is url
        echo 'shipment label data:'.$creationState->LabelData->labelData; // When the label response type is base64 or ZPL2
    endforeach;
else:
    echo 'An error occured!\n';

    foreach($response->Status as $status): // echo all response status messages.
        echo '\n- '.$status->message;
    endforeach;

    foreach($response->CreationStates as $creationState): // There will be a creation state for each shipment order.
        foreach($creationState->LabelData->Status as $status): // echo all creation state status messages .
            echo '\n-- '.$status->message;
        endforeach;
    endforeach;
endif;

跟踪API的用法

以下为getPieceDetail函数的示例。如果您只想跟踪您自己发送的货物，这是最好的函数，因为它在一个请求中包含了getPiece和getPieceEvents返回的所有数据。但是，此请求仅适用于您使用zt令牌发送的同一商业客户账户的货物编号。

设置请求对象，调用getPieceDetail函数并获取其响应。

$request = new \ChristophSchaeffer\Dhl\BusinessShipping\Request\Tracking\getPieceDetail();
$request->pieceCode = '00340434161094027318';
$response = $client->getPieceDetail($request);

要检查请求是否成功，请使用hasNoErrors函数。如果请求本身或任何子对象没有状态码"0"，即成功，这将返回false。

if($response->hasNoErrors()): // checks if any error status messages have been returned.
    echo 'Success!';
else:
    echo 'An error occured!\n';
    echo $response->error;   // this is the string error message submitted by dhl
endif;

如果您想跟踪您自己未发送的货物，可以使用getStatusForPublicUser函数。此函数包含较少的数据，但适用于所有货物编号。您还可以请求多个货物编号。

请注意，由于某些原因，DHL决定在沙盒模式下禁用此功能。因此，您需要使用生产模式进行测试。

设置您想要请求的件数

$piece1 = new PieceData(); // create the first Piece you want to request
$piece1->pieceCode = '00340435091628083543'; // set the shipment number

$piece2 = new PieceData(); // create the second Piece you want to request
$piece2->pieceCode = '00340435091628083544'; // set the shipment number

$pieces = [$piece1, $piece2]; // combine both pieces into an array

设置请求对象，调用getStatusForPublicUser函数并获取其响应。

$request = new \ChristophSchaeffer\Dhl\BusinessShipping\Request\Tracking\getStatusForPublicUser($pieces);
$response = $client->getStatusForPublicUser($request);

要检查请求是否成功，请使用hasNoErrors函数。如果请求本身或任何子对象没有状态码"0"，即成功，这将返回false。

if($response->hasNoErrors()): // checks if any error status messages have been returned.
    echo 'Success!';

    foreach($response->pieceStatusPublicList as $pieceStatusPublic):
    if(!$pieceStatusPublic->hasNoErrors()) {
        echo 'An error occured with the shipment number'.$pieceStatusPublic->pieceCode.'\n';
        echo $pieceStatusPublic->pieceStatusDesc.'\n';
    }
endforeach;
else:
    echo 'An error occured!\n';
    echo $response->error.'\n';   // this is the string error message submitted by dhl
endif;

文档

• 您可以在这里找到DHL的官方文档。然而，它部分过时且不完整。
• 您可以在这里找到本项目的文档页面。

支持

• 请使用问题选项卡来报告错误和建议。
• 如果您有任何问题，请通过邮件christoph-dietrich@web.de联系我。

许可

本项目受MIT许可许可。请阅读LICENSE文件以获取详细信息。