如何通过一个 API 统一澳大利亚和新西兰的货件追踪
要通过一个 API 统一澳大利亚和新西兰的货件跟踪，请将您的订单或履约系统连接到多承运商跟踪服务，使用正确的承运商身份注册每票货件，并将传入的跟踪更新转换为一致的内部事件模型。该集成应保留承运商特有的详细信息，同时让运营团队和客户能够对国内配送以及跨塔斯曼海配送享有统一的跟踪体验。
对于开发人员、电商运营人员和物流团队而言，主要挑战并不是发出第一个 API 请求，而是在不同承运商以不同方式描述同一运输流程时，保持货件身份、配送状态、承运商交接和客户通知的一致性。本指南将介绍如何设计该集成、评估跟踪 API，并在投入生产使用前进行测试。
明确单一 API 需要统一的内容
共享 API 为您的应用提供了统一的集成入口，但不会让每家承运商发布完全相同的信息，也不会让它们以相同频率扫描包裹。您的架构需要区分一致的接口和完整的可见性。
首先，应根据实际履约活动建立货件清单，而不是根据在任一国家运营的承运商通用列表建立清单。包括澳大利亚国内货件、新西兰国内货件，以及两个方向的跨境运输。如果其他国际始发地属于您的业务范围，也应将其加入。
- 承运商和服务：记录承运商、使用的服务以及任何已知的配送合作伙伴。
- 路线：区分货件的始发地和目的地与其最新扫描位置。
- 标识符：收集订单参考号、履约参考号、跟踪号码，以及任何替换号码或合作伙伴号码。
- 运营目的：明确更新是用于客户跟踪、异常管理、配送确认，还是三者全部。
- 所需详细信息：确定宽泛的配送状态是否足够，或客服人员是否还需要扫描描述、位置和时间戳。
该清单将成为您的验收检查表。服务商的承运商覆盖范围可用于初步筛选，但最终决定应取决于实际使用的承运商和服务组合是否能返回可用的跟踪信息。
根据您的货件组合评估跟踪 API
17TRACK 提供跟踪 API，因此值得作为多承运商集成的选项进行评估。使用其官方 API 文档检查当前的集成要求。应将承运商支持、事件字段、更新行为、账户限制和商业条款视为需要针对您的实现进行核实的事项，而不是根据产品类别作出的假设。
请对任何正在考虑的 API 提出相同的实际问题：
- 它能否识别并跟踪货件清单中的承运商和服务？
- 当承运商识别存在歧义时，您能否提供明确的承运商标识符？
- 您的应用如何接收更新？如果遗漏更新，有哪些恢复机制可用？
- 哪些原始承运商详细信息会与标准化状态一同保留？
- 当跟踪号码无效、尚未被识别，或可能关联多个承运商时，会发生什么？
- 您的账户如何定义用量、计费、跟踪时长和访问限制？
建议的决策规则：应根据对真实运输模式的成功测试结果进行选择，而不是根据宣传中的承运商数量最多来选择。当一个集成能够提供足够的信息来支持运营决策，并且能够足够清晰地暴露故障以便恢复时，它才适合使用。
构建能够适应承运商差异的内部模型
区分订单、货件和跟踪环节
不要将跟踪号码作为订单的主键。一个订单可能包含多个包裹，而一个包裹的运输过程可能涉及多个跟踪标识符。应创建内部货件 ID，并将跟踪记录关联到该 ID。
实用模型包含三个层级：客户订单、订单中的实物货件，以及与每票货件关联的跟踪环节。国内包裹可能只需要一个跟踪环节。跨境包裹则可能在涉及其他承运商或标识符时需要关联记录。
跟踪记录应同时以承运商和跟踪号码作为范围，并保留其与货件 ID 的关系。如果出现新的配送合作伙伴号码，应将其作为关联标识符添加，而不是覆盖原号码。这样可以保留客服人员调查交接情况时所需的历史记录。
同时保留原始事件和标准化事件
使用一套规模较小、业务能够据此采取行动的内部状态词汇。例如，可以定义为运输前、运输中、派送中、可取件、已送达、异常和未知。这些是建议的内部类别，并不代表某个特定服务商的状态架构。
在保存映射状态的同时保留原始承运商描述。取件点事件和地址问题都可能需要客户采取行动，但不应产生相同的消息。同样，创建标签也不应自动被视为承运商已经实际持有包裹的证据。
在版本化配置中记录映射决策。当出现新的事件描述且含义不明确时，应将其放入审核队列。明确的未知状态比自信地分配错误的配送结果更加安全。
区分事件时间和接收时间
分别存储事件发生时间和系统接收时间。较早的扫描记录可能在较新的记录之后到达，尤其是在更新延迟或一次性提供历史事件时。
对于澳大利亚和新西兰，不要对每票货件都应用同一个固定时差。来源提供时间戳和时区偏移时，应予以保留。当拥有可靠的位置背景时，显示时使用适当的命名时区，并考虑夏令时差异。如果缺少来源时区，应保留这种不确定性，而不是自行生成精确的 UTC 转换。
实施可靠的数据接收工作流
- 首先创建内部货件。在向跟踪服务注册之前，记录订单关系、路线、承运商选择和跟踪标识符。
- 提交跟踪注册。使用服务商记录的请求格式。保存响应，并区分注册成功与承运商事件随后可用这两个阶段。
- 对失败进行分类。将无效输入和身份验证问题与临时服务故障区分开来。只有在重试有合理帮助时才进行重试。
- 接收或获取更新。实施所选 API 支持的传递机制。如果使用 webhook，请使用服务商记录的方法验证传入请求，并通过持久化队列处理已接受的事件。
- 应用变更前去重。在可用时使用服务商事件标识符，或使用经过谨慎设计的复合键。重复传递不得触发重复的客户通知。
- 重新计算货件状态。评估事件含义和时间顺序，而不是直接将当前状态替换为最后到达的更新。
- 协调不完整记录。在 API 支持获取功能的情况下，使用该功能调查遗漏更新或过期记录，同时遵守适用的用量限制。
将服务商特有的身份验证、字段名称和错误处理封装在适配器中。您的订单管理系统应使用内部货件模型，而不是直接依赖服务商响应中的每个细节。这种分离也会让后续 API 变更更易于测试。
处理跨塔斯曼海运输流程，避免凭空确定
跨境跟踪所需的上下文多于一系列状态标签。当来源数据支持这些区分时，您的应用应区分出口事件、海关相关事件、承运商交接和最终配送事件。
不要根据通用的运输中扫描记录推断货件已完成清关。同样，近期没有扫描记录也不能证明海关正在扣留包裹。有效的客户消息应说明最后一个已确认事件及其时间，然后解释团队实际能够支持的下一步行动。
将始发地和目的地与扫描位置分开。一票从澳大利亚运往新西兰的货件，不会仅仅因为收到入境扫描就变成新西兰国内货件。这一区分对于路线报告和异常责任归属很重要。
如果配送合作伙伴介入，只有在货件数据、跟踪服务或经过运营核实的记录支持该关系时，才关联其跟踪记录。不要仅仅因为标识符看起来相似就合并包裹。
将跟踪事件转化为有用的客户更新
面向客户的页面应回答四个问题：最后确认的状态是什么、何时发生、如果已知则记录地点在哪里，以及客户是否需要采取行动？
将通知规则与事件接收分开。并非每次扫描都值得发送电子邮件或短信。定义有意义的状态转换，例如首次确认移动、尝试配送、需要取件或已送达事件，并抑制同一转换的重复提醒。
- 跟踪过期：说明上次更新发生的时间，但不要将沉默视为丢失的证据。
- 配送预计时间：区分承运商提供的预计时间和商家的承诺。当两者都不存在时，不要编造日期。
- 异常：在已知的情况下提供具体的下一步，而不是显示无法解释的错误标签。
- 已送达争议：保留来源事件并将案件转交客服；仅凭已送达状态无法解决所有客户争议。
除了 API 凭据外，也要保护跟踪页面。避免公开不必要的地址或联系方式，将服务凭据保存在服务器端，并针对所显示的信息应用适当的访问控制。
在正式上线前开展基于路线的试点
在与业务相关的情况下，测试澳大利亚国内、新西兰国内、澳大利亚至新西兰以及新西兰至澳大利亚的货件。包括普通配送和运营边界情况：拆分订单、未识别号码、交接、配送尝试、取件事件、退货以及延迟到达的扫描记录。
使用获得适当授权的真实货件记录验证承运商。使用模拟事件测试您自己应用的韧性，但不要将模拟结果视为实时承运商覆盖范围的证据。
- 身份检查：每次更新都到达正确的货件和订单。
- 时间顺序检查：乱序事件不会错误地逆转配送进度。
- 恢复检查：临时故障和重复更新不会导致数据丢失或重复提醒。
- 客服检查：客服人员可以查看原始事件并理解面向客户的状态。
- 商业检查：预计用量符合账户已核实的计费模式和限制。
在评估试点前设定验收阈值。衡量注册结果、未映射事件、处理延迟、重复通知和未解决的过期货件。将承运商数据延迟与您自己应用内部的延迟区分开，以便由正确的负责人进行处理。
当团队能够解释并处理不完整的跟踪，而不仅仅是显示成功配送时，该实现才算准备就绪。一个 API 可以简化连接；您的货件模型、事件规则和运营流程才能让这种连接可靠运行。
常见问题
一个跟踪 API 能否取代承运商运输集成？
不一定。跟踪、标签创建、取件预约、费率计算和海关文件是不同的功能。请核实所选产品的范围，并在履约流程需要时保留其他集成。
我可以在承运商首次扫描前注册跟踪号码吗？
请查看 API 的注册规则。设计应用时，应区分已接受的跟踪注册和已确认的实际运输。一条没有事件的记录不应自动显示为运输中。
单一 API 能为每家承运商提供实时更新吗？
不要这样假设。端到端的新鲜度取决于承运商何时发布数据、跟踪服务何时获取数据，以及您的应用何时处理数据。请确认您所使用的承运商和服务组合的更新行为。
跟踪号码发生变化时应该怎么办？
保留原始标识符，并将经过验证的替换标识符或合作伙伴标识符关联到同一个内部货件。保留两者的历史记录，并防止重复记录生成相互冲突的通知。
17TRACK 与这种集成相关吗？
相关。其 Tracking API 与此处描述的多承运商集成相关。请使用您的澳大利亚和新西兰货件样本对其进行评估，并在部署前通过官方 API 资源确认承运商支持、技术行为和账户条款。
来源
- 17TRACK Tracking API — 本指南所讨论 API 选项的官方产品资源。
- 17TRACK API documentation — 用于检查请求格式、集成要求和支持行为的官方技术参考。
