对接地址：https://www.sendlabel.de
鉴权：Authorization: Bearer <API_KEY>
快速开始（最少步骤）
1）管理员在 /admin/api-keys 创建 API Key，并给客户保存。
2）客户可选：调用 /api/v1/senders 创建发件人并设置默认发件人（后续出单无需每次传 sender）。
3）调用 /api/v1/shipments/import 批量导入并触发出单（异步 Job）。
4）轮询 /api/v1/jobs 或查询订单 /api/v1/orders/{orderId} 获取结果。
接口列表
- 创建/查询发件人：GET/POST /api/v1/senders
- 设置默认发件人：POST /api/v1/senders/default
- 批量导入并出单（DHL 校验 + 入队）：POST /api/v1/shipments/import
- 查询任务：GET /api/v1/jobs?ids=job_1,job_2
- 查询订单：GET /api/v1/orders/{orderId}
- 下载面单 PDF：GET /api/v1/labels?orderId={orderId}
承运人/服务（carrier）
- DHL_PARCEL_DE：DHL Paket（德国境内/欧盟）
- DHL_KLEINPAKET：DHL Kleinpaket（仅 DE，≤1kg）
- DP_INTL：Deutschland → International（Deutsche Post International，不含欧盟）
字段兼容（减少对接摩擦）
我们支持常见字段别名。例如 sender 可以用：sender / shipper / ship_from / address_from / from。shipments 列表可以用：shipments / items / orders / packages。这些别名还可以在后台 API Key 的配置中继续扩展。
对于发件人，你可以：（1）每次传 sender 或 （2）传 senderId 或（3）设置 defaultSenderId 后不传 sender。
重要：DHL 校验与错误反馈（含 Leitcode）
我们会在创建前调用 DHL validate，返回尽可能明确的字段级错误。若错误信息包含 Leitcode，通常意味着邮编/城市/街道/门牌号信息不一致或缺失。
注意：DHL 接口有时会返回 warning（例如从旧产品自动纠正到 Kleinpaket）。只要响应中包含面单内容，warning 不应阻止面单落库与发放。
对于“领星/易境通无法拆分 streetName/streetNo”的情况，系统会尝试从 street1 自动拆分出门牌号。 如仍失败，会返回明确错误提示应该显式传 streetName + streetNo。
测试用例 1：创建发件人并设置默认
curl -X POST "https://www.sendlabel.de/api/v1/senders" \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"sender": {
"name": "Sender Name",
"company": "Sender GmbH",
"street1": "Musterstraße 1",
"postalCode": "10115",
"city": "Berlin",
"countryCode": "DE",
"email": "sender@example.com",
"phone": "+4930..."
}
}'
# 返回：{ "ok": true, "senderId": "adr_..." }curl -X POST "https://www.sendlabel.de/api/v1/senders/default" \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{ "senderId": "adr_..." }'测试用例 2：批量导入并触发出单（sender 省略，使用默认发件人）
curl -X POST "https://www.sendlabel.de/api/v1/shipments/import" \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"carrier": "DHL_PARCEL_DE",
"labelPrintFormat": "A4",
"buyerType": "b2b",
"shipments": [
{
"reference": "ERP-0001",
"recipient": {
"name": "Max Mustermann",
"street1": "Dingelberg 18",
"postalCode": "38444",
"city": "Wolfsburg",
"countryCode": "DE",
"email": "max@example.com",
"phone": "+49 176 23414739"
},
"parcel": { "weightKg": 1.8, "lengthCm": 30, "widthCm": 20, "heightCm": 10 }
}
]
}'labelPrintFormat 传 DHL 的格式编号即可。常见值例如 A4 | 210 x 297 mm、A5 | 148 x 210 mm、910-300-600 | 103 x 199 mm、100x70mm | 100 x 70 mm。
成功时每条会返回 orderId + jobId；失败时返回 errors[]（含 DHL 校验信息与提示）。
Excel 批量导入功能（三语说明见下方切换）
系统网页端也支持 Excel 批量导入：在“创建包裹单”页面的「批量导入（Excel）」区域，直接上传 Excel 文件即可。系统会读取第一个工作表并批量加入购物车，再统一支付出单。