如何透過一個 API 統一澳洲及紐西蘭的貨件追蹤
要透過一個 API 統一澳洲及紐西蘭的貨件追蹤，請將你的訂單或履行系統連接至多承運商追蹤服務，使用正確的承運商身份註冊每件貨件，並將收到的追蹤更新轉換為一致的內部事件模型。整合應保留承運商特有的詳細資料，同時讓你的營運團隊及客戶在本地及跨塔斯曼海配送中享有一致的追蹤體驗。
對開發人員、電子商務營運人員及物流團隊而言，主要挑戰並不是發出第一個 API 請求，而是在不同承運商以不同方式描述同一段運送旅程時，仍然保持貨件身份、配送狀態、承運商交接及客戶通知的一致性。本指南將說明如何設計這項整合、評估追蹤 API，並在正式環境依賴它之前進行測試。
定义单一 API 需要统一的内容
共享 API 为你的应用程式提供共同的整合入口，但不会令每间承运商发布完全相同的资料，或以相同频率扫描包裹。你的架构需要区分一致的介面与完整的可见性。
先根据实际履行活动建立货件清单，而不是根据在任一国家营运的承运商建立一般清单。包括澳洲境内货件、纽西兰境内货件，以及两个方向的跨境运输。如其他国际始发地属于你的业务范围，也应一并加入。
- 承运商及服务：记录承运商、所使用的服务，以及任何已知的配送合作伙伴。
- 路线：区分货件的始发地及目的地与最新扫描位置。
- 识别码：记录订单编号、履行编号、追踪号码，以及任何替换号码或合作伙伴号码。
- 营运目的：指定更新是用于客户追踪、异常管理、配送确认，还是三者皆是。
- 所需详细资料：决定广泛的配送状态是否足够，或客服人员是否还需要扫描说明、位置及时间戳。
这份清单会成为你的验收清单。供应商的一般承运商覆盖范围有助于筛选，但你的决定应取决于实际使用的承运商及服务组合是否能返回可用的追踪资料。
根據你的货件组合评估追蹤 API
17TRACK 提供Tracking 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 文件 — 用于查看请求格式、整合要求及支援行为的官方技术参考资料。
