如何在一个 API 请求中发送多个跟踪号码(批次限制与部分失败)
要在一次 API 请求中发送多个追踪号码,请使用明确支持批量处理的 Tracking API 端点,按照其请求架构格式化每个货件,并将较大的列表拆分为符合文档限制的批次。然后同时检查 HTTP 响应和每个货件的结果:HTTP 请求成功并不一定意味着每个追踪号码都已被接受。仅重试符合条件的失败,并在重新提交整个批次之前协调不确定的结果。

本指南适用于将货件追踪连接到订单管理系统、仓库平台、电子商务应用或内部仪表板的开发者。目标不仅仅是减少请求次数,还要确保每个货件都得到处理,同时避免重复工作或丢失失败记录。
首先,确定批量端点实际执行的操作
追踪集成可能涉及多个不同的操作。注册货件、获取最新追踪信息以及接收后续更新并不是可以互换的操作。
- 注册:提交货件,以便服务开始或继续为其提供追踪。
- 查询:根据端点的检索规则,请求货件的追踪信息。
- 更新配送信息:通过受支持的机制(例如 Webhook)接收后续变更,或通过定时请求获取这些变更。
请查阅文档,确认所需的确切操作。一个接受多条记录的注册端点,并不能说明查询端点也接受相同数量、使用相同架构或共享相同的速率限制。
对于 17TRACK 集成,请从 Tracking API 产品页面开始,并使用官方 API 文档确认操作、身份验证方式、请求格式和响应字段。请将下面的示例视为实现模式,而不是对该 API 合约的替代。
批次限制不仅仅是货件数量上限
Tracking API 没有统一的批次限制。限制可能因提供商、端点、API 版本和账户配置而异。在实现批处理之前,应分别记录这些约束。
| 约束 | 需要确认的内容 | 对实现的影响 |
|---|---|---|
| 每次请求的项目数 | 特定操作允许的最大记录数 | 发送前拆分输入列表 |
| 请求正文大小 | 文档规定的字节限制 | 考虑可选字段和序列化大小 |
| 请求速率 | 规定时间间隔内允许的请求数 | 通过共享限制器控制请求节奏 |
| 并发数 | 是否限制同时发起的请求 | 限制活动工作线程的数量 |
| 用量统计 | 用量按请求、货件还是其他单位计算 | 将用量与请求量分开估算 |
例如,假设某端点允许每次请求包含 25 条记录,则 63 条记录需要发送三次请求,分别包含 25、25 和 13 条记录。这些数字仅用于说明分块方式,并非 17TRACK 规定的限制。
不要假设批处理会减少计费使用量。它可以减少 HTTP 请求开销,但对费用的影响取决于提供商实际的计费规则。同样,有效的批次大小也不代表可以无限并行发送请求。
构建请求前准备记录
大多数可避免的批处理失败都始于输入准备。在将每个货件加入批次之前进行验证,但要避免因规则不当而错误拒绝来自不同承运商的有效追踪号码。
- 将追踪号码保留为字符串。将其转换为数字可能会删除前导零或改变较长的标识符。
- 删除意外的首尾空白。除非相关规范允许规范化,否则不要删除内部字符或改变大小写。
- 验证必填字段。某些工作流可能要求承运商标识符或其他货件信息。仅使用文档规定的字段名称和值。
- 明确去重范围。同一个追踪号码并不一定在每个承运商、商家或历史货件范围内都属于重复项。
- 保留本地货件标识符。即使 API 不接受自定义参考字段,也要存储出库项目与订单或货件记录之间的关系。
对于跨多个网络的 Carrier Tracking,除非针对你的具体工作流这种推断是可靠的,否则不要仅根据追踪号码的长度或前缀推断承运商。如果 API 支持承运商识别,请遵循其文档规定的歧义处理行为。
示例请求结构
以下 JSON 展示了批次负载的概念。包装结构、属性名称和标识符仅为示例,并非 17TRACK 请求架构。某些 API 要求顶层为数组,而不是包含数组的对象。
{
"shipments": [
{
"tracking_number": "EXAMPLE000001",
"carrier_id": "DOCUMENTED_CARRIER_ID"
},
{
"tracking_number": "EXAMPLE000002",
"carrier_id": "DOCUMENTED_CARRIER_ID"
}
]
}通过 JSON 序列化器构建负载,而不是拼接字符串。通过文档规定的机制发送身份验证凭据,并将其排除在源代码管理、浏览器交付的代码和常规日志之外。
在两个层级处理响应
批次请求同时具有传输层结果和应用层结果。你的集成必须同时评估两者。
层级 1:请求是否收到可用响应?
首先检查 HTTP 状态、响应标头和响应正文。身份验证错误、格式错误的请求、速率限制和服务器故障可能会阻止正常的项目处理。网络超时则有所不同:客户端可能不知道服务器是否收到或处理了请求。
HTTP 语义在 RFC 9110 中定义。不过,提供商的文档决定了其应用层结果字段如何对应实际的货件结果。
层级 2:每个货件发生了什么?
如果响应支持项目级结果,请对每条提交的记录进行分类。不要假设 HTTP 200 意味着每条记录都成功,也不要假设结果列表保留请求顺序,除非合约明确保证这一点。
- 已接受:根据端点文档规定的定义,操作已成功。
- 永久性输入失败:在再次尝试之前修正或调查该记录。
- 可重试失败:根据提供商的重试指南安排再次尝试。
- 结果未知:响应缺失、不完整,或无法安全地与提交的记录匹配。
在理解“已注册”或类似重复相关响应的文档含义之前,应将其单独处理。这些响应可能表示所需状态已经存在,但不应自动视为成功的所有权、配置或订阅确认。
处理响应后,每条输入记录都应有且仅有一个本地结果。一个有用的协调检查是:提交记录数等于已接受记录数加永久性失败数、可重试失败数和未知结果数。这是本地记账规则,并不是 API 必须返回的格式。
处理部分失败,避免重新发送已成功的记录
假设一个示例批次包含十个货件:七个被接受,两个缺少有效必填字段,一个遇到文档规定的临时错误。保存七个成功结果,将两个无效记录转交修正,并且仅重试临时失败的记录。
重新发送全部十条记录会产生不必要的流量,并可能使重复处理变得复杂。这也会让区分原始拒绝与后续重复相关响应更加困难。
| 结果 | 建议操作 |
|---|---|
| 字段无效或值不受支持 | 修正输入;不要在输入未改变的情况下重试 |
| 身份验证或权限失败 | 暂停受影响的工作并修复凭据或访问权限 |
| 速率限制响应 | 根据文档指南和适用的响应标头延迟发送 |
| 临时项目级错误 | 以有限的尝试次数和退避策略重试该项目 |
| 提交后超时 | 标记为不确定;进行协调,或使用文档规定的重试安全保证 |
| 无法识别或不完整的结果 | 保留证据并进行调查,而不是假设成功 |
HTTP 429 表示请求过多,其响应可能包含 Retry-After 标头,如RFC 6585 所述。不要假设该标头始终存在。如果没有提供明确的重试延迟,请使用符合 API 文档的有限退避策略。
加入抖动以分散多个工作线程的重试请求,设置最大尝试次数或重试时限,并将超过限制的记录发送到审核队列。无限重试可能会掩盖持续存在的配置问题。
为什么超时需要特殊处理
超时并不能证明请求被拒绝。连接失败之前,服务器可能已经接受了批次。因此,自动重新发送会改变状态的请求可能导致重复处理。
如果端点支持文档规定的幂等键,请遵循其规则,包括键的作用域和保留时间。不要自行创建幂等标头并假设服务器会遵守。否则,请使用受支持的查询或协调工作流,在重新提交之前确定所需状态是否已存在。本地去重有助于协调你自己的工作线程,但不能保证服务器端幂等性。
实用的批处理工作流
将提供商特定的细节放在适配器中,使队列、重试调度器和监控逻辑不依赖原始响应字段名称。
验证记录并保留本地货件 ID
在预期的业务范围内解决重复项
根据文档规定的项目和负载限制拆分记录
通过受限的工作线程池处理每个批次:
发送前持久化一条尝试记录
等待共享速率限制器
使用提供商特定的适配器发送
如果结果不确定:
加入协调队列
继续
对请求级和项目级结果进行分类
为每条提交的记录持久化一个结果
仅安排符合条件的失败进行重试
将无效记录或超过重试限制的记录转交审核
使结果持久化和重试调度具备可恢复性。例如,持久化作业记录或事务性入队模式可以防止进程崩溃导致重试决策丢失。工作线程重启时,应能够区分尚未发送的工作和远程结果仍不确定的工作。
将批次大小作为与相关端点关联的可配置设置,而不是散布在代码库各处的常量。在排查问题或隔离有问题的记录时,较小的批次可能更有用;允许的最大批次并不一定是最佳运行大小。
监控货件结果,而不仅仅是 HTTP 运行时间
API Monitoring 应显示货件是否达到预期状态。只报告 HTTP 成功率的仪表板可能会遗漏成功响应内部的部分失败。
- 项目接受率:已接受记录数除以提交记录数,并明确说明如何处理重试。
- 失败分布:按端点、文档规定的错误代码和相关承运商上下文统计数量。
- 未知结果:尚未协调的记录以及其保持未解决状态的时间。
- 重试积压:待处理重试、最早重试的时间以及已耗尽的尝试次数。
- 请求健康状况:延迟、超时、速率限制和服务器错误。
- 追踪新鲜度:已接受的货件随后是否收到可用的追踪信息。
注册被接受并不代表产生了新的承运商扫描记录。将 API 处理状态与货件流转和数据新鲜度分开,以免将集成事故与配送延迟混淆。
在可用时记录本地批次 ID、货件参考、尝试次数、文档规定的错误代码和提供商请求 ID。对凭据和不必要的个人信息进行脱敏。仅在运营确有必要的地方使用追踪标识符,并避免将原始货件标识符放入高基数指标标签。
上线前测试这些情况
在可用的情况下,使用有文档说明的沙盒或受控测试环境。不要假设虚构的追踪号码会在生产环境中产生可预测的响应。
- 在文档规定的项目限制下提交一个有效批次,然后测试客户端如何阻止超大批次。
- 确认带有前导零的追踪号码在序列化和存储过程中保持不变。
- 测试同时包含已接受和被拒绝项目的批次,并确保不重试已成功的记录。
- 模拟速率限制,并确认多个工作线程遵守同一限制。
- 模拟提交后的超时,并验证协调路径。
- 在收到响应与本地持久化之间重启工作线程。
- 测试缺失、不熟悉或无法匹配的项目结果。
- 确认无效记录会进入可见的修正队列,而不是无限重试。
一个可用于生产的集成应能够说明每个提交货件的状态,包括结果暂时未知的货件。减少请求次数很有用;维护这种可追溯性才是更重要的设计目标。
常见问题
一次请求可以发送多少个追踪号码?
使用确切端点和 API 版本所规定的限制。同时检查请求大小、速率限制以及任何账户特定的约束。对于不同的追踪 API,或同一个 API 中的不同操作,不存在可以安全通用的固定数量。
一个无效的追踪号码会导致整个批次失败吗?
是的,具体取决于端点的验证规则。一些 API 会返回单独的拒绝结果,而另一些可能会在项目处理前拒绝整个请求。请同时检查请求级错误和项目级结果;不要假设每个批次端点都支持部分接受。
HTTP 响应成功时,我应该重试批次吗?
不要自动重试。首先解析文档规定的应用层状态和项目结果。持久化成功记录,并且仅重试符合条件的失败。如果无法安全解释结果,请将其分类为不确定并进行调查。
可以在同一批次中混合不同承运商吗?
只有在端点支持这种请求结构时才可以。确认承运商信息是否按货件提供、是否支持自动识别,以及识别存在歧义时会发生什么。支持多承运商的服务本身并不能确定每个端点的批处理规则。
批处理会让追踪更新更快到达吗?
批处理可以减少应用发送的请求数量,但不会自动使承运商事件更早出现。注册、数据检索、承运商扫描可用性和更新交付是工作流中相互独立的部分。
来源
- 17TRACK Tracking API — 供评估追踪集成的开发者使用的官方产品入口。
- 17TRACK API 文档 — 提供商特定端点合约、限制、身份验证和响应处理的参考。
- RFC 9110:HTTP 语义 — HTTP 状态语义、幂等性、自动重试和 Retry-After。
- RFC 6585:其他 HTTP 状态代码 — HTTP 429 Too Many Requests 及其可选 Retry-After 标头的定义。


