操作指南 · 物流与打印
菜鸟 LINK/TOP 接口配置与错误排查
区分 LINK 与旧版 TOP，隔离正式、预发布和沙箱环境，配置资源、商家与模板。
适用版本：2.1.94 及以上 · 适用端：PC · 2026-08-24 验证
选择协议和环境
新应用使用 LINK 当前协议；TOP 旧版兼容只适用于已经确认仍由旧网关提供服务的历史应用。LINK 的正式、预发布和沙箱必须分别新增服务商配置，已有配置不能原地切换协议或环境。
| LINK 字段 | 说明 |
|---|---|
| App Secret | 必填，用于请求签名 |
| 资源 Code | 必填，作为来源资源标识发送 |
| App Key | 选填，用于识别应用 |
| 菜鸟商家 User ID | 必填的数字 sellerId，不是资源 Code |
| 默认物流公司编码 | 菜鸟 CP Code |
| 面单产品编码 | 平台或承运商发放的产品编码 |
| 面单模板 URL | 完整 HTTP/HTTPS URL，可通过正式接入预检查询 |
TOP 兼容模式需要 App Key、App Secret；实际取号、取消和轨迹通常还需要店铺授权 Session / Access Token。
LINK 配置步骤
- 在菜鸟开放平台的快递数字化能力中开通取号、取消与字段脱敏接口。
- 在 ZenTea 选择 LINK 和正确环境，填写该环境专属的 App Secret、资源 Code 和 sellerId。
- 填写目标承运商 CP Code、产品编码；模板 URL 可以先留空。
- 保存后执行“配置自检”，填写 CP Code。正式环境会尝试查询标准模板、网点、发货地和面单余额，但不会取号。
- 如果应用没有标准模板查询能力，从菜鸟开放平台复制完整模板 URL 后保存。
- 沙箱环境可继续执行测试取号与取消；预发布和正式环境不会从测试入口创建面单。
重要能力限制
菜鸟 LINK 电子面单能力不等于物流轨迹能力。当前应用没有独立轨迹接口时，ZenTea 会拒绝轨迹查询；需要另行申请菜鸟轨迹服务，或使用其他已开通的查询服务商。
菜鸟返回的模板 URL 和打印数据需要交给兼容菜鸟官方组件的本地打印服务。它不是普通 HTML 或图片，不能直接当作浏览器打印或小票代理打印。
常见提示与处理
| 页面提示 | 原因与处理 |
|---|---|
| LINK 资源 Code 尚未配置 | 填写当前环境应用的资源 Code，不能填 sellerId |
| 商家 User ID 必须是正整数 | sellerId 缺失或含非数字；从授权商家资料取得数字 ID |
| 面单模板必须是完整 URL | 填了模板编号或相对路径；改为完整 HTTP/HTTPS 地址 |
| 必须先配置标准面单模板 | 尚未执行模板预检或应用无模板查询能力 |
| 未返回指定承运商模板 | CP Code 错误或应用未开通标准模板查询 |
| 非正式环境不能声明生产能力 | 预发布/沙箱填写了生产能力或代收开关；清空后保存 |
| LINK 未返回运单号 | 资源、sellerId、网点、模板、产品或面单余额不满足 |
| 当前 LINK 未配置轨迹接口 | 只有电子面单能力；另行开通轨迹服务 |
| TOP 取消或轨迹需要 Session | 历史应用缺少店铺授权会话；重新授权并更新 |
沙箱通过不能替代正式账号验收，正式与沙箱的凭证、sellerId 和资源 Code 不得复用。