README

基于 DHL 原生 REST API 的 PHP 封装，包含三个模块：

目录结构

wiewind-dhl-php-api/
├── composer.json           # 包定义（PSR-4 自动加载、依赖、协议）
├── LICENSE                 # MIT
├── README.md               # 本文件
├── example/
│   ├── shipment.php        # 运单生成示例
│   ├── returns.php         # 退货运单示例
│   └── tracking.php        # 包裹追踪示例
└── src/                    # 全部源码（PSR-4: Wiewind\DHL\ → src/）
    ├── Shipment/
    │   ├── Credentials.php # 连接 + 请求 + 响应解析
    │   ├── Order.php       # 单个运单
    │   ├── Customs.php     # 出口报关声明
    │   ├── Item.php        # 报关商品明细行
    │   ├── Address.php     # 地址基类
    │   ├── Shipper.php     # 发件人（继承 Address）
    │   ├── Consignee.php   # 收件人（继承 Address）
    │   └── Label.php       # base64 PDF/PNG 输出
    ├── Returns/
    │   ├── Credentials.php
    │   ├── Order.php
    │   ├── Shipper.php
    │   ├── Item.php
    │   └── Label.php
    └── Tracking/
        ├── Credentials.php # 连接 + GET 请求 + 响应解析
        ├── Shipment.php    # 被追踪包裹模型
        └── Event.php       # 单条轨迹事件模型

安装

通过 Composer 安装：

composer require wiewind/dhl-php-api

然后引入 Composer 的自动加载器即可，三个模块均通过 PSR-4 按需自动加载：

require 'vendor/autoload.php';

use Wiewind\DHL\Shipment\Credentials;   // 运单
use Wiewind\DHL\Returns\Credentials;    // 退货
use Wiewind\DHL\Tracking\Credentials;   // 追踪

环境要求：PHP ≥ 7.4，并启用 ext-curl、ext-json 扩展。

Shipment 模块（运单生成）

通过 DHL Parcel DE Shipping API v2 生成运单，可返回：运单号、运单 PDF、出口海关报关单 PDF。

类结构

快速开始

完整示例见 example/shipment.php，命令行运行：

php example/shipment.php

核心流程：

$cred = new Wiewind\DHL\Shipment\Credentials('sandbox');   // 或 'production'
$cred->setOrder($order);
$res = $cred->run();

if ($res['success']) {
    $res['shipmentNo'];   // 运单号
    $res['pdfLabel'];     // 运单 PDF（base64）
    $res['customsDoc'];   // 报关单 PDF（base64，仅出口时返回）
}

run() 返回结构

[
  'success'    => 1 | 0,
  'httpCode'   => int,
  'shipmentNo' => string,   // 首个运单（便捷字段）
  'pdfLabel'   => string,   // 首个运单的标签 base64
  'customsDoc' => string,   // 首个运单的报关单 base64
  'shipments'  => [ ['shipmentNo'=>.., 'pdfLabel'=>.., 'customsDoc'=>..], ... ],
  'errorMsg'   => string,   // 失败时
  'errorCode'  => int,      // 失败时
]

文档选项（query 参数）

Credentials 默认请求嵌入式 PDF：

注意事项

• 产品与客户号必须匹配：境内包裹用 V01PAK，国际包裹用 V53WPAK 等；billingNumber = EKP + 业务流程代码 + 参与号。
• 国家代码用 ISO 3166-1 alpha-3（如 DEU、CHN、USA）。
• 出口才需要 Customs：境内包裹不要调用 setCustoms() / addItem()，否则会触发不必要的报关单。

Returns 模块（退货运单）

通过 DHL Parcel DE Returns API v1 生成退货（Retoure）运单，可返回：退货运单号、退货标签 PDF、退货二维码（QR Label）。

类结构

快速开始

完整示例见 example/returns.php，命令行运行：

php example/returns.php

核心流程：

$cred = new Wiewind\DHL\Returns\Credentials('sandbox');   // 或 'production'
$cred->setOrder($order);
$res = $cred->run();

if ($res['success']) {
    $res['shipmentNo'];   // 退货运单号
    $res['pdfLabel'];     // 退货标签 PDF（base64）
    $res['qrLabel'];      // 退货二维码（base64，无纸化退货门店扫码用）
}

run() 返回结构

[
  'success'    => 1 | 0,
  'shipmentNo' => string,   // 退货运单号
  'pdfLabel'   => string,   // 退货标签 base64
  'qrLabel'    => string,   // 退货二维码 base64
  'errorMsg'   => string,   // 失败时
  'errorCode'  => int,      // 失败时
]

注意事项

• setReceiver() 传入的退货收件人编号由 DHL 分配，需与账户对应。
• 国际退货（出口到德国以外）需要 addItem() 提供报关明细；境内退货可省略。

Tracking 模块（包裹追踪）

通过 DHL Shipment Tracking - Unified API 根据运单号查询包裹的当前状态与完整轨迹。

该模块鉴权方式与另外两个不同：仅用 DHL-API-Key 请求头，无需用户名/密码。

类结构

快速开始

完整示例见 example/tracking.php，命令行运行：

php example/tracking.php

核心流程：

require 'vendor/autoload.php';

$cred = new Wiewind\DHL\Tracking\Credentials('production');  // 或 'sandbox'
$cred->setApiKey('your-dhl-api-key');
$cred->setTrackingNumber('00340434161094015902');
$cred->setService('parcel-de');   // 可选：指定服务，缩小范围
$res = $cred->run();

if ($res['success']) {
    foreach ($res['shipments'] as $shipment) {
        $shipment->getStatusCode();    // delivered / transit / pre-transit ...
        $shipment->getStatus();        // 状态文案
        $shipment->isDelivered();      // 是否已签收
        foreach ($shipment->getEvents() as $event) {
            $event->getTimestamp();
            $event->getDescription();
        }
    }
}

run() 返回结构

[
  'success'   => 1 | 0,
  'httpCode'  => int,
  'shipments' => Shipment[],   // Shipment 对象数组（见下方方法）
  'errorMsg'  => string,       // 失败时
  'errorCode' => int,          // 失败时
]

Shipment 常用方法：getTrackingNumber()、getService()、getStatusCode()、 getStatus()、getStatusDetail()、getStatusTimestamp()、getOrigin()、 getDestination()、getEvents()、getLatestEvent()、isDelivered()。

可选查询参数

生产环境配置

两个模块的凭证设置方式一致：

$cred = new Credentials('production');
$cred->setUsername('...');     // DHL 商业账户用户名
$cred->setPassword('...');     // DHL 商业账户密码
$cred->setApiKey('...');       // dhl-api-key（开发者门户申请）

沙箱凭证已内置（DHL 公布的测试账号），可能被 DHL 更换，以开发者门户为准。 沙箱模式下 setUsername / setPassword 不生效，避免误改测试账号。