在提交到 API 前如何验证追踪号码:需要遵循的 7 条规则
在将跟踪号码发送到跟踪 API 之前,应分层验证:规范化输入、检查基本结构、确认承运商上下文、仅在承运商文档规定校验和时应用校验和,并拒绝明显不安全或不完整的值。不要依赖一个通用正则表达式。跟踪号码格式因承运商、服务、国家和货件类型而异,因此有效的验证器应在阻止错误请求的同时,不要拦截使用不熟悉格式的合法号码。
本指南面向将货件跟踪集成到订单管理系统、仓库流程、客户门户或电子商务应用中的开发人员和运营团队。目标并不是在提交之前证明包裹存在。语法验证和货件状态验证是两个独立步骤。
验证可以确认和无法确认的内容
提交前验证器可以识别常见的输入问题,例如空值、意外空格、不支持的字符、长度过长,或将跟踪号码放在错误的字段中。当承运商已知且格式有文档说明时,它还可以识别可能的承运商。
它通常无法确认号码是否属于真实货件、包裹是否已被承运商接收,或该号码当前是否可跟踪。这些问题需要通过承运商或跟踪平台查询。号码可能通过格式检查,但仍可能未被使用、存在细微输入错误、已过期,或关联到不同的服务。
七条规则
1. 在不改变含义的情况下规范化值
用户和上游系统经常会添加前导或尾随空格、换行符、不换行空格或格式字符。在验证之前,应安全地规范化这些内容。常见的第一步是删除周围的空白,并将不可打印的空白转换为普通空格。如果承运商记录的格式允许内部空格或连字符,请决定是在 API 请求中删除它们,还是保留原始值以供显示和审计。
在可行的情况下保留两个值:原始输入和规范值。原始值有助于支持团队调查数据质量问题;规范值用于验证和提交。避免可能改变标识符的转换。除非相关承运商或 API 文档明确支持,否则不要自动将字母转换为数字、替换易混淆字符,或删除所有标点符号。
Unicode 处理需要特别注意。来自其他字母表的视觉相似字符,即使看起来像 ASCII 字母或数字,也可能不被 API 接受。将规范值限制为所选集成允许的字符集,可以避免令人困惑的下游错误。
2. 拒绝未通过基本结构检查的值
在应用承运商特定逻辑之前,检查值是否存在且合理。实用检查包括最小和最大长度、允许的字符类别,以及值是否只包含空白,或是否为“N/A”“TBD”或“test”等占位符。具体限制应来自 API 合约或承运商文档。不要仅因为大多数示例较短,就臆造一个通用最大长度。
结构检查应有意保持保守。例如,只允许数字的规则会拒绝有效的字母数字标识符。要求固定长度的规则可能会拒绝服务变体或国际格式。使用通用检查捕获明显错误,然后仅在承运商和服务已知时应用更具体的检查。
还应在应用程序边界验证数据类型。跟踪号码通常应作为字符串而不是整数处理。数字转换可能删除前导零,并可能在使用定长数值类型的系统中产生精度问题。在完成批准的规范化后,应将值原样保留为字符串。
3. 使用承运商上下文,而不是仅凭号码猜测
不带承运商信息的跟踪号码是一种不明确的输入。不同承运商可能使用重叠的长度、前缀或字符集,对于一个承运商看似合理的格式,对另一个承运商可能无效。如果订单、标签、仓库系统或商家账户已经确定了承运商,只要 API 支持,就应将该上下文与跟踪号码一并传递。
承运商上下文可以改善验证和路由。它能让应用程序选择相关格式规则,减少误匹配,并使错误消息更有用。当多个承运商都可能接受外观相似的值时,它还可以防止将自动检测结果当作事实。
如果承运商未知,请采用两阶段方法。首先运行通用安全检查。接下来,仅通过明确支持承运商检测的 API 流程提交值,或者在业务流程要求确认承运商时将其放入审核队列。除非该映射得到维护并有文档说明,否则不要仅根据前缀静默分配承运商。
4. 仅在规则有文档说明时应用校验和
某些标识符系统使用校验位,但跟踪号码并不受一种通用校验和标准约束。校验和可以检测某些转录错误,但不能证明货件存在。更重要的是,应用错误的校验和算法可能会拒绝有效号码。
只有在相关承运商、服务、标签规范或 API 文档定义了算法以及其覆盖的输入部分时,才实现校验和。记录规则版本,并使用官方示例进行测试。如果没有权威规则,应跳过校验和,而不是根据少量样本中观察到的模式进行猜测。
将校验和结果视为一个信号,而不是完整的验证决定。当规则具有权威性时,检查失败可以作为阻止提交的依据。检查通过后应将值移至下一阶段,而不是将其标记为正在运输的货件。
5. 将格式验证与 API 资格分开
一个值可能格式良好,但仍不适合所调用的端点。提交前,请检查 API 文档中关于必填字段、接受的承运商标识符、身份验证要求、请求限制、重复处理行为,以及服务类型或目的地限制的规定。这些是集成规则,而不是跟踪号码规则,但它们决定了有效标识符能否成功处理。
17TRACK Tracking API 文档说明了这种区分的重要性:开发人员需要遵循平台的请求模型和支持的集成行为,而不是根据跟踪号码的外观自行构造请求。请查阅当前文档,了解端点要求和响应处理:17TRACK API 文档。
将验证错误与传输错误和身份验证错误分开。“跟踪号码格式无效”“未知承运商”“已达到速率限制”和“授权失败”需要不同的处理措施。单一的“提交失败”通用消息会降低重试和运营报告的可靠性。
6. 通过限制输入、去重和安全重试保护 API
验证也是一种运营保障。在解析或记录日志之前强制执行输入长度限制。拒绝控制字符和意外的负载结构。在自己的应用程序边界实施速率限制,以免错误导入产生无法控制的请求激增。
当业务流程不要求重复注册时,应在提交前去重。实用的去重键可能包括规范跟踪号码、承运商、账户和货件上下文。正确的键取决于工作流程;同一标识符有时可能在不同服务或业务记录中重复使用,因此不要假设号码本身始终具有全局唯一性。
对临时故障使用带退避的有限重试,避免重试永久性验证错误。当 API 和架构支持时,存储幂等性或提交记录。记录足够的信息以排查请求,但要保护凭据、客户数据和任何敏感货件详情。验证器应减少重复失败,而不是因过度记录日志造成第二个安全问题。
7. 在提交后确认结果并监控误报
最后一条规则是将提交前验证视为门槛,而不是结论。请求被接受后,检查 API 响应,并保存其状态、请求标识符、承运商关联信息以及任何有文档说明的错误代码。如果平台接受请求但暂时无法返回运输事件,这可能表示处理延迟,而不是号码无效。
为持续无法解析的号码制定后续处理政策。时间窗口应考虑承运商、服务、货件起点和客户服务政策;不存在能够证明号码无效的通用期限。对于缺少承运商、提供商反复报错、承运商结果冲突,或状态与订单记录不匹配的记录,应进行升级处理。
衡量误拒绝和误接受。严格的正则表达式可能减少格式错误的提交,却错误阻止合法货件。宽松的验证器可能增加接受的请求,但在下游产生噪音。按承运商和服务检查失败样本,通过版本控制更新有文档说明的规则,并使用具有代表性且保护隐私的固定测试数据集测试变更。
实用的验证流程
可维护的实现可以采用以下流程:
- 检查请求是否包含字符串值和有效业务记录。
- 保存原始输入,然后创建有文档说明的规范形式。
- 拒绝空值、占位符、不安全字符以及超出文档规定长度范围的值。
- 从可信订单数据中确定承运商,或使用明确支持的检测流程。
- 仅在权威文档支持时应用承运商特定的语法和校验和规则。
- 检查端点要求、重复状态和重试资格。
- 提交请求,对响应进行分类,存储结果,并为未解决的记录安排后续处理。
该流程使验证器更易于测试,因为每个决定都有不同原因。它还可以为运营团队提供可操作的失败类别,而不是单一的不透明错误。
实施清单
- 将跟踪号码存储为字符串,以保留前导零。
- 在需要可审计性时,分别保存原始值和规范值。
- 将承运商规则作为带版本的配置进行维护,而不是分散在硬编码条件中。
- 测试字母、数字、连字符、空白、Unicode 外观相似字符、占位符和边界长度。
- 在可用时使用可信的承运商上下文。
- 不要根据正则表达式匹配成功推断货件存在。
- 将永久性验证错误与临时 API 或网络错误分开分类。
- 在更改格式规则或请求逻辑之前,查阅提供商文档。
常见问题
正则表达式可以验证跟踪号码吗?
当承运商和服务格式已知时,它可以验证有限的模式。但它无法证明号码存在、属于特定货件或当前处于激活状态。通用表达式很可能造成误拒绝或误匹配。
看起来无效的号码应该提交到 API 吗?
明显为空、不安全或在结构上不可能的值通常应在提交前拦截。对于不熟悉但其他方面安全的格式,不应仅因为它不符合内部猜测就拒绝。应先检查承运商文档或使用支持的检测流程。
校验和足以确认货件吗?
不够。校验和在适用时只能测试该值是否符合数学规则。它无法确认承运商是否签发了该号码,也无法确认包裹是否已进入网络。
承运商未知时应该怎么做?
运行通用安全检查,并在可用时使用明确支持承运商检测的 API 工作流。否则,应保留记录以进行信息补充或人工审核,而不是静默猜测承运商。
应如何处理 API 错误?
按原因分类。修复格式错误的输入和不支持的承运商值;对临时网络或提供商故障,在限制次数并采用退避的情况下重试;将身份验证或配额错误转交给集成负责人。存储诊断所需的响应详情,但不要暴露机密。
来源
- 17TRACK API 文档 — 面向跟踪 API 开发人员的请求和集成指南。
- 17TRACK Tracking API — 官方产品信息和 API 使用场景。
- USPS Tracking — 官方承运商跟踪入口和客户指南。
- UPS Tracking — 官方承运商跟踪入口。


