SendLabel x Lingxing
领星 ERP / WMS API 对接说明
这是一页可以直接转发给领星技术团队的说明，重点覆盖测试账号、接口选择、联调顺序和 production 安全边界。
联系信息
SendLabel.de
https://www.sendlabel.de
info@sendlabel.de
+49 151 4581 6823
Depha GmbH, Steinriedendamm 15, Halle 1, Eingang 1, 38108 Braunschweig, Deutschland
导出时间: 2026/08/07 05:21
你将收到什么
管理员会为领星创建或复用一个专属前端账号，并生成一组测试 API Key。
这组资料通常包括：登录邮箱、初始密码（仅新账号）、测试 Token / client_secret、推荐 client_id，以及已开通的渠道。
- 默认只开放测试联调，不默认开放 production。
- 如需真实出单验证，必须由我司按账号单独开启 production。
- 建议先用 validate_only / dry_run 跑通鉴权、地址和字段映射，再申请 production。
测试账号与客户生产账号的边界
当前提供给领星技术团队的这套账号与 Token，主要用于平台级接口联调，目的是先把领星与 SendLabel 的技术对接测试完成。
后续如果有真实客户要在领星系统里使用 SendLabel，不建议长期共用这套测试账号或领星统一 production 凭据。
- 真实客户应先在 SendLabel 网站注册/登录，并提交自己的 API 接入申请。
- 我司审核通过后，会按该客户自己的账号单独开通 production，并创建该客户自己的 production API Key。
- 客户再把自己的 production Key 填入领星系统；这样订单、扣费、风控、审计和取消权限都会归属到该客户自己的账号。
推荐联调顺序
这是最稳妥的路径，能避免对账、扣费和真实面单残留。
- 第一步：先验证鉴权是否通过，并确认请求能命中正确渠道。
- 第二步：使用 validate_only 检查地址结构、必填字段和基础业务校验。
- 第三步：使用 dry_run 获取预计结果、价格和可能的错误分支，但不真实建单。
- 第四步：如需 production 联调，由我司按账号临时放开，并建议配合自动撤销机制。
鉴权方式
推荐直接使用 `Authorization: Bearer <API_KEY>`。如果现有客户端更接近 UPS / DHL 原生方式，也支持兼容头和 client_id 别名。
- `Authorization: Bearer <API_KEY>`
- X-API-Key / X-SendLabel-API-Key
- Basic(base64(prefix:key))
- dhl_<API_KEY_PREFIX> / ups_<API_KEY_PREFIX> client_id aliases
常用接口入口
新系统建议优先使用统一接口。已有原生 UPS / DHL 客户端的系统，可以先使用 compat 路由降低改造量。
- https://www.sendlabel.de/api/v1/shipments/import
- https://www.sendlabel.de/api/v1/orders/{orderId}
- https://www.sendlabel.de/api/v1/orders/{orderId}/tracking
- https://www.sendlabel.de/api/compat/dhl-parcel-de/v1/shipments/import
- https://www.sendlabel.de/api/compat/ups/v1/shipments/import
- https://www.sendlabel.de/api/compat/ups/security/v1/oauth/token
测试请求示例
下面两段命令分别对应统一接口 validate_only 和 UPS compat dry_run。先跑通这两类请求，通常就能确认大部分字段映射是否正确。
curl -X POST "https://www.sendlabel.de/api/v1/shipments/import" \
-H "Authorization: Bearer <API_KEY>" \
-H "X-SendLabel-Execution-Mode: validate_only" \
-H "Idempotency-Key: lingxing-validate-0001" \
-H "Content-Type: application/json" \
-d '{
"carrier": "DHL_PARCEL_DE",
"shipments": [
{
"reference": "LX-10001",
"recipient": {
"name": "Max Mustermann",
"street1": "Lindenstr. 5",
"postalCode": "70173",
"city": "Stuttgart",
"countryCode": "DE"
},
"parcel": { "weightKg": 1.2, "lengthCm": 30, "widthCm": 20, "heightCm": 10 }
}
]
}'
curl -X POST "https://www.sendlabel.de/api/compat/ups/v1/shipments/import" \
-H "Authorization: Bearer <API_KEY>" \
-H "X-SendLabel-Execution-Mode: dry_run" \
-H "Idempotency-Key: lingxing-ups-dryrun-0001" \
-H "Content-Type: application/json" \
-d '{
"carrier": "UPS",
"shipments": [
{
"reference": "LX-UPS-10001",
"recipient": {
"name": "Erika Mustermann",
"street1": "Lindenstr. 5",
"postalCode": "70173",
"city": "Stuttgart",
"countryCode": "DE"
},
"parcel": { "weightKg": 1.5, "lengthCm": 30, "widthCm": 20, "heightCm": 10 }
}
]
}'生产联调与风控
即使 API Key 已具备 production scope，账号级 production 开关如果没有放开，服务端仍会拒绝真实建单请求。
对需要真实出单验证的客户，我们建议开启受控 live test，并配置自动撤销延迟。
- 默认测试账号不开放 production。
- 建议只有专属测试账号才允许 production 联调。
- 建议对真实测试单启用自动撤销，避免持续产生费用。
对接前检查清单
以下清单适合在技术对接 kickoff 前逐项确认。
- 确认联调用的是专属测试账号，而不是管理员账号。
- 确认需要 DHL、UPS 还是两个渠道都开通。
- 确认请求里会稳定携带 `Idempotency-Key`。
- 确认错误处理优先读取统一的 `sendlabelError`。
- 确认 production 联调前已和我司同步自动撤销与费用控制方案。