Skip to main content
首页博客指南跟踪 API 应返回哪些数据?当前状态之外的 12 个字段?

跟踪 API 应返回哪些数据?当前状态之外的 12 个字段?

17TRACK

跟踪 API 返回的内容不应只有“运输中”这样的标签。除了当前状态之外,还应关注货件标识符、承运商身份、详细状态信息、承运商原始消息、事件历史记录、事件时间戳、地点、预计送达时间、异常情况、承运商交接信息、配送详情以及数据新鲜度元数据。这 12 组数据结合起来,可以帮助开发者构建可靠的工作流程,并为运营团队提供足够的上下文来采取行动。

跟踪 API 应返回哪些数据:除当前状态外的 12 个字段

这是面向开发者、技术采购人员和电商运营团队建议的响应契约,并不表示每家承运商或每个 API 都会提供所有字段。有些值确实可能无法获取。更好的设计是明确指出这些缺失,而不是用假设填补空白。

什么样的跟踪数据才有用?

当前状态只能回答一个狭窄的问题:货件的概括状态是什么?它不一定能说明发生了什么、何时发生、信息是否最新,或接下来应该采取什么行动。

例如,两件货件都可能显示“运输中”,但需要采取不同的响应措施。一件可能刚刚完成设施扫描,且没有报告任何问题;另一件可能在事件历史记录中存在尚未解决的地址问题。只读取标题状态的应用可能会忽略这一差异。

应围绕三个实际任务评估响应:将货件匹配到正确的订单、准确解释其进度,以及判断是否有理由采取行动。以下字段可以支持这些任务。字段名称仅作示例,并非通用标准或某个特定提供商的模式。

除当前状态外需要评估的 12 个字段

1. 货件和跟踪标识符

响应应标识所描述的货件。实用的值包括提交的跟踪号码、API 的跟踪记录标识符,以及你的系统可以映射到履约记录或包裹记录的客户参考编号。

不要假设一个订单等于一件货件。一个订单可能拆分为多个包裹,换货也可能产生另一件货件。应在包裹或履约层级存储跟踪记录,然后将其与订单关联。请将跟踪号码作为字符串保存,以免格式和前导零丢失。

2. 承运商身份

除了易读的承运商名称外,还应查找稳定的承运商标识符。在可用的情况下,响应应区分由你的应用明确提供的承运商和通过自动检测选定的承运商。

承运商上下文对于解释跟踪号码及其事件非常重要。如果检测结果存在歧义,你的集成应提供解决方式,而不是将不确定的匹配默默呈现为已确认结果。请单独保留服务级别信息:仅凭承运商名称无法确定货件使用的是快递、邮政还是其他服务。

3. 标准化状态详情

除主要状态外,还应请求有文档说明的详细代码或子状态。较宽泛的类别可能将货件描述为异常,而详细状态则会指出是尝试派送、地址问题还是海关相关的扣留。

业务逻辑应使用稳定代码,展示时使用易读标签。确认提供商如何将承运商事件映射到这些代码,包括如何处理未知或未映射事件。标准化标签可以让不同承运商的数据源更易于使用,但不应抹去支持团队需要了解的差异。

4. 承运商原始消息和代码

在承运商提供时,应保留原始事件描述和承运商事件代码。这些值可以为支持人员提供标准化状态中可能缺失的上下文,尤其是在承运商使用特定运营术语时。

请将原始文本与翻译或改写后的描述分开保存。否则,面向客户的解释可能会被误认为是承运商的确切措辞。展示承运商文本时,应将其视为不受信任的输入:进行适当转义,不要将其渲染为可执行 HTML。

5. 跟踪事件历史

有用的响应应公开货件时间线,而不仅是最新事件。理想情况下,每个事件都应包括标识符、状态或代码、描述、时间戳以及可用的地点信息。

确认 API 返回的是完整历史记录、有限时间窗口,还是分页结果。同时明确更正记录和重复观测的表示方式。除非响应契约明确保证排序,否则应用不应假设第一项始终是最新记录。

6. 事件时间戳和时区信息

事件发生时间不同于 API 接收或返回该事件的时间。在可用时应同时保留这两个时间。这个区别有助于解释为什么刚刚收到的更新可能描述的是更早发生的事情。

请求带有明确 UTC 偏移量或 UTC 标记的时间戳。RFC 3339 定义了适用于互联网协议的时间戳格式,包括数字时间偏移量。如果数据源只提供没有已知偏移量的当地时间,应保留这种不确定性,而不是默默将其视为 UTC。如果底层数据源只提供日期,绝不要暗示其具有秒级精度。

7. 事件地点和货件地理信息

在数据提供时,应查找城市、地区、国家和邮政编码等结构化地点组件。如果将地点转换为结构化字段可能丢失含义,也应保留原始地点字符串。

扫描地点不一定是包裹的实时位置。同样,最后报告的设施也不能证明包裹仍在那里。面向客户的页面应将其描述为最近一次报告的地点。避免根据不完整的扫描文本推断坐标或确切配送地址。

8. 预计送达日期或时间窗口

预计送达字段应说明其中包含单个日期还是时间窗口、由谁生成,以及最后更新时间。承运商提供的预计时间和单独计算的预测结果应保持可区分。

不要将只有日期的预计时间转换为精确到达时间。你的集成还应处理已修改或撤回的预计时间,避免在跟踪页面上保留过时的承诺。如果不存在预计时间,应显示其不可用,而不是基于未经支持的假设进行计算。

9. 异常原因和所需行动

异常信息应解释问题,并在数据源支持的情况下指出行动、责任方或截止时间。一般性的延误通知与要求收件人提供信息,在运营层面是不同的。

