如何通过 API 注册跟踪号码:请求字段、承运商代码和响应
要通过 API 注册跟踪号码,请发送经过身份验证的注册请求,其中包含货件的跟踪号码,以及在需要时提供承运商标识符。然后检查每个已提交货件的响应,而不仅仅是 HTTP 状态,并保存注册成功、失败或仍不确定的结果。注册会启动跟踪流程,但并不能证明承运商已经扫描包裹,也不能证明跟踪事件已经可用。

本指南面向将订单管理系统、仓储应用或电子商务平台连接到跟踪 API 的开发人员。本文以 17TRACK 作为具体集成示例,并说明针对所选 API 版本,哪些详细信息必须根据文档进行检查。
注册能做什么,以及不能做什么
注册请求会告诉跟踪服务你希望跟踪哪件货物。它不同于购买运输标签、预约揽收或要求承运商创建货件。在典型的集成中,运输流程会先生成跟踪号码,然后你的应用再注册该号码。
请在应用中区分以下三个事件:
- 货件已创建:你的运输系统已分配跟踪号码。
- 注册已接受:跟踪服务已接受该货件进行跟踪。
- 已收到跟踪信息:承运商事件已通过跟踪服务变得可用。
不要仅仅因为注册成功就将订单更新为“运输中”。新创建的标签可能还没有实体揽收扫描。面向客户的货件状态应来自根据状态映射规则解读的跟踪事件,而不是注册响应。
对于 17TRACK 集成,请从跟踪 API 概览开始,并以官方 API 文档作为端点、字段定义、身份验证和响应代码的依据。以下示例重点介绍注册,不涉及获取结果或接收更新等独立任务。
编写 API 调用前准备请求字段
最有用的准备工作,是在运输系统和跟踪集成之间建立一份小型字段契约。确定每个值的来源、是否可以缺失,以及如何进行验证。
| 字段或值 | 用途 | 实施规则 |
|---|---|---|
| 跟踪号码 | 标识要跟踪的货件。 | 以字符串形式存储和传输;保留前导零。 |
| 承运商标识符 | 标识跟踪服务系统中的承运商。 | 使用服务商文档规定的标识符,而不是内部仓库代码。 |
| 内部参考信息 | 将注册与货件记录关联起来。 | 如果有可用的受支持参考字段,请使用它;无论如何都要保留自己的数据库映射。 |
| 其他识别数据 | 当承运商要求提供跟踪号码以外的信息时,可能有助于识别货件。 | 仅提交该集成和承运商文档规定的字段。 |
| API 凭证 | 验证调用账户的身份。 | 将其保存在服务器上,并从应用日志中排除。 |
将跟踪号码视为标识符
绝不要将跟踪号码转换为整数。数字转换可能会删除前导零,而且在某些编程环境中,大数值可能会丢失精度。删除意外的首尾空格,但除非相关文档或承运商格式支持这种规范化,否则不要删除标点符号或更改字母大小写。
调用 API 前验证明显的输入错误:空字符串、意外的换行符,以及被复制到跟踪号码字段中的订单号。不要对所有承运商强制使用统一的长度或字符规则。适用于一个承运商的验证规则,可能会拒绝另一个承运商的有效号码。
将订单参考信息与货件身份分开
一个订单可能包含多个包裹,而替换货件可能会产生另一个跟踪号码。应在货件或包裹层级进行注册建模,而不是假设每个订单只有一个跟踪号码。
如果使用服务商支持的标签或参考字段,最好使用不透明的货件参考信息,而不是客户的电子邮件地址或街道地址。你自己的数据库应继续作为订单、货件、跟踪号码和承运商映射之间的权威关联。
选择正确的承运商代码
承运商代码不一定是通用的行业标识符。跟踪平台识别的值可能不同于运输软件中存储的承运商名称。即使两个系统都使用数字代码,也可能为同一个承运商分配不同的数字。
维护从运输服务到跟踪服务商承运商标识符的明确映射。必要时,区分承运商的地区运营或服务与其更广泛的品牌。仅根据显示名称建立的映射,在运输系统使用别名时可能产生歧义。
- 承运商已知时:在支持的情况下使用文档规定的承运商标识符,尤其是在跟踪号码格式重叠时。
- 承运商未知时:仅通过文档规定的机制使用自动检测。不要假设省略、空字符串、零和 null 表示相同含义。
- 结果看起来不正确时:在重复注册同一号码之前,核对原始标签、运输服务和映射。
自动检测很有用,但不能证明某个承运商实际持有该货件。同样,有效的承运商代码也不能保证所提供的跟踪号码属于该承运商。
应将承运商映射配置化,而不是将其分散在应用代码中。记录上次检查映射的时间,并在每次修改映射时,在回归测试中加入一个已知货件。
示例:提交 17TRACK 注册请求
以下示例展示了 17TRACK v2.2 注册端点、17token 身份验证标头,以及包含一个跟踪号码对象的数组。在部署之前,请确认此版本及其请求要求与您的账户和官方文档一致。跟踪号码是占位符,必须替换为真实的货件标识符。
curl --request POST \
--url 'https://api.17track.net/track/v2.2/register' \
--header "17token: ${TRACKING_API_TOKEN}" \
--header 'Content-Type: application/json' \
--data '[
{
"number": "YOUR_TRACKING_NUMBER"
}
]'此最小示例未展示承运商选择或承运商特定的补充字段。请查看注册文档,确定省略承运商字段时承运商检测的工作方式,以及你的货件是否需要其他信息。如果提供承运商,请使用文档规定的 carrier 字段,以及该 API 版本要求的标识符。
请从服务器端环境运行此请求。不要将令牌嵌入公开店铺、浏览器脚本或分发给客户的移动应用中。环境变量适用于本地示例;生产部署应使用组织的机密管理控制措施。
在提高请求量之前,测试一个已知货件并检查完整响应。然后测试无效输入,以及同时包含有效和无效项目的批次。这些检查可以揭示你的集成是否真正处理了项目级结果,而不是仅仅识别 HTTP 成功响应。
从三个层级读取响应
可靠的响应处理程序需要回答三个不同的问题:请求是否到达服务、服务是否接受了该操作,以及每个货件发生了什么?
1. HTTP 和传输结果
连接超时、TLS 失败或响应中断,并不一定能告诉你服务器是否处理了请求。在能够完成核对之前,应将该结果标记为不确定。HTTP 成功状态确认 HTTP 交换成功,但你仍然需要检查应用响应。
2. 请求级结果
检查 API 文档规定的顶层结果和错误字段。身份验证错误、格式错误的 JSON 和账户限制需要采取不同措施。保存服务商的原始错误代码和消息,不要将所有失败都简化为“跟踪不可用”。
不要假设数字应用代码与 HTTP 状态码含义相同。它们来自不同层级,必须分别解释。
3. 货件级结果
对于批量注册,应处理每个已提交项目。响应可能会区分已接受和已拒绝的货件;解析器应遵循所选版本文档规定的确切架构。不要仅仅因为一个项目成功,就将整个批次标记为已注册。
将服务商响应规范化为自己的稳定应用状态。例如,数据库可以使用 accepted、rejected 和 uncertain。这些是建议的内部状态,并不是 17TRACK 响应中的实际值。根据适当的保留和访问策略,保留原始服务商响应,以便开发人员调查差异。
有用的注册记录应包含内部货件 ID、提交的号码、承运商选择、尝试时间、API 版本、结果以及服务商错误详情。将注册状态与配送状态分开保存。
处理重试,避免形成无限循环
重试策略应取决于失败原因,而不能仅仅取决于是否发生异常。
- 输入无效:重试前更正字段。重复发送未改变的格式错误请求不太可能有帮助。
- 身份验证失败:核实凭证和账户配置。避免反复提交同一个失败批次。
- 速率限制:遵守规定的限制以及适用的重试指示。使用有界退避,而不是立即并行重试。
- 临时服务故障:在定义的尝试次数和时间预算内重试。
- 提交后超时:根据文档规定的 API 行为核对货件注册状态,然后再判断首次尝试失败。
- 与重复相关的响应:检查该货件是否已经注册,以及是否与应用记录正确关联。
除非文档明确规定,否则不要假设注册具有幂等性。应用端去重可以减少意外重复提交,但不能确定服务商的重复处理策略。
使用适合货件模型的内部唯一性规则。仅凭跟踪号码,在不同承运商和较长保留期限内可能不足以作为永久键。保留承运商上下文和自己的货件标识符,并记录如何处理替换货件和更正后的号码。
将注册监控与跟踪更新分开
API 监控应区分集成失败与货件只是没有新的承运商事件。这两种情况需要不同的负责人和不同的修复方式。
对于注册,应监控接受和拒绝数量、错误类别、不确定结果、重试积压以及响应延迟。对于后续跟踪,应分别监控更新接收或获取失败。在了解正常流量和服务商规定的运行限制之前,不要设定数值化告警阈值。
实际的生产检查应回答以下问题:
- 每个等待跟踪的货件是否都有注册记录?
- 每个已接受的注册是否都能追溯到正确的包裹?
- 被拒绝的项目是否会分派给能够更正底层数据的人员?
- 不确定的请求是否会被核对,而不是被放弃或无限重试?
- 面向客户的状态是否根据货件事件生成,而不是根据注册接受结果生成?
- 凭证和不必要的个人信息是否已从日志中排除?
对于电子商务运营,运营交接与 API 调用本身同样重要。开发人员应负责传输和解析失败;运输或履约团队应能够调查错误标签、承运商映射和缺失的货件信息。
常见问题
我可以在承运商首次扫描前注册跟踪号码吗?
注册和承运商扫描是两个独立事件。根据其验证规则,服务可能会在跟踪事件可用之前接受号码。不要将接受视为承运商已收到包裹的证明。
我是否始终需要提供承运商代码?
这取决于 API 文档规定的检测行为和相关货件。如果承运商已知,明确且正确映射的标识符可以减少歧义。如果未知,应使用文档规定的自动检测方法,而不是自行编造承运商值。
为什么 API 返回 HTTP 成功,但货件却失败了?
HTTP 请求可以成功,而应用仍然拒绝某个单独的项目。请读取顶层应用结果和货件级结果。这种区别对于批量请求尤其重要。
注册请求超时时,我应该怎么办?
将结果视为不确定。连接失败前,服务器可能已经处理了请求。检查服务商文档规定的重复行为以及可用的注册或跟踪查询方法,然后在有界策略下进行核对或重试。
注册会自动配置跟踪通知吗?
不要假设会自动配置。注册、跟踪获取和 webhook 配置是独立的集成事项。请核实相关文档,并在依赖其向客户发送通知之前测试完整的更新流程。
来源
- 17TRACK API 文档 — 注册端点、身份验证、请求字段、承运商标识符、响应架构和错误处理的参考。请将实施细节与部署的 API 版本保持一致。
- 17TRACK 跟踪 API 概览 — 跟踪 API 产品和开发者集成资源的官方起点。


