¶ TBS 轨迹接口配置与查询操作指引
适用：旧版员工端。用于查看 TBS 提供的物流进展，不用于创建订单或打印面单。
¶ 一、使用前准备
请先向 TBS 联系人准备以下资料：
- Token：相当于接口的通行证，复制时不要漏字或带入空格，不要公开发送。
- 调用 IP 白名单：由客服或技术人员确认系统实际使用的出口 IP，再请 TBS 开通。不是填写员工电脑的 IP。
- 一票可查询的 TBS 跟踪号：先由 TBS 确认该单号有数据。
使用有权限的员工账号进入旧版。看不到“轨迹接口”时，请联系管理员。
本文图片为旧版真实界面，敏感内容已遮挡。配置截图只演示位置，没有替机构保存配置；轨迹查看截图也不代表 TBS 实时查询成功。
¶ 二、配置 Token（首次使用）
¶ 第 1 步：打开轨迹接口
- 点击右上角 菜单。
- 点击“系统设置”下的 轨迹接口。
注意：页面底部的“轨迹对接设置”是给运单选择承运商与单号类型，不是填写 Token 的入口。
¶ 第 2 步：选择 TBS
在“基本”页的 接口 下拉框中选择 TBS，然后点击 参数。
“基本”页还可设置抓取条件、抓取天数和上网/签收关键字。首次接入不确定时，请先与客服核对，不要照抄其他接口的关键字。是否签收取决于实际轨迹及已有规则，不能只看 TBS 的订单状态。
¶ 第 3 步：填写 Token
- 在 Token 框中粘贴 TBS 提供的完整内容。
- 核对已开通白名单。
- 点击右下角 确定。
截图中的 *** 仅表示隐去内容，不是可使用的 Token。完成后重新打开 TBS 的“参数”页，确认配置已保存。Token 更换后需在此更新，系统不会自动申请或刷新 Token。
¶ 三、给运单选择 TBS
¶ 第 4 步：选择需要查询的运单
- 用页面右上角的单号搜索框找到运单，点击放大镜搜索。
- 勾选目标运单。
- 点击页面底部 轨迹对接设置。
编号 1 为勾选位置，编号 2 为设置入口，编号 3 为后续使用的“立即爬取轨迹”。首次建议只选一票。
¶ 第 5 步：核对承运商和单号类型
- 将 承运商 选择为 TBS。
- 将 单号类型 选择为实际存放 TBS 跟踪号的字段。
- 点击 保存，按页面提示确认。
例如：TBS 跟踪号填写在运单的“转单号”中，就选择“转单号”；如果实际放在“客户单号”中，就选择“客户单号”。不要仅因为截图显示“转单号”就照选。系统会用所选字段里的内容查询，不会自动替换成别的单号。
同一渠道以后都走 TBS 时，也可按配置轨迹抓取在相应报价或代理档案中维护通用规则。涉及多段运输时参考多段轨迹设置。
¶ 四、查询并查看结果
¶ 第 6 步：触发查询
选中已完成设置的运单，点击底部 立即爬取轨迹（见第 4 步图片编号 3），按页面提示操作。
提交后并不代表马上查到数据；需要等待系统处理，再查看该运单。自动抓取按“基本”页所选的抓取条件执行。修改配置不会让所有旧运单立即重新抓取，需要补查时再手动触发。
¶ 第 7 步：查看轨迹
双击运单行打开详情，再点击 轨迹 页签。重点查看 日期、描述、位置。
这张图只演示查看位置；原有轨迹和人员信息已隐藏，不是 TBS 查询成功样本。多个单号查询时，各票结果单独处理，一票失败不会中断后面的单号，请分别检查。
¶ 第 8 步：有疑问时查看轨迹监控
在“轨迹”页点击 眼睛图标，打开 轨迹监控，查看抓取单号、抓取时间及结果。需要核对接口返回时，可点击右下角 抓取报文，并将脱敏后的报错信息交给客服。
这张图是尚无抓取记录的界面示意。“抓取报文”用于检查接口响应，不等同于把结果保存到运单，也不等同于“立即爬取轨迹”。分享报文前，请隐藏 Token、账号、实际单号及个人信息。
¶ 五、怎样判断结果正常
- 先确认查询使用的是 TBS 跟踪号，并且白名单与 Token 都有效。
- 轨迹列表出现有效日期、状态描述、地点，且与 TBS 的记录一致。
- 时间可能包含横杠或斜杠、分钟或秒，系统会按支持的格式读取。没有时间的节点可能不会进入最终轨迹列表，不要以返回条数完全一致作为唯一标准。
- 没有物流节点时，先确认 TBS 是否已有该票数据；不能只凭“没有报错”判断轨迹已齐全。
¶ 六、常见问题
提示“Token 未填，请填写完整”
回到“菜单 → 轨迹接口 → TBS → 参数”补齐 Token，并确认保存。
提示 403 Forbidden，或认证失败
请 TBS 核对 Token 是否有效、系统实际请求出口 IP 是否已开通白名单。白名单未生效时，反复点查询通常不能解决问题。
提示查询单号为空，或找不到该单号
检查“单号类型”是否选对，所选字段是否填写了 TBS 跟踪号，再请 TBS 确认该号可查询。
显示无数据
检查是否已有抓取记录、抓取条件是否满足、是否选对接口与单号。TBS 返回的内容以其实际提供为准，不保证每家末端快递都有完整派送节点。
提示查询地址未配置、响应格式/时间异常，或持续连接失败
把脱敏后的报错信息、操作时间和接口名称提供给客服核查。不要在其他接口中随意改参数。
TBS 已完成，系统却没显示签收
订单状态不等于签收轨迹。先检查真实轨迹描述，再由客服核对签收关键字规则。
¶ 七、脱敏示例文件
下载脱敏示例文件包，解压后包含：
- 配置检查清单（TXT）：用于核对准备资料，不可直接导入系统。
- 轨迹响应结构（JSON）：全部为虚构数据，便于与客服沟通，不代表真实查询结果。
返回：轨迹服务商接口