README

该 DHL 商业客户发货 API SDK 包提供了一个到以下 Web 服务的接口

• Geschäftskundenversand 3.1.2
• DHL 包裹 DE 发货 2.1.6

要求

系统要求

• PHP 7.2+ 且包含 SOAP 和 JSON 扩展

包要求

• league/openapi-psr7-validator：JSON 请求消息的架构验证器
• netresearch/jsonmapper：将 JSON 响应消息反序列化为 PHP 对象的映射器
• php-http/discovery：HTTP 客户端和消息工厂实现的发现服务
• php-http/httplug：可插拔的 HTTP 客户端抽象
• php-http/logger-plugin：HTTPlug 的 HTTP 客户端记录插件
• psr/http-client：PSR-18 HTTP 客户端接口
• psr/http-factory：PSR-7 HTTP 消息工厂接口
• psr/http-message：PSR-7 HTTP 消息接口
• psr/log：PSR-3 日志接口

虚拟包要求

• psr/http-client-implementation：任何提供 PSR-18 兼容 HTTP 客户端的包
• psr/http-factory-implementation：任何提供 PSR-7 兼容 HTTP 消息工厂的包
• psr/http-message-implementation：任何提供 PSR-7 HTTP 消息的包

开发包要求

• nyholm/psr7：PSR-7 HTTP 消息工厂和消息实现
• phpunit/phpunit：测试框架
• php-http/mock-client：HTTPlug 模拟客户端实现
• phpstan/phpstan：静态分析工具
• squizlabs/php_codesniffer：静态分析工具

安装

$ composer require dhl/sdk-api-bcs

卸载

$ composer remove dhl/sdk-api-bcs

测试

$ ./vendor/bin/phpunit -c test/phpunit.xml

功能

DHL BCS API SDK 能够连接到旧版 商业客户发货 SOAP API 以及其继任者，即 包裹 DE 发货 REST Web 服务。

虽然连接到 REST API 包含了一些在 BCS v3.1.2 之后引入的发货服务，但两种连接都共享相同的高级功能

• 验证发货：验证发货订单而不预订标签
• 创建发货订单：预订发货标签
• 删除发货订单：取消发货标签

请注意，在某些情况下，包裹 DE 发货 REST API 使用不同的参数

• 沙盒凭据和 EKP
• 国家必须以三位字母代码指定

身份验证

这两个 API 都需要两级身份验证来识别应用程序和用户。API SDK 提供了一个身份验证存储来传递凭据。

// BCS
$authStorage = new \Dhl\Sdk\Paket\Bcs\Auth\AuthenticationStorage('appId', 'appToken', 'user', 'signature');

// Parcel DE Shipping
$authStorage = new \Dhl\Sdk\Paket\Bcs\Auth\AuthenticationStorage('', 'apiKey', 'user', 'password');

• API 用户凭据（用户和签名/密码）在 DHL 商业客户门户 中创建
• SOAP 访问：应用程序 ID 和令牌在 开发者门户 中创建
• REST 访问：API 密钥在 API 开发者门户 中创建

API 选择

默认情况下，SDK 连接到旧版 商业客户发货 SOAP API。要切换到 REST Web 服务，请向服务工厂传递一个额外的参数

$serviceFactory = new \Dhl\Sdk\Paket\Bcs\Service\ServiceFactory(
    \Dhl\Sdk\Paket\Bcs\Api\ServiceFactoryInterface::API_TYPE_REST
);

在创建输出消息时使用请求构建器，同样也要在那里传递相应的参数

$requestBuilder = new \Dhl\Sdk\Paket\Bcs\RequestBuilder\ShipmentOrderRequestBuilder(
    \Dhl\Sdk\Paket\Bcs\Api\ShipmentOrderRequestBuilderInterface::REQUEST_TYPE_REST
);

有关使用服务工厂和请求构建器的更详尽示例，请参阅关于Web服务操作的部分。

Web服务操作

验证运输

验证DHL Paket的运输以及相关运输文件。

公共API

适合消费的库组件包括

• 服务
  • 服务工厂
  • 运输服务
  • 数据传输对象构建器
• 数据传输对象
  • 身份验证存储
  • 订单/标签设置
  • 带有状态消息的验证结果

