Skip to main content
首页博客指南投入生产前向跟踪 API 提供商提出的 15 个问题

投入生产前向跟踪 API 提供商提出的 15 个问题

17TRACK

在将跟踪 API 投入生产环境之前,请了解它如何处理您实际使用的承运商和运输类型、其事件代表什么、更新如何到达,以及数据或集成失败时会发生什么。下面的 15 个问题为工程和运营团队提供了一种实用方式,可在客户、客服人员或自动化工作流依赖这些结果之前,对上述问题进行测试。

开始前向跟踪 API 提供商提出的 15 个问题

成功的演示并不等于生产测试。请使用具有代表性的货件样本,包括延误、退回和难以识别的包裹。对于每个答案,请索取文档、示例负载或测试结果。对于任何未解决的事项,请记录负责人和决策日期,而不要假设它会在上线后得到处理。

从货件匹配度和数据含义开始

1. 我们实际的哪些货件可以被跟踪,覆盖范围意味着什么?

向提供商提供您的承运商、服务、起运地与目的地组合以及跟踪号码格式样本。请其确认哪些货件可以接受、哪些承运商可以自动识别,以及在哪些情况下您必须提供承运商代码。承运商出现在列表中,并不能证明每种服务、交接方式或货件类型都会产生您的应用所需的事件。

测试来自高交易量线路和运营边界情况的真实示例。如果您的业务中存在运输途中更换承运商的情况,也请纳入一票此类货件。记录 API 是拒绝货件、接受货件但找不到事件,还是返回详细程度有限的事件。这些结果在订单管理系统中需要采取不同的处理方式。

2. 注册货件需要哪些信息,以及如何防止重复注册?

明确所需标识符、承运商选择规则、注册时机,以及对无效或尚未激活的跟踪号码的响应。请确认对于您的使用场景,仅凭跟踪号码是否足够,还是需要其他信息。确认同一货件被提交两次时会发生什么,无论是由同一系统还是不同服务提交。

建立一个责任明确的注册流程:哪个系统提交货件、哪个系统存储提供商的标识符,以及哪个系统重试不确定的提交。如果提供商处理请求后发生超时,盲目重试不得悄然创建第二条记录或重复发送下游通知。

3. 你们的状态代表什么,我们能否查看底层承运商事件?

索取状态字典和具有代表性的原始事件。“运输途中”“派送中”“异常”“已送达”和“已退回”等术语是有用的摘要,但您的业务规则可能需要更多细节。确认提供商是否会在标准化状态旁提供承运商的原始描述,以及如何处理无法清晰映射的事件。

在上线前确定您自己的内部状态模型。尤其要决定哪个事件可以关闭货件、触发送达消息或启动异常工作流。除非底层数据支持这种解释,否则不要将宽泛的状态标签视为某个具体物理事件已经发生的证明。

4. 提供哪些时间戳和地点信息,我们应如何解读?

对于每个事件,区分承运商所称的事件发生时间与提供商接收或发布该事件的时间。询问时区、缺失的偏移量、地点精度,以及在较晚事件之后才到达的更新。最近收到的事件可能描述的是较早的扫描;仅按接收时间排序可能会产生误导性的时间线。

根据您的数据库架构和面向客户的展示方式测试负载。决定在本地时区不确定时如何显示事件;如果来源没有提供精确的送达时间或地点,请避免展示此类精确信息。

5. 如何表示异常、退货和送达证明?

索取派送失败尝试、海关扣留、地址问题、退回寄件人过程以及已送达货件的示例。询问哪些详情是标准化的,哪些仍由承运商决定,以及在您关注的场景中,送达确认是否包含任何支持性证据。不要假设“已送达”状态包含收件人姓名、签名、照片或其他证明。

将每种异常映射到一个行动负责人。有些事件需要客服审核;其他事件则应在更多信息到达前不向客户发送消息。如果争议处理流程需要送达证明,请将其可用性和格式设为单独的验收标准,而不是将其视为跟踪覆盖范围的默认组成部分。

