货件跟踪 API 工作流程:从注册货件到获取跟踪详情
货件追踪 API 工作流始于提交追踪号码和任何必需的承运商信息,检查注册是否成功,等待追踪数据变得可用,然后获取货件状态和事件历史记录。对于生产环境集成,开发者还需要将每条追踪记录关联到订单,处理部分失败,安全地处理更新,并区分已接受的注册与实际的承运商扫描记录。

本指南面向连接电商平台、订单管理系统、仓库应用或客户服务工具的开发者,介绍这一工作流。指南将应用程序设计建议与特定服务商的 API 要求分开说明。对于 17TRACK 集成,请在实现下面的示例前,使用官方 API 文档确认请求架构、身份验证、支持的操作和响应字段。
了解注册执行和不执行的操作
向追踪服务注册货件,意味着提交一个标识符,以便服务根据其 API 合同追踪或管理该货件。这与购买邮资、生成运输标签、预约揽收或将包裹交给承运商并不是同一项操作。
在应用程序中区分以下三种结果:
- 已收到请求:API 已对你的 HTTP 请求返回响应。
- 注册已接受:服务已接受单条追踪记录进行处理。
- 追踪信息可用:服务已拥有你的应用程序可以获取或接收的货件信息。
这些结果不应合并为单一的“成功”标志。已接受的追踪号码可能尚未有任何承运商事件。同样,批量请求的 HTTP 响应成功,也不能证明批次中的每一项都已被接受;应检查服务商定义的应用层结果结构。
1. 准备货件身份信息和 API 配置
在发起注册请求前,确定货件将在你的系统中如何标识。仅使用订单标识符通常是不够的,因为一个订单可能会拆分为多个包裹。为每个货件或包裹建立独立的内部记录,并将该记录关联到相关订单。
有用的内部记录包括以下信息。这些是建议的应用程序字段,而不是 17TRACK 请求架构。
- 内部货件 ID:包裹的稳定标识符。
- 订单参考号:该货件所属的订单或履约记录。
- 追踪号码:承运商签发的标识符,应以文本形式存储以保留前导零。
- 承运商信息:履约系统提供的承运商身份(如已知)。
- 服务商参考号:追踪服务返回的、后续操作所需的任何标识符。
- 注册状态:记录提交处于待处理、已接受、已拒绝还是等待对账状态。
- 追踪状态:最新的货件状态,应与注册状态分开维护。
提交前验证输入。删除意外的首尾空格,但不要根据对承运商格式的假设重写追踪号码。保留原始值以便排查问题。如果已知承运商,应将其映射为服务商文档中规定的承运商标识符,而不是发送非正式的显示名称。
在服务器端配置身份验证。将凭据置于源代码管理之外,分离开发环境和生产环境配置,并从日志中删除机密信息。确认文档中规定的 API 版本、请求限制、批量限制和账户要求,不要借用无关集成中的配置值。
2. 注册货件并记录单项结果
使用服务商文档中描述的注册操作提交追踪记录。仅包含必需字段以及具有明确用途的可选信息。不要仅仅因为订单数据库中存在客户姓名、地址或其他个人数据,就将其发送出去。
以下伪代码展示了应用程序流程。函数名称仅用于说明,并不是 API 端点或 SDK 方法。
shipment = load_internal_shipment(shipment_id)
validate_tracking_input(shipment)
result = tracking_adapter.register(shipment)
if result.item_accepted:
save_registration_result(shipment_id, result)
elif result.outcome_unknown:
schedule_registration_reconciliation(shipment_id)
else:
save_registration_error(shipment_id, result)
route_for_retry_or_correction(result)持久化足够的信息,以便说明发生了什么:内部货件 ID、提交时间、尝试次数、单项结果以及任何服务商请求参考号。不要仅依赖临时工作线程日志。客户服务和运营团队需要一个持久答案,以确认货件是否已成功注册。
逐项处理批量提交
如果 API 支持批量注册,请将每个返回项与原始货件关联。不要因为 HTTP 请求成功完成,就将整个批次标记为已接受。保存已接受的项目,隔离被拒绝的项目,并分别调查结果不明确的项目。
这样可以避免一个格式错误的追踪号码导致已成功记录被不必要地重复提交,也能为运营人员提供需要修正的记录清单。
将超时视为未知结果
超时并不能证明注册失败。连接中断前,服务商可能已经接受了请求。重新盲目提交之前,应使用文档规定的幂等行为、重复处理方式或查询操作来核对结果。
如果服务商对重复请求的处理方式不明确,请使用受控记录进行测试,并在启用自动重试前确认相关约定。在内部对注册任务去重仍然有用,但不能替代理解远程服务如何处理重复请求。
3. 等待首条追踪信息到达
注册被接受后,追踪详情可能不会立即可用。承运商记录实际处理事件之前,运输标签可能已经存在。信息缺失也可能意味着需要检查追踪号码、承运商选择或特定货件的查询要求。
应明确表示这种状态。“已注册;等待追踪信息”比“运输中”或“注册失败”更准确。不要为了填充空白界面而编造预计送达时间或运输事件。
当记录仍为空时,按以下实际顺序进行调查:
- 确认单项注册已被接受。
- 将提交的追踪号码与履约记录进行比对。
- 检查承运商映射以及文档中规定的其他查询要求。
- 在承运商自己的追踪页面上检查同一货件。
- 如果承运商已有事件而你的集成没有,请检查获取响应,并向 API 服务商提供经过脱敏的诊断信息。
不要在没有证据的情况下采用统一等待时间。升级规则应反映运输服务、预期交接流程以及你自身的运营承诺。
4. 获取追踪详情并正确解读
记录可用后,使用其所需的标识符调用文档规定的追踪详情操作。不要假设注册和获取接受完全相同的字段。一些 API 合同会区分追踪号码、承运商标识符和服务商生成的记录参考号。
应用程序应区分三层信息:
- 货件摘要:用于仪表板、订单页面和运营筛选的总体状态。
- 事件历史:单条观测记录,包括事件描述、时间戳以及在有提供时的地点。
- 获取元数据:应用程序接收或获取信息的时间,以及请求是否成功完成。
查询成功意味着获取操作成功,并不表示包裹自上次查询以来已经移动。生成通知或下游工作流前,应将返回的追踪信息与已存储记录进行比较。
将事件时间与获取时间分开保存
将承运商事件对应的时间与系统接收该事件的时间分开存储。今天下午获取的事件可能描述的是更早的扫描。用获取时间替换事件时间,会使旧更新看起来像新的实际移动。
保留原始时间戳和提供的时区偏移。仅在已知时区时,为了比较而规范化时间戳。如果事件没有时区信息,应保留这种不确定性,而不是悄悄分配服务器时区。
在规范化状态旁保留原始含义
规范化状态有助于跨承运商对货件进行分组,但原始事件描述可以更准确地说明运营问题。在可用时应同时保留二者。仅有宽泛的异常类别,可能无法告诉支持人员下一步是检查地址、联系收件人,还是等待下一次更新。
不要根据含糊状态推断送达保证、已确认丢失或特定的海关结果。应根据底层信息和运营政策进行升级处理。
5. 通过轮询或 Webhook 保持记录更新
获取一次详情足以测试连接,但不足以维持货件可见性。生产环境设计需要更新机制。确认所选服务商支持的机制及其附带条件。
使用轮询时,应用程序按计划请求追踪详情。在文档规定的限制内安排请求,避免无理由地反复查询未发生变化的记录,并对可重试失败使用退避策略。客户打开订单页面不应自动触发不受限制的上游请求;页面可以使用已存储的追踪视图,同时由受控的后台进程刷新数据。
如果使用 Webhook,请根据服务商文档规定的验证机制验证传入请求。按照 Webhook 合同,在确认消息前持久化或可靠地排队已接受的消息,然后异步处理事件。
除非文档规定的交付合同另有保证,否则应构建能够容忍重复消息和意外到达顺序的接收器。在可用时使用服务商事件标识符去重。否则,应基于适当的事件字段定义并测试指纹,同时认识到该指纹可能需要根据数据进行调整。
以 Webhook 为主导的集成也可以使用受控获取进行对账。例如,恢复任务可以检查受接收器中断影响的记录。这是一种弹性设计模式,并不意味着可以忽略速率限制或服务商的具体指导。
6. 将追踪信息转化为安全的业务操作
在触发面向客户的操作前,先更新内部货件记录。持久化保存通知和工作流转换记录,确保重复事件不会生成重复消息。
将业务操作映射到有意义的变化,而不是每个 API 响应。新发现的送达事件可能足以触发“已送达”通知。包含相同事件的重复响应则不应触发通知。异常可能需要内部审核,但发送给客户的消息应反映事件实际说明的内容。
定义如何处理在货件被视为完成后收到的事件。不要仅仅因为摘要已达到终止状态,就删除事件历史或永久阻止所有后续更新。保留、对账和通知规则应考虑合法更正,避免已完成的工作流被反复重新打开。
将工作流应用于 17TRACK 集成
对于自定义追踪集成,相关起点是17TRACK Tracking API 页面及其开发者文档。使用产品页面评估服务,使用文档确定实际集成合同。消费者追踪页面不能替代 API 规范。
编写适配器前,确认身份验证格式、注册和获取操作、承运商识别规则、单项响应处理方式以及适用的请求限制。对于基于 Webhook 的处理,还应确认载荷架构、验证流程、确认要求和重试行为。
将这些服务商特定的细节保留在适配器中,不要将对响应字段的假设分散到整个订单系统中。这样,应用程序的其余部分就可以使用注册结果、货件状态、事件历史和上次成功同步等内部概念。
上线前可避免高成本错误的检查
- 已接受但记录为空:界面显示追踪信息待处理,而不是包裹正在运输。
- 批次结果混合:每个货件都有各自持久化的结果。
- 提交后超时:工作线程核对不确定结果,而不是假定失败。
- 重复事件:货件时间线和客户通知保持去重。
- 较早事件稍后到达:保留该事件,不盲目替换较新的摘要。
- 上游服务不可用:客户页面可以显示上次存储的结果,并提供适当的新鲜度提示。
- 承运商映射错误:可以通过文档规定的恢复路径修正记录。
- 拆分订单:每个包裹保留自己的追踪状态和事件历史。
- 凭据或载荷泄露:日志包含诊断参考信息,但不会泄露机密或不必要的个人信息。
实际完成标准并不只是收到成功的注册响应,而是能够追踪包裹从提交到更新的全过程,解释空结果或失败结果,并在处理被中断时恢复,同时不丢失事件或重复执行客户操作。
常见问题
注册追踪号码会创建货件吗?
不会,至少在此处描述的工作流中不会。追踪注册是将已有标识符提交给追踪服务。除非特定 API 明确将其合并,否则标签创建、邮资购买和承运商预约都是独立操作。
为什么注册成功后追踪详情仍为空?
注册被接受和追踪数据可用是不同的条件。承运商可能尚未记录事件,或者需要检查追踪号码、承运商映射或其他查询信息。在将记录视为成功注册前,应检查单项结果。
每次获取状态时都应该注册货件吗?
不要将重复注册作为默认刷新机制。保存已接受的注册状态,并使用文档规定的获取或更新机制。对于更正、重新激活或重复提交,应遵循服务商的明确规则。
应该使用轮询还是 Webhook?
使用符合文档化 API 合同和运营要求的机制。轮询需要受控的请求计划。Webhook 需要安全、可靠的接收器和能够安全处理重复消息的流程。在支持的情况下,Webhook 更新结合针对性对账可以提供实用的恢复路径。
可以将追踪号码作为数据库中唯一的货件标识符吗?
应使用内部货件标识符。将追踪号码和相关承运商上下文作为该记录的属性保存。这样,在不改变内部货件身份的情况下,更容易管理拆分订单、更正后的追踪号码和服务商特定的参考号。
来源
- 17TRACK Tracking API — 用于评估 17TRACK API 集成的官方产品入口。
- 17TRACK API documentation — 关于具体实现请求格式、操作、响应和集成要求的官方参考。本文中的伪代码和内部字段建议是应用程序设计示例,并非该 API 合同的引用。


