Search by 
wiewind / dhl-php-api
PHP client for DHL native REST APIs: Parcel DE Shipping v2, Returns v1, and Unified Shipment Tracking.
Maintainers
v1.0.0
2026-06-29 14:08 UTC
Requires
- php: >=7.4
- ext-curl: *
- ext-json: *
README
基于 DHL 原生 REST API 的 PHP 封装，包含三个模块：
| 模块 | 命名空间 | API | 用途 |
|---|---|---|---|
| Shipment | Wiewind\DHL\Shipment |
Parcel DE Shipping v2（POST /parcel/de/shipping/v2/orders） |
生成出/境内运单，返回运单号、运单 PDF、出口海关报关单 |
| Returns | Wiewind\DHL\Returns |
Parcel DE Returns v1（POST /parcel/de/shipping/returns/v1/orders） |
生成退货运单，返回退货运单号、退货标签、退货二维码 |
| Tracking | Wiewind\DHL\Tracking |
Shipment Tracking - Unified（GET /track/shipments） |
根据运单号查询包裹状态与完整轨迹 |
目录结构
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。
类结构
| 类 | 说明 |
|---|---|
Credentials |
连接配置 + 构建请求信封 + 发起请求 + 解析响应 |
Order |
单个运单（产品、客户号、重量、尺寸、海关）；toArray() 自动剔除空字段 |
Customs |
出口报关声明，触发生成报关单 |
Item |
报关商品明细行（描述、数量、价值、原产国、HS 编码） |
Address |
地址基类；Shipper、Consignee 继承它 |
Label |
把 base64 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：
| 选项 | 默认值 | 说明 |
|---|---|---|
docFormat |
PDF |
PDF 或 ZPL2 |
includeDocs |
include |
include=内嵌 base64，URL=返回链接 |
combine |
false |
setCombine(true) 把运单+报关单合并为一个 PDF |
printFormat |
（空） | 标签版式，如 setPrintFormat('910-300-700') |
注意事项
- 产品与客户号必须匹配：境内包裹用
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）。
类结构
| 类 | 说明 |
|---|---|
Credentials |
连接配置 + 发起请求 + 解析响应 |
Order |
退货单（退货收件人、寄件人、参考号、重量、价值、报关明细） |
Shipper |
退货寄件人（即退货的客户） |
Item |
报关商品明细行（国际退货时使用） |
Label |
把 base64 PDF/PNG 保存到文件或输出到浏览器 |
快速开始
完整示例见 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请求头，无需用户名/密码。
类结构
| 类 | 说明 |
|---|---|
Credentials |
连接配置 + 发起 GET 请求 + 解析响应 |
Shipment |
被追踪包裹模型，含当前状态及 Event 轨迹数组 |
Event |
单条轨迹事件（时间、状态码、说明、地点） |
快速开始
完整示例见 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()。
可选查询参数
| 方法 | 说明 |
|---|---|
setService('parcel-de') |
指定 DHL 服务（express / parcel-de / ecommerce / freight 等），加快查询 |
setLanguage('de') |
返回文案语言（ISO 639-1） |
setRequesterCountryCode('DE') |
请求方国家（ISO 3166-1 alpha-2） |
setOriginCountryCode('DE') |
始发国家 |
setRecipientPostalCode('53113') |
收件人邮编（部分服务用于校验） |
生产环境配置
两个模块的凭证设置方式一致：
$cred = new Credentials('production'); $cred->setUsername('...'); // DHL 商业账户用户名 $cred->setPassword('...'); // DHL 商业账户密码 $cred->setApiKey('...'); // dhl-api-key（开发者门户申请）
沙箱凭证已内置（DHL 公布的测试账号），可能被 DHL 更换，以开发者门户为准。 沙箱模式下
setUsername/setPassword不生效，避免误改测试账号。