测试更新如何到达您的系统

6. 你们通过 webhook、轮询还是两者提供更新,我们应在何时使用各自的方式?

索取已记录的交付模式、负载示例、订阅设置以及恢复遗漏更新的指导。如果提供 webhook,请确认它们是通知货件发生变化、提供完整快照,还是携带单个事件。如果必须使用轮询或将其作为备用方式,请明确适当的请求模式以及如何识别发生变化的记录。

根据工作流选择模式。面向客户的时间线可能可以容忍与异常队列不同的更新延迟。您的架构不应仅仅因为集成使用 webhook 就承诺即时提醒:承运商必须先提供事件,之后每个系统还必须对其进行处理。

7. 通知重复、延迟或乱序到达时会发生什么?

询问提供商是否会重试未成功的交付、重试持续多久,以及它期望您的端点返回什么响应。如果有稳定的事件或货件标识符,请索取该标识符。然后测试同一通知两次,在较新事件之后发送较旧事件,并让您的端点暂时返回错误。

您的接收器应设计为仅确认已安全接受的内容,在重试时不重复发送客户消息,并在事件乱序到达时重建正确的时间线。如果方案依赖每条通知恰好交付一次,请在发布前质疑这一假设。

8. 我们如何衡量数据新鲜度,哪些因素会影响它?

询问提供商可以在每个阶段测量什么:承运商事件时间、提供商接收时间以及发送到您系统的时间。将这些测量结果与提供商做出的任何承诺区分开来。物理移动与应用更新之间的长时间间隔,可能源于上游、提供商处理过程或您自己的队列。

在试点期间,针对具有代表性的货件测量这些间隔并调查异常值。根据工作流的实际需求设置警报阈值。如果扫描延迟会导致有害的客户消息或错过升级处理,请定义备用方案,例如“数据过时”标签或人工审核。

9. 如何保护 API 凭证和 webhook 请求?

索取身份验证和凭证管理文档。确认凭证如何签发、限定范围、轮换和撤销;测试凭证与生产凭证是否分离;以及 webhook 接收器如何验证请求的真实性。还要询问有哪些措施可以防止重放 webhook 请求。

让您的安全团队审核拟议的实现,而不仅是提供商的功能列表。不要将密钥放入客户端代码和日志中,限制对生产凭证的访问,并演练凭证轮换。如果您的应用无法使用文档规定的机制验证传入通知,那么对于基于 webhook 的工作流而言,这就是发布阻断项。

10. 你们保留哪些货件和客户数据,这些数据会被发送到哪里?

列出集成将发送的每个字段,包括跟踪号码、订单引用、地址、联系信息以及任何自定义元数据。询问哪些字段是必需的,数据和日志保留多长时间,删除请求如何处理,以及哪些地区或子处理商与您组织的要求相关。在审核需要时,获取合同或安全文档。

尽量减少传输的数据。跟踪集成不应仅仅因为传递整个订单对象很方便,就接收客户信息。您的隐私、法务和安全团队应决定提供商记录的数据处理方式是否适合您运营所在的市场。

为故障和运营变化做好规划

11. 速率限制是什么,客户端应如何响应错误?

询问按端点、凭证和环境划分的限制,以及并发规则和建议的重试行为。区分无效请求、临时服务问题和被速率限制的请求。对于 HTTP API,状态码含义很重要:RFC 6585 将 429 定义为请求过多,而 RFC 9110 描述了 HTTP 语义,包括服务器错误。

计算普通日期和流量峰值期间的预期流量,然后测试一个能够退避、排队处理工作并在持续失败时发出警报的客户端。确认不确定的写入是否可以安全重试。在服务中断期间放大流量的重试策略可能会使恢复更加困难。

12. 架构、状态和承运商集成的变更如何沟通?

询问 API 版本控制、弃用通知、变更日志,以及是否可以在不改变版本的情况下添加事件字段。承运商提供的描述和跟踪行为也可能发生变化。确定当某项变化影响某个承运商或路线,而不是整个 API 时,提供商会如何沟通。

