DHL 原生请求头示意
原程序通常把请求直接发到 DHL 域名，并携带 DHL 自己的认证头。
POST /orders HTTP/1.1
Host: api-eu.dhl.com
Content-Type: application/json
DHL-API-Key: <DHL_API_KEY>
DHL-API-Secret: <DHL_API_SECRET>
{ ... }SendLabel API Migration
从 DHL 原生接口迁移到 SendLabel API
先看改动量，再决定是走 DHL compat 低改动迁移，还是一步切到 SendLabel 统一接口。
迁移结论
- 如果客户只做单票出单和标签下载，通常只需要改域名、鉴权和少量字段映射。
- 如果客户强依赖 DHL 原生错误码、一请求多票、账号级 manifest 或独立产品线能力，改动会明显增大。
- 最稳妥的顺序通常是先接 SendLabel 的 DHL compat 路由，稳定后再考虑迁到统一接口。
推荐迁移路径
- 阶段 1：先把 Base URL、鉴权头和关键路径切到 SendLabel。
- 阶段 2：优先打通 `orders / labels / senders`，把老系统的主链路先跑通。
- 阶段 3：补幂等键、错误处理和对账口径，再决定是否切统一接口。
常见接口映射
From
To
DHL orders
SendLabel `/api/compat/dhl-parcel-de/orders`
DHL labels
SendLabel `/api/compat/dhl-parcel-de/labels`
DHL senders
SendLabel `/api/compat/dhl-parcel-de/v1/senders`
DHL default sender
SendLabel `/api/compat/dhl-parcel-de/v1/senders/default`
DHL manifests
SendLabel `/api/compat/dhl-parcel-de/manifests`
New unified flow
SendLabel `/api/v1/shipments/import`
迁移对照表
下面这张表按照客户程序最常见的改动点整理，适合直接交给技术同事做接口改造评估。
| 项目 | DHL 原生接口 | SendLabel API | 客户程序需要改什么 |
|---|---|---|---|
| 鉴权 | 直接使用 DHL 的 API Key / Secret / 原生认证头。 | 改为使用 SendLabel API Key，可通过 `Authorization: Bearer <API_KEY>` 等方式传递。 | 必须改请求头和密钥管理方式。 |
| Base URL | 请求 DHL 官方域名。 | 改为请求 SendLabel 域名。 | 必须替换基础域名；建议在配置层单独抽出。 |
| 接口路径 | 按 DHL 原生 Shipping API 的 orders / labels / senders / manifests 组织。 | 优先走 SendLabel 的 DHL compat 路由；新项目也可直接走统一接口 `/api/v1/shipments/import`。 | 至少要调整路径映射。 |
| 出单请求体 | 字段名、嵌套层级和部分枚举遵循 DHL 原生规范。 | 兼容路由会尽量贴近 DHL，但仍会做 SendLabel 侧标准化。 | 通常只需做小幅字段核对；若依赖原始嵌套细节，需要补映射层。 |
| 单次请求多票 | 客户程序可能一次提交多票。 | 当前 DHL compat `orders` 更适合单票镜像迁移；若需要批量，建议改走统一接口。 | 如果原程序强依赖一请求多票，需要拆成逐票调用或切统一接口。 |
| 标签返回 | 可能直接依赖 DHL 返回的 label 文档方式。 | API 客户更适合直接取 `labelBase64`，也支持后续通过标签接口下载。 | 如果原程序假设一定拿到 PDF 文件流，需要补一个 decode 或下载步骤。 |
| Sender 管理 | 直接使用 DHL 账户里的 sender 配置。 | 改为使用 SendLabel sender 体系，但提供 compat sender 接口降低迁移成本。 | 通常需要同步或重建 sender，并调整默认 sender 的设置方式。 |
| Manifest 语义 | 部分客户按 DHL 账户维度理解 manifest。 | SendLabel 当前更偏向客户作用域/本系统作用域的 manifest 视角。 | 如果客户依赖整账号级 manifest 汇总，需要重新确认业务预期。 |
| 地址校验 | 客户可能把原始地址直接交给 DHL。 | SendLabel 会做地址标准化、拆分和必要校验。 | 可能会更早暴露地址问题；建议把错误提示透传给 ERP/WMS。 |
| 错误处理 | 代码里可能直接依赖 DHL 原始错误码和原始响应字段。 | 兼容层错误现在采用双轨结构：尽量保留 DHL 风格字段，同时附加统一的 `sendlabelError` 方便标准化解析。 | 如果客户程序 hardcode 了 DHL 原始错误字段，需要调整；推荐优先读取 `sendlabelError`，保留对原生字段的兼容兜底。 |
| 幂等与重试 | 很多客户只是网络超时后直接重试。 | 建议显式使用 `Idempotency-Key`，由 SendLabel 统一处理重复请求。 | 强烈建议把幂等键纳入 ERP/WMS 请求模型。 |
| 计费与发票 | 原来可能完全由客户与 DHL 自行结算。 | 切到 SendLabel 后，API 出单会进入 SendLabel 的余额/信用额度/周结开票体系。 | 客户侧需要接受新的对账与开票口径，尤其是周结或额度触发开票。 |
| Pickup / Postnumber / Tracking | 部分客户把这些能力与 Shipping 默认绑定理解。 | 这些仍然是需要单独确认的产品线能力，不应和 Shipping 出单混为一谈。 | 如果客户原程序依赖这些接口，要单独确认权限和测试路径。 |
客户实施版逐接口对照
这一段更适合直接交给客户技术人员。每一行都说明推荐迁移目标、头部变化、请求/响应变化，以及改代码的强弱程度。
| 原 DHL 接口 | 推荐 SendLabel 接口 | 头部变化 | 请求变化 | 响应变化 | 改代码强度 |
|---|---|---|---|---|---|
| POST DHL orders | POST /api/compat/dhl-parcel-de/orders | 把 DHL 原生认证头改为 SendLabel API Key 认证。 | 主体结构大体可沿用，但当前镜像版只支持单票；如果原来一次传多票，要拆单或改走统一接口。 | 返回会带 SendLabel 兼容信息与本系统订单语义，不应只按 DHL 原始字段解析。 | 中 |
| GET DHL labels | GET /api/compat/dhl-parcel-de/labels | 同样改为 SendLabel API Key。 | 查询参数建议改为 `shipment` / `shipmentNumber` / `trackingNumber` 或 `orderId`。 | 默认拿到的是 PDF 文件流；如果原程序改成走统一接口，也可以改用 `labelBase64`。 | 低 |
| GET/POST DHL manifests | GET/POST /api/compat/dhl-parcel-de/manifests | 改为 SendLabel API Key。 | 可继续按日期或 shipmentNumber 查询，但它是客户作用域，不是整个 DHL 账号维度。 | 返回的 manifest 文档和映射关系仍可用，但要重新确认业务上是否需要账号级总表。 | 中 |
| GET/POST DHL senders | GET/POST /api/compat/dhl-parcel-de/v1/senders | 改为 SendLabel API Key。 | 需要把客户原本在 DHL 账号里的 sender 迁到 SendLabel sender 体系。 | 响应更偏向 SendLabel 内部 sender 记录，不建议假设其主键与 DHL 原始 sender 标识一致。 | 中 |
| POST DHL default sender | POST /api/compat/dhl-parcel-de/v1/senders/default | 改为 SendLabel API Key。 | 默认发件人不再是 DHL 账号里的默认值，而是 SendLabel Key / 客户侧默认 sender。 | 返回按 SendLabel 侧默认 sender 生效。 | 低 |
| POST DHL batch shipment creation | POST /api/v1/shipments/import | 改为 SendLabel API Key，并建议强制带 `Idempotency-Key`。 | 需要从 DHL 原生结构迁到 SendLabel 统一结构，包括 `carrier`、`shipments[]`、地址与 parcel 字段。 | 响应会变成统一 import 结果模型，包含 `results[]`、执行模式、可能的 `labelBase64` 或本地 orderId。 | 高 |
请求头对照示例
先把头部改对，通常就能完成第一轮联调。下面这三段示意了从 DHL 原生到 SendLabel compat / unified 的最小变化。
SendLabel compat 请求头示意
如果先走低改动迁移，优先把域名和鉴权切到 SendLabel，业务体结构尽量少动。
POST /api/compat/dhl-parcel-de/orders HTTP/1.1
Host: api.sendlabel.example
Authorization: Bearer <SENDLABEL_API_KEY>
Content-Type: application/json
Idempotency-Key: erp-order-20260623-10001
{ ... }SendLabel unified 请求头示意
如果客户愿意做较大重构，统一接口也使用同一套鉴权，但请求体会切到统一模型。
POST /api/v1/shipments/import HTTP/1.1
Host: api.sendlabel.example
Authorization: Bearer <SENDLABEL_API_KEY>
Content-Type: application/json
Idempotency-Key: erp-order-20260623-10001
{ ... }Before / After 请求示例
这一段适合直接发给客户开发同事。可以先按 compat 低改动迁移，如果后续还要统一 UPS / DHL，再切到 unified import。
示例 1：DHL 原生单票请求
这是客户原来常见的思路：直接按 DHL 结构提交一票 shipment。
{
"profile": "STANDARD_GRUPPENPROFIL",
"shipments": [
{
"product": "V01PAK",
"billingNumber": "22222222220101",
"refNo": "ERP-10001",
"shipper": {
"name1": "ACME GmbH",
"addressStreet": "Musterstrasse",
"addressHouse": "12",
"postalCode": "53113",
"city": "Bonn",
"country": "DE"
},
"consignee": {
"name1": "Max Mustermann",
"addressStreet": "Hauptstrasse",
"addressHouse": "8",
"postalCode": "10115",
"city": "Berlin",
"country": "DE"
},
"details": {
"weight": {
"uom": "kg",
"value": 1.2
}
}
}
]
}示例 2：改到 SendLabel compat 的最小改动版本
如果客户想先少改代码，通常保留接近 DHL 的 shipment 结构，只把请求目标切到 SendLabel compat，并确保一次只传一票。
{
"profile": "STANDARD_GRUPPENPROFIL",
"shipments": [
{
"product": "V01PAK",
"billingNumber": "22222222220101",
"refNo": "ERP-10001",
"shipper": {
"name1": "ACME GmbH",
"addressStreet": "Musterstrasse",
"addressHouse": "12",
"postalCode": "53113",
"city": "Bonn",
"country": "DE"
},
"consignee": {
"name1": "Max Mustermann",
"addressStreet": "Hauptstrasse",
"addressHouse": "8",
"postalCode": "10115",
"city": "Berlin",
"country": "DE"
},
"details": {
"weight": {
"uom": "kg",
"value": 1.2
}
}
}
]
}示例 3：改到 SendLabel unified 的重构版本
如果客户准备统一接 UPS、DHL 等多个承运商，就更适合把请求体改成 SendLabel 统一 import 结构。
{
"carrier": "dhl",
"service": "parcel_de",
"shipments": [
{
"shipper": {
"name": "ACME GmbH",
"address1": "Musterstrasse 12",
"postalCode": "53113",
"city": "Bonn",
"countryCode": "DE"
},
"recipient": {
"name": "Max Mustermann",
"address1": "Hauptstrasse 8",
"postalCode": "10115",
"city": "Berlin",
"countryCode": "DE"
},
"parcel": {
"weightKg": 1.2
},
"references": {
"customerReference": "ERP-10001"
},
"options": {
"labelFormat": "pdf"
}
}
]
}示例 4：统一接口返回的关键字段
统一接口的返回不再只是 DHL 原始字段，ERP/WMS 侧通常至少要读取本地 orderId、tracking 与 labelBase64。
{
"results": [
{
"ok": true,
"carrier": "dhl",
"orderId": "ord_123456",
"trackingNumber": "00340434161234567890",
"labelBase64": "<base64-pdf>",
"executionMode": "sync"
}
]
}curl 调用示例
这几段命令适合让客户开发同事先做最小联调。先测通鉴权、路径和标签下载，再回到程序里改正式代码。
curl 示例 1：走 compat 单票出单
适合先低改动迁移的客户，尽量保留原 DHL 风格请求体，只更换目标路径和鉴权方式。
curl -X POST "https://api.sendlabel.example/api/compat/dhl-parcel-de/orders" \
-H "Authorization: Bearer <SENDLABEL_API_KEY>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: erp-order-20260623-10001" \
--data @dhl-compat-order.jsoncurl 示例 2：走 unified import
适合计划统一 UPS / DHL 结构的客户，后续 ERP/WMS 只维护一套承运商无关的请求模型。
curl -X POST "https://api.sendlabel.example/api/v1/shipments/import" \
-H "Authorization: Bearer <SENDLABEL_API_KEY>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: erp-order-20260623-10001" \
--data @sendlabel-unified-order.jsoncurl 示例 3：按追踪号下载标签
如果客户暂时仍保持 PDF 下载流程，可以继续通过 compat 标签接口按追踪号取 PDF 文件流。
curl -L "https://api.sendlabel.example/api/compat/dhl-parcel-de/labels?trackingNumber=00340434161234567890" \
-H "Authorization: Bearer <SENDLABEL_API_KEY>" \
--output label.pdf示例文件说明
如果客户要先按页面里的 curl 做联调，下面这张表可以帮助他们快速知道每个示例文件该放什么内容、对应哪个接口。
| 文件名 | 用途 | 对应接口 |
|---|---|---|
| dhl-compat-order.json | 给 compat 单票出单示例使用，尽量保留原 DHL 风格字段。 | POST /api/compat/dhl-parcel-de/orders |
| sendlabel-unified-order.json | 给 unified import 示例使用，适合准备统一 UPS / DHL 模型的客户。 | POST /api/v1/shipments/import |
| label.pdf | compat 标签下载示例的输出文件名，方便联调时直接落盘检查。 | GET /api/compat/dhl-parcel-de/labels |
字段映射速查表
如果客户开发同事要评估工作量，这张表最有用。左边是 DHL 常见字段，中间是 compat 保留情况，右边是切到 unified 后通常应改成什么。
| DHL 常见字段 | SendLabel compat | SendLabel unified | 说明 |
|---|---|---|---|
| shipments[0].product | shipments[0].product | service | compat 可基本沿用；切 unified 时要改成 SendLabel 的服务标识。 |
| shipments[0].billingNumber | shipments[0].billingNumber | not passed by customer in most cases | compat 下通常仍可保留；unified 一般不要求客户再直接传 DHL 计费号。 |
| shipments[0].refNo | shipments[0].refNo | shipments[0].references.customerReference | 客户自定义参考号建议保留，但 unified 下字段层级会变化。 |
| shipments[0].shipper.name1 | shipments[0].shipper.name1 | shipments[0].shipper.name | compat 保持原样；unified 会收敛成更通用的名字字段。 |
| shipments[0].shipper.addressStreet + addressHouse | shipments[0].shipper.addressStreet + addressHouse | shipments[0].shipper.address1 | unified 更适合单行地址；如原程序分街道/门牌，需要在映射层合并。 |
| shipments[0].consignee.* | shipments[0].consignee.* | shipments[0].recipient.* | 收件人对象在 unified 中会改名为 `recipient`。 |
| shipments[0].details.weight.value | shipments[0].details.weight.value | shipments[0].parcel.weightKg | 重量字段会从 DHL 的嵌套结构变成更直接的 parcel 模型。 |
| label response document | PDF stream from labels endpoint | results[0].labelBase64 | 如果 ERP/WMS 想省一次下载请求，unified 更适合直接读取 base64 标签。 |
| native DHL error fields | compat response + SendLabel wrapper | unified import result/errors | 不要再只按 DHL 原始错误字段写死解析，最好统一做一层适配。 |
成功响应对照
这组示例最适合提醒客户技术同事：迁移后不应只继续按 DHL 原始成功响应字段写死解析。
成功响应示例 1：DHL 原生风格
客户原系统常常直接解析 DHL 返回的 shipment number、label 文档和状态结构。
{
"shipments": [
{
"shipmentNo": "00340434161234567890",
"shipmentLabel": {
"format": "PDF",
"data": "<base64-pdf>"
},
"status": {
"statusCode": 2000,
"statusText": "OK"
}
}
]
}成功响应示例 2：SendLabel compat
compat 会尽量贴近 DHL 语义，但返回里可能同时带有 SendLabel 的兼容包装和本地订单语义。
{
"orderId": "ord_123456",
"trackingNumber": "00340434161234567890",
"labelBase64": "<base64-pdf>",
"Compatibility": {
"provider": "DHL",
"route": "/api/compat/dhl-parcel-de/orders"
}
}成功响应示例 3：SendLabel unified
unified 不再以 DHL 原始响应为核心，而是统一成可同时适配 DHL、UPS 等承运商的结果模型。
{
"results": [
{
"ok": true,
"carrier": "dhl",
"service": "parcel_de",
"orderId": "ord_123456",
"trackingNumber": "00340434161234567890",
"labelBase64": "<base64-pdf>",
"executionMode": "sync"
}
]
}切换前检查清单
- 确认客户是先走 `DHL compat`，还是直接切 `unified import`。
- 给客户生成测试 Key，并要求在所有正式请求里带 `Idempotency-Key`。
- 核对 sender、标签格式、地址字段、参考号长度和错误处理分支。
- 如果客户还有 Pickup / Postnumber / Tracking 依赖，单独做权限与测试确认。
- 在上线前用 dry run 和 live test 各跑一轮，再确认 billing / invoice 口径。