使用方法

$logger = new \Psr\Log\NullLogger();

$serviceFactory = new \Dhl\Sdk\Paket\Bcs\Service\ServiceFactory();
$service = $serviceFactory->createShipmentService($authStorage, $logger, $sandbox = true);

$requestBuilder = new \Dhl\Sdk\Paket\Bcs\RequestBuilder\ShipmentOrderRequestBuilder();
$requestBuilder->setShipperAccount($billingNumber = '22222222220101');
$requestBuilder->setShipperAddress(
    $company = 'DHL',
    $country = 'DE',
    $postalCode = '53113',
    $city = 'Bonn',
    $street = 'Charles-de-Gaulle-Straße',
    $streetNumber = '20'
);
$requestBuilder->setRecipientAddress(
    $recipientName = 'Jane Doe',
    $recipientCountry = 'DE',
    $recipientPostalCode = '53113',
    $recipientCity = 'Bonn',
    $recipientStreet = 'Sträßchensweg',
    $recipientStreetNumber = '2'
);
$requestBuilder->setShipmentDetails($productCode = 'V01PAK', $shipmentDate = '2019-09-09');
$requestBuilder->setPackageDetails($weightInKg = 2.4);

$shipmentOrder = $requestBuilder->create();
$result = $service->validateShipments([$shipmentOrder]);

创建运输订单

创建DHL Paket的运输以及相关运输文件。除了主要运输数据（发货人、收件人等）外，还可以通过订单配置对象定义进一步设置，包括标签打印尺寸、配置文件等。

公共API

适合消费的库组件包括

• 服务
  • 服务工厂
  • 运输服务
  • 数据传输对象构建器
• 数据传输对象
  • 身份验证存储
  • 订单/标签设置
  • 带有运输/跟踪号和标签的运输

使用方法

$logger = new \Psr\Log\NullLogger();

$serviceFactory = new \Dhl\Sdk\Paket\Bcs\Service\ServiceFactory();
$service = $serviceFactory->createShipmentService($authStorage, $logger, $sandbox = true);

$orderConfiguration = new \Dhl\Sdk\Paket\Bcs\Service\ShipmentService\OrderConfiguration(
    $printOnlyIfCodable = true,
    $combinedPrinting = null,
    $docFormat = \Dhl\Sdk\Paket\Bcs\Api\Data\OrderConfigurationInterface::DOC_FORMAT_PDF,
    $printFormat = \Dhl\Sdk\Paket\Bcs\Api\Data\OrderConfigurationInterface::PRINT_FORMAT_A4
);

$requestBuilder = new \Dhl\Sdk\Paket\Bcs\RequestBuilder\ShipmentOrderRequestBuilder();
$requestBuilder->setShipperAccount($billingNumber = '22222222220101');
$requestBuilder->setShipperAddress(
    $company = 'DHL',
    $country = 'DE',
    $postalCode = '53113',
    $city = 'Bonn',
    $street = 'Charles-de-Gaulle-Straße',
    $streetNumber = '20'
);
$requestBuilder->setRecipientAddress(
    $recipientName = 'Jane Doe',
    $recipientCountry = 'DE',
    $recipientPostalCode = '53113',
    $recipientCity = 'Bonn',
    $recipientStreet = 'Sträßchensweg',
    $recipientStreetNumber = '2'
);
$requestBuilder->setShipmentDetails($productCode = 'V01PAK', $shipmentDate = '2019-09-09');
$requestBuilder->setPackageDetails($weightInKg = 2.4);

$shipmentOrder = $requestBuilder->create();
$shipments = $service->createShipments([$shipmentOrder], $orderConfiguration);

删除运输订单

取消之前创建的运输。

公共API

适合消费的库组件包括

• 服务
  • 服务工厂
  • 运输服务
• 数据传输对象
  • 身份验证存储

使用方法

$logger = new \Psr\Log\NullLogger();

$serviceFactory = new \Dhl\Sdk\Paket\Bcs\Service\ServiceFactory();
$service = $serviceFactory->createShipmentService($authStorage, $logger, $sandbox = true);

$shipmentNumber = '222201011234567890';
$cancelled = $service->cancelShipments([$shipmentNumber]);