如何无需等待 Webhook 即可通过 API 获取最新的货件状态
如需在不等待 webhook 的情况下获取最新可用的货件状态,请向您的物流追踪服务商的货件查询 API 发送经过身份验证的请求。使用响应立即更新您的应用,然后继续启用 webhook 以接收后续变化。需要注意的是,查询通常会获取服务商最新存储的追踪信息;它不一定会触发新的承运商查询。

当客户打开订单页面、客服人员需要获取更新,或您的系统需要从遗漏的通知中恢复时,这种方式非常有用。可靠的实现应结合按需查询、清晰的新鲜度指标,以及防止重复或乱序更新的保护机制。
确定“最新货件状态”的含义
在选择端点之前,请区分以下三种听起来相似但结果不同的操作。
| 操作 | 作用 | 无法确定的事项 |
|---|---|---|
| 读取您自己的数据库 | 返回您的应用已经保存的追踪信息。 | 服务商是否已收到更新的信息。 |
| 查询追踪 API | 获取服务商查询操作可提供的信息。 | 该请求期间是否执行了新的承运商查询。 |
| 请求刷新追踪信息 | 如果服务商提供此操作,则请求再次执行上游查询。 | 承运商是否有新的扫描记录,或刷新是否会同步完成。 |
需要立即获得答案时,请使用查询。只有在需要服务商再次尝试上游查询时,才研究刷新操作。不要认为添加防缓存参数、重复发送请求或发送 HTTP cache-control 标头,就能强制承运商提供新信息。
货件可见性包含多个阶段:承运商记录事件,追踪服务商获取事件,然后您的应用接收或检索事件。直接 API 请求可以避免等待通知送达,但无法消除链路前端产生的延迟。
编写代码前检查查询契约
负责集成追踪服务的是集成该服务的开发人员。请从服务商当前的文档开始,而不是从旧集成示例中复制端点。确认以下细节:
- 货件标识:查询接受追踪号码、内部货件 ID,还是追踪号码与承运商标识的组合?
- 注册要求:货件是否必须先注册才能查询?
- 身份验证:需要使用哪个标头或身份验证机制?
- 响应含义:该操作返回已存储的信息、启动数据收集,还是返回一个需要稍后检查的任务?
- 结果处理:成功的 HTTP 响应是否可能包含货件级失败或待处理结果?
- 使用限制:有哪些速率限制、批量限制和账户特定限制?
- 新鲜度字段:哪些时间戳分别表示承运商事件、服务商更新和响应生成时间?
对于 17TRACK 集成,相关产品是 Tracking API,而不是消费者追踪页面或店铺追踪界面。请使用官方 API 文档确认适用于您集成的追踪信息查询操作、身份验证、请求字段和响应结构。将查询和 webhook 处理视为两条独立的应用路径,但让它们更新同一条货件记录。
避免对刷新行为或查询频率进行硬编码假设。这些细节必须与您实际使用的操作和服务条款相匹配。
通过后端构建按需查询
一种实用设计是在您自己的应用中公开一个经过身份验证的端点。浏览器向该端点请求货件更新;您的服务器检查授权,决定是否需要查询服务商,然后返回标准化结果。
以下路由是您可以在应用中创建的端点示例。它不是 17TRACK 端点,也不是服务商请求规范。
GET /api/orders/{order_id}/shipment-status使用订单标识在服务器上查找货件。不要让调用方仅通过替换请求中的追踪号码,就能获取其他客户的追踪历史。请将服务商 API 凭据保存在后端,而不是浏览器 JavaScript 或移动应用程序包中。
可实现的请求流程
- 授权访问。确认客户或工作人员有权查看订单。
- 确定货件。读取已保存的追踪标识和承运商信息(如适用)。
- 检查本地新鲜度。如果已有近期成功查询,请根据应用的新鲜度策略复用该结果。
- 必要时查询服务商。使用文档中说明的操作,并设置有上限的请求超时。
- 验证结果。同时检查 HTTP 结果和货件级结果。
- 合并信息。使用处理 webhook 事件时相同的标准化和协调规则。
- 返回状态和新鲜度。在可用时包含最新事件时间和上一次成功查询服务商的时间。
本地新鲜度策略是工程决策,并不代表承运商的更新频率。请根据界面需求、服务商限制、货件量和实际查询价值来选择。客户反复点击更新按钮不应创建不受限制的上游请求流。
标准化响应,但不要臆造新鲜度
即使服务商的响应结构不同,您的应用也可以返回稳定的内部格式。以下示例对象是您自己的应用契约,并非实际的服务商负载:
{
"shipment_id": "internal-shipment-id",
"status": "in_transit",
"latest_event_at": null,
"provider_updated_at": null,
"last_successful_query_at": null,
"retrieval_state": "success",
"source": "provider_query"
}只有在明确知道含义时才填写各个时间戳。您的服务器收到响应的时间应记录在查询元数据中;不得将其表示为包裹移动的时间。如果服务商未提供服务商更新时间戳,请保留该字段为空或设为 null,而不要用其他时间戳替代。
对于客户界面,请分开显示以下信息:“最新承运商事件”描述货件活动,而“追踪检查时间”描述应用的检索活动。这种区分可以避免未变化的扫描记录看起来像是新记录。
防止 API 查询和 webhook 相互覆盖
两种机制同时启用后,同一事件可能通过查询和 webhook 到达。它们完成的顺序也可能与启动顺序不同。先发起的查询可能在 webhook 已经提供更新信息后才完成。
不要使用“最后响应获胜”的逻辑。最近收到的负载不一定代表最新的货件状态。
- 共享一条更新管道。让查询结果和 webhook 负载经过相同的验证、标准化和持久化函数。
- 去重事件。优先使用有文档说明的事件标识。如果不存在,则根据事件时间、状态、地点和描述等可用字段构建定义明确的指纹。
- 使用含义明确的排序字段。有文档说明的修订号或序列号,比假设到达时间代表事件顺序更有用。
- 保留历史记录。新收到的事件可以填补历史缺口,而不改变当前货件摘要。
- 允许更正。状态并不是通用的线性阶梯。请遵循有文档说明的更正行为,而不是永久拒绝每一次看似倒退的状态转换。
当事件顺序不确定时,请保留原始负载及其来源以便调查。不要通过捏造事件时间戳或假设所有承运商时间戳使用相同时区来消除歧义。
区别处理缺失数据和失败请求
空结果、状态未变化和请求失败不应向客户显示相同的信息。
查询成功但状态没有变化
保留现有货件状态,并更新上一次成功查询时间。不要仅因为另一次查询完成就生成新的货件事件。如果客户需要更多详情,请显示现有事件历史,并说明没有返回更新的追踪事件。
货件尚无追踪信息
检查是否需要注册、标识和承运商是否正确,以及服务商如何表示等待数据收集。没有事件本身并不能证明追踪号码无效或包裹丢失。保留服务商对未知标识、已注册但等待信息的货件,以及无法处理的请求之间的区分。
服务商请求超时或失败
如果您有之前的有效状态,请返回该状态,并明确说明最新检查未成功。保持之前的成功查询时间戳不变。网络错误不是配送异常,不应改变包裹的业务状态。
对于适当的临时性故障,请使用带退避和抖动的有限重试。不要反复重试无效凭据或格式错误的请求。如果响应提供了 Retry-After,请根据服务商契约和 HTTP 语义解释它。HTTP 规范允许该值表示延迟秒数或 HTTP 日期。
同一货件收到多个请求
合并并发查询,使它们共享一个上游请求。按账户和货件设置限制,并防止自动重试在多个应用层之间成倍增加。如果支持批量操作,请检查每个货件的结果,而不要因为整个批量 HTTP 请求完成就将其视为全部成功。
将轮询作为受控的后备方案
没有 webhook 时,定时轮询可以使数据库保持更新,但需要明确的运行策略。确定哪些货件仍符合条件、失败如何影响计划,以及何时停止常规轮询。
对于大多数集成,混合设计是合理的起点:webhook 处理后台变化,按需查询服务交互式请求,对需要关注的记录执行协调任务。这是架构建议,并不保证对每个账户都能将成本降至最低。
- 优先处理活跃货件和存在未解决检索错误的记录。
- 避免每次定时运行都查询所有历史货件。
- 定义如何处理已完成货件,包括业务所需的任何更正窗口。
- 跟踪查询发现真正新信息的频率。
- 调查 webhook 送达问题,而不是通过不断提高轮询频率来掩盖问题。
监控服务商请求延迟、失败查询、速率限制响应,以及查询数据与 webhook 写入记录之间的差异。同时单独监控最新承运商事件的时间。API 响应成功并不代表追踪信息已经发生变化。
发布前测试工作流
请求成功只是第一项测试。请验证以下可能产生误导性状态更新的情况:
- 按需查询仍在运行时 webhook 到达。
- 两个客户或工作人员会话同时请求同一货件。
- 服务商返回 HTTP 成功,但报告货件级错误。
- 请求失败时,您的应用已经保存了有效追踪信息。
- 事件缺少时区或包含不熟悉的状态代码。
- 承运商更正了此前显示的结果。
- 用户尝试访问属于其他账户的货件。
您的发布标准应是:应用返回已知的最佳货件信息,准确说明其新鲜度,并且在请求失败或乱序到达时不会破坏这些信息。
常见问题
查询 API 会强制承运商扫描或更新包裹吗?
不会。获取追踪信息无法引发实体扫描。请求是否触发上游查询取决于有文档说明的操作。即使支持刷新,如果承运商没有更新事件,也可能返回未变化的信息。
不配置 webhook 可以使用 API 查询吗?
如果服务商支持所需的查询流程,您可以围绕按需请求或轮询构建集成。请先确认注册和查询要求。之后,您的应用将负责决定何时检查、控制请求量以及检测变化。
应该多久轮询一次货件状态?
不存在通用间隔。请选择符合服务商限制、货件量以及尽快发现更新的业务价值的计划。衡量轮询返回新事件的频率,然后进行调整,而不要假设频繁请求会产生更新鲜的承运商数据。
为什么 API 返回了我已经通过 webhook 收到的信息?
两条路径都可能公开同一底层货件记录。webhook 发送通知,而查询按需检索信息。通过两种方式收到同一事件不一定是错误;您的应用应对其进行去重。
更新按钮应该写成“刷新追踪”吗?
只有当该措辞准确描述操作时才应这样写。如果按钮获取的是服务商已存储的数据,“检查更新”更清晰。请将最新承运商事件与应用最近一次成功检查的时间分开显示。
来源
- 17TRACK Tracking API — 本指南所讨论的追踪 API 集成的官方产品参考。
- 17TRACK API documentation — 关于服务商特定操作、身份验证、请求字段和响应处理的参考。
- RFC 9110,第 10.2.3 节:Retry-After — 定义 HTTP 标头的 delay-seconds 和 HTTP-date 形式。


