操作指南 · 物流与打印
京东物流官方直连配置与能力验收
通过京东物流开放平台 OAuth、配送产品、取号、取消、轨迹和云打印模板完成正式接入，区分 UAT 与生产权限。
适用版本：2.1.94 及以上 · 适用端：PC · 2026-08-24 验证
适用人员与前置条件
选择“京东物流（官方直连）”前，企业应在京东物流开放平台完成商家认证、应用创建、对接方案订阅和面单账号开通。ZenTea 的 AppKey、AppSecret、Access Token、对接方案编码（LOP-DN）、配送产品编码、付费方式和云打印模板都属于当前企业自己的京东配置；不要把 UAT 凭证填入生产服务商，也不要在文档、截图或工单中提交完整密钥。
配置步骤
- 在“物流中心 → 接入与发件 → 物流服务商”新增京东物流，选择正式或 UAT 环境。UAT 只能用于联调，不能声明生产取号、打印、取消、轨迹或 COD 能力。
- 填写当前环境的 AppKey、AppSecret，并通过页面“开始京东授权”取得或刷新 Access Token。授权成功后核对 Token 过期时间，不要手工复制另一应用的 Token。
- 填写京东开放平台给出的对接方案编码 LOP-DN、销售平台来源、订单号规则和付费方式。寄方付、到付、月结必须与京东账号已开通的范围一致；页面选项不能替代京东侧授权。
- 在“配送产品”中添加实际开通的产品编码和名称。标快、特快等多个产品应维护在同一京东服务商配置中，并在订单取号时明确选择产品，不能为了显示按钮随意填编码。
- 需要面单时启用云打印，先同步京东云打印模板，再选择当前账号可用的模板编码和打印场景；模板订阅、LOP-DN 和打印权限缺一不可。
- 需要秒级轨迹时，再启用轨迹消息推送并在京东侧订阅对应事件。轮询轨迹查询可以独立验收，推送未配置不影响已经开通的查询能力。
验收结果与边界
先执行配置自检，再用京东允许的 UAT 或正式测试订单分别验证取号、取消、轨迹查询和云打印 PDF。只有正式账号返回运单号、云打印生成可读 PDF、取消成功且轨迹查询成功后，才在生产能力矩阵中启用对应能力。COD 还需要京东侧开通代收业务、结算账号和真实回款验收，不能只勾选 COD。
京东 OAuth 授权属于应用和环境维度，同一个应用在同一环境只能维护一条服务商配置；多个配送产品放在该配置内。不同客户必须使用各自的京东应用或业务账号，不能共享 Access Token、产品权限或月结资料。
常见异常与回滚
| 页面提示 | 处理 |
|---|---|
| 京东 OAuth 返回格式无效或授权失败 | 核对环境、回调配置、AppKey/AppSecret 和授权应用，不要把 Token 发给支持人员 |
| 货品信息或付费方式必填 | 按页面实际字段补齐商品名称、数量、付费方式，并核对京东产品开通范围 |
| 产品编码无效或未授权 | 使用京东开放平台当前应用已订阅且账号已开通的编码 |
| 寄件地址解析失败 | 补齐发件档案和订单的省、市、区、详细地址，确认京东网点覆盖 |
| 云打印没有模板 | 同步模板并确认已订阅云打印方案；不要把其他客户模板编码复制过来 |
| 取号超时 | 进入“取号待对账”查询京东后台，确认结果前禁止重复取号 |
停用或更换 Token 只影响后续请求，历史运单和打印任务保留。生产密钥疑似泄露时，应立即在京东侧撤销或轮换，再在 ZenTea 更新凭证并重新完成自检和一张低风险测试单。