应将报告的事实与自身的工作流决策分开。例如,企业可能会在一段配置的时间内没有更新后创建支持任务。这是内部升级规则,并不代表承运商已宣布包裹丢失。不要从含义模糊的跟踪文本中生成付款指示或敏感信息请求。

10. 承运商交接和相关跟踪号码

当货件在运营商之间转移时,有用的数据包括下一承运商、关联跟踪号码,以及原始记录与后续记录之间的关系。当配送环节使用不同标识符时,这些信息有助于保持连续性。

应将报告的交接视为一种关系,而不是覆盖原始承运商。不要仅因为目的地或跟踪号码看起来相似就合并记录。如果该关系没有被提供或以其他方式确认,应保持未解决状态,而不是凭空创造一段连续旅程。

11. 配送结果和证明引用

报告已送达时,响应应提供记录的送达时间和任何可用的配送详情,例如安全放置地点描述或收件人类别。在承运商和服务允许的情况下,配送证明引用也可能很有用。

不应将“已送达”状态视为目标收件人亲自接收包裹的证明。签名、照片、姓名和精确地点可能包含个人信息。应限制访问权限,避免在公开跟踪页面上暴露这些详情,并确认配送证明链接的授权或有效期要求。

12. 新鲜度、检索状态和响应元数据

请求足够的元数据,以区分最新货件事件和最近一次成功的数据检索。实用的值包括上次成功检查时间、上次失败尝试时间、响应生成时间,以及返回的数据是否为缓存数据或部分数据。

API 请求成功本身并不能证明承运商发布了新的扫描记录。HTTP 响应语义描述的是请求结果;货件进度属于应用数据。应将检索错误与货件异常分开保存,以免临时连接问题变成错误的送达提醒。

缺失数据需要明确含义

字段是否存在只是契约的一部分。你的团队还需要理解缺失值代表什么。预计送达时间可能是数据源无法提供、尚未检索到,或在货件送达后不适用。这些情况不应自动生成相同的客户消息。

  • 未知:尚未确定该值。
  • 未提供:数据源未在检索到的数据中提供该值。
  • 不适用:该字段不适用于此记录或状态。
  • 检索失败:系统无法完成相关查询。

这些是建议的区分方式,而不是强制使用的字面值。无论选择何种表示方式,都应对其进行记录说明。避免使用占位日期、看起来像有效记录的空对象,以及可能被误认为真实地点的默认坐标。

集成前如何测试响应

评估来自企业实际使用的承运商、服务和运输路线的真实负载。模式可以列出可选字段,但不保证每个底层数据源都会填充这些字段。对于 17TRACK 集成,请使用官方 Tracking API 文档检查响应契约,不要将本指南中的概念性字段名称当作可直接复制使用的参数。

  1. 构建具有代表性的样本。包括新注册的货件、运输中的货件、尝试配送的货件、已完成配送的货件,以及可用的交接案例。
  2. 将字段追溯到事件。确认所显示的状态、最新事件和配送详情描述的是一致的记录。发现差异时应进行调查,而不是将其隐藏。
  3. 测试延迟和重复更新。重新处理相同负载,并在较新事件之后收到较旧事件。确认这两种情况都不会创建重复通知或错误地回退显示状态。
  4. 测试缺失和格式错误的值。包括缺失的预计时间、未知地点、不熟悉的状态代码和不完整的时间戳。应用应在不凭空创造替代值的情况下保持可用。
  5. 将传输失败与跟踪结果分开。身份验证失败、超时或格式错误的响应应进入集成错误流程,而不是货件异常工作流。
  6. 验证客户视图。检查内部引用、原始诊断详情和个人信息不会泄露到公开页面或通知中。

对于基于 webhook 的更新,还应根据提供商文档检查交付标识符、身份验证、重试行为和重放处理。这些属于集成要求,而不是货件事实。接收端应安全处理重复交付,不应假设到达顺序等于事件顺序。

验收标准应具有实际意义:你的应用能否在不作出无依据声明的情况下解释货件,你的运营团队能否确定下一步合理行动?一个更小但定义清晰的负载,可能比包含大量无法解释的可选值的大型响应更有用。

常见问题

每件货件都需要填充全部 12 组数据吗?

不需要。配送证据、后续跟踪号码和预计送达日期可能不可用或不适用。应要求清晰的字段定义和可预测的缺失值行为,而不是要求所有字段都必须填充。根据实际运输组合检查最重要的字段。

我们应该存储原始响应,还是只存储标准化字段?

应用逻辑应存储标准化字段。在符合隐私、安全、合同和保留要求的前提下,保留相关源负载也有助于调试和处理映射变化。应限制访问权限,不要仅因为敏感内容出现在响应中就保留它。

哪个时间戳应决定最新事件?

应依据有文档说明的事件时间顺序和提供商排序规则,同时考虑时区和更正记录。接收时间表示你的系统何时获知某个事件,并不一定是事件发生的时间。如果时间戳不完整或相互冲突,应保留这种模糊性,而不是声称存在精确顺序。

跟踪 API 能确认包裹丢失吗?

只有在数据源明确支持这种解释时,才能将丢失视为承运商报告的结果。长时间没有扫描记录可以依据运营规则启动调查,但仅凭沉默不能证明包裹丢失。应将“跟踪信息过时”和“报告丢失”作为两个独立概念。

“已送达”状态足以关闭客户投诉吗?

不能自动这样处理。它确定了报告中的跟踪结果,但可能无法解决收件人的争议。应查看可用的配送详情、客户账户和支持流程。不要将状态标签当作调查冲突信息的替代品。

来源