为可选字段和未知状态值编写容错解析器,但不要悄悄将陌生值转换为“已送达”或“失败”。存储足够的源数据细节,以便诊断映射变化。指定人员审核提供商通知,并在变化影响客户之前更新集成测试。

13. 生产前可以测试什么,测试环境与实际运行环境有多接近?

索取文档访问权限、测试环境(如有)、示例响应以及执行错误路径的方法。询问哪些场景是模拟的,哪些需要真实货件。沙盒可能证明您的代码能够处理某个负载,但无法充分说明承运商事件的完整性、更新时间或区域适配性。

运行两类测试:针对解析、重试和安全性的确定性集成测试;以及针对运营行为的有限真实货件试点。包括重复提交、提供商超时、延迟扫描、退货和未知状态。要求工程团队和负责处理异常的团队都对结果签字确认。

14. 当跟踪停止更新时,适用哪些支持和事故承诺?

询问您的账户可以使用哪些支持渠道、如何报告事故,以及哪些合同服务承诺(如有)适用于 API 或通知交付。明确正常运行时间承诺涵盖 API 端点、跟踪更新的交付,还是两者。它们并不是相同的运营结果。

建立您自己的运行手册:谁发现故障、谁联系提供商、何时使用轮询或其他备用方式,以及更新延迟期间客户会看到什么。索取解决单个货件数据问题和全平台中断的流程。在需要之前测试您的升级路径。

15. 如何计算使用量和费用,如果我们离开会发生什么?

询问哪些操作计入计费或使用限制:提交、跟踪货件、请求、通知还是其他单位。确认在拟议协议下,重复注册、重试、不活跃货件、超额使用和测试流量如何处理。获取适用条款的书面说明,而不要根据 API 演示估算成本。

同时规划终止合作。确定如何导出货件历史记录、访问权限会保留多久,以及活跃跟踪记录会发生什么。可行的退出计划并不是预测您一定会更换提供商,而是避免失去对已在运输途中的货件的可见性。

将答案转化为生产决策

有用的上线审核应产生三个结果:

  • 货件匹配结果:经过测试的样本,显示哪些跟踪记录被接受,以及其事件是否支持您计划的客户和运营工作流。
  • 集成结果:已验证能够处理身份验证、重复项、重试、延迟事件、架构变化以及遗漏更新的恢复。
  • 运营协议:记录限制、数据处理条款、支持联系人、成本假设以及未解决风险的负责人。

如果多承运商跟踪 API 符合您的使用场景,17TRACK 是可以评估的提供商之一;其 跟踪 API 页面和 API 文档可以作为起点,用于根据这些问题检查集成。同样的标准应适用于任何提供商:文档说明接口预期如何工作,而您自己的代表性货件测试则说明它是否适用于您的生产工作流。在触发客户通知或异常自动化的事件得到验证之前,不要发布这些功能。

常见问题

沙盒测试是否足以批准跟踪 API 投入生产?

不够。沙盒可以验证请求格式和部分故障处理,但需要真实货件来评估承运商特定事件、时间安排以及异常数据在您实际线路上的实用性。两者都应使用,并分别设定验收标准。

我们应该使用 webhook 还是轮询跟踪更新?

根据提供商记录的交付选项和工作流对延迟的容忍度来决定。受支持时,webhook 可以减少重复检查的需要,但您的接收器仍需要处理重试和重复。轮询可以作为主要方式或恢复路径,具体取决于记录的限制。

映射跟踪状态时最常见的错误是什么?

使用一个宽泛的状态作为更具体业务主张的触发器。例如,仅有“已送达”标签可能无法提供解决争议所需的证明。应使用提供商实际提供的底层事件详情来定义触发条件。

上线前谁应批准该集成?

工程团队应批准可靠性和安全性;运营或客服团队应批准事件和异常工作流的实用性;相应的隐私、法务和采购负责人应审核数据处理和商业条款。为任何仍未解决的差距指定明确负责人。

来源