自定义物流接口配置

谁应该配置

自定义物流接口面向有自建网关或已确认第三方协议的实施团队，不适合门店人员自行试填。生产地址必须使用公网 HTTPS；系统会阻止内网、回环地址、无法解析的域名以及跨域或跨端口的业务端点。唯一允许普通 HTTP 的地址是快递100官方电子面单测试域名。

需要配置的内容

• 服务地址：第三方网关的基础 HTTPS 地址。
• 业务端点：按实际能力配置创建面单、取消面单、查询轨迹和云打印路径。
• 加密凭证：保存 API Key、Token 或签名密钥，保存后不会回显。
• 固定请求头：只放内容类型等非敏感字段。
• 凭证请求头映射：声明某个请求头引用哪一项加密凭证，不能把密钥明文写入固定请求头。
• 响应字段映射：指定运单号、第三方订单号、面单内容、状态、轨迹和错误消息在第三方 JSON 中的位置。
• 回调字段映射：仅在第三方明确采用 ZenTea 的签名合同时配置。

生产取号必须满足幂等

第三方必须把 ZenTea 的取号请求号作为稳定幂等键：同一请求重复提交时返回第一次结果，不能再次分配运单。只有第三方书面确认并完成重复请求测试后，才能启用生产取号。未确认幂等的接口只用于联调。

测试顺序

1. 保存后执行结构检查，确认至少配置了一个业务端点。
2. 如使用回调，先验证本系统签名和事件落库，再从第三方后台向公网地址发送真实回调。
3. 使用第三方沙箱完成取号、取消、轨迹和面单数据解析。
4. 模拟连接超时和重复提交，确认第三方不会分配第二张面单。
5. 最后用正式账号验收，并建立第三方后台的人工核对流程。

常见提示与处理

内置服务商使用官方查询接口轮询，不需要配置通用回调密钥。