Skip to main content
首页博客指南如何使用货件跟踪 API 发送主动式配送通知

如何使用货件跟踪 API 发送主动式配送通知

17TRACK

要通过货件追踪 API 发送主动配送通知,请将每个包裹与其订单关联,接收追踪更新,将这些更新转换为与客户相关的事件,并通过电子邮件、短信或应用通知服务触发消息。在传入追踪数据与传出消息之间加入持久化队列和重复检查,以避免重复或延迟的更新产生令人困惑的提醒。

如何使用货件追踪 API 发送主动配送通知

本指南面向构建此类工作流的开发人员和电子商务运营团队。目标不是转发承运商的每一次扫描,而是在发生有意义的变化时告知客户变化内容、其含义以及客户是否需要采取行动。

连接 API 之前先设计通知工作流

货件追踪 API 提供追踪信息;你的应用程序决定如何使用这些信息。即使所选服务同时提供这两项功能,也应将货件可视化与客户沟通视为不同的职责。

实用的架构包含六个阶段:

  1. 订单关联:在需要时,将追踪号码和承运商标识符关联到内部货件记录。
  2. 追踪注册:根据服务提供商的集成要求提交或注册货件。
  3. 更新接收:接收 webhook 回调、通过 API 请求获取更新,或结合使用两种方式。
  4. 事件处理:验证、规范化、去重并评估传入事件。
  5. 通知决策:决定是否通知、联系谁,以及使用哪个渠道和模板。
  6. 消息发送:发送通知并记录消息服务的响应。

除非集成确实要求共享客户联系信息,否则请将其保存在你自己的订单系统或消息系统中。追踪服务通常不需要客户的电子邮件地址,仅用于让你的应用程序将追踪事件与订单关联。

1. 确认集成契约

在编写接收器之前,请查看服务提供商的文档,了解身份验证、货件注册、承运商识别、支持的更新方式、响应格式、请求限制和错误处理。对于 webhook 集成,还应确认回调如何进行身份验证、什么响应表示已收到,以及投递失败时如何处理。

对于 17TRACK 的实现,请从 17TRACK Tracking API 页面及其官方 API 文档开始。请使用文档中规定的契约进行集成,不要将本指南中的示例字段名称视为 17TRACK 的请求或响应字段。实施前请确认回调设置、安全要求和账户特定的限制。

请根据集成契约选择更新方式:

  • Webhooks:在基础设施支持且适用时使用回调。服务提供商发送更新后,应用程序即可处理,无需反复请求同一个货件。
  • 轮询:在回调不可用或不适用时,按计划获取追踪信息。将计划安排控制在文档规定的请求限制内。
  • 组合方式:使用回调进行常规处理,并在服务提供商支持该工作流的情况下,有选择地通过 API 获取信息,以协调更新似乎已过时的货件。

不要仅仅因为使用了 webhooks,就向客户承诺即时通知。在上游追踪数据可用之前,你的应用程序无法报告承运商事件。

2. 构建能够应对真实订单的货件记录

使用内部货件 ID 作为主要引用,而不要仅使用追踪号码。一个订单可能包含多个包裹,也不应假定追踪号码永远具有全局唯一性。

有用的内部记录包括:

  • 内部订单 ID 和货件 ID。
  • 追踪号码和承运商标识符(如已知)。
  • 服务提供商提供的货件引用(如有)。
  • 当前规范化状态和最新的有意义事件。
  • 承运商事件时间,包括可用时的时区或偏移量。
  • 系统接收更新的时间。
  • 客户沟通偏好的引用。
  • 通知历史以及任何有效的异常处理流程。

将事件时间与接收时间分开存储。较早发生的扫描可能在较新的扫描之后到达。如果应用程序仅按到达顺序排序,就可能错误地将已送达货件改回运输中。

对于拆分订单,请将通知关联到受影响的包裹。当另一个包裹仍在运输时,“你订单中的一个包裹已送达”比“你的订单已送达”更准确。

3. 将追踪事件映射为客户决策

承运商描述属于运营数据,不是可直接使用的客户消息。请构建规范化层,在保留原始事件的同时,为其分配通知规则能够理解的内部类别。

以下类别是建议的应用概念,并非通用的 API 状态词汇:

内部类别通知决策消息边界
已收到货件信息仅在有用时发送准备更新。不要仅根据创建标签就暗示承运商已经实际接收货件。
运输中考虑在首次有意义的移动时通知。除非会改变客户的下一步行动,否则抑制例行的设施扫描。
派送中在受支持的事件表明该状态时通知。不要将该状态转化为保证的送达时间。
派送尝试或需要取件发送可采取行动的通知。仅在已验证时加入截止日期或取件说明。
配送异常评估原因以及客户是否需要采取行动。不要将每个异常都描述为包裹丢失。
已送达发送包裹级别的确认。不要编造收件人、配送地点或送达证明。

保留不确定性。无法识别的事件应进入审核或回退路径,而不是被强行归入最接近的熟悉类别。保留原始描述,以便支持人员排查问题。

4. 接收更新,避免丢失或重复处理

你的 webhook 端点应验证请求,持久化保存已接受的更新,并返回服务提供商要求的确认响应。应异步生成消息,而不是在回调请求期间等待电子邮件或短信服务。

实现服务提供商文档规定的回调验证方法。不要自行创建签名标头,也不要假设每个服务提供商使用相同的身份验证方案。同时强制使用 HTTPS、请求大小限制、载荷验证和适当的访问控制。

简化的处理流程如下。这些是应用程序级操作,不是可运行的 SDK 示例:

接收回调
  使用服务提供商文档规定的机制验证请求
  验证载荷
  持久化保存已接受的载荷并以原子方式加入处理队列
  返回文档规定的确认响应

处理队列中的更新
  查找内部货件
  规范化相关事件
  忽略已处理的事件
  评估时间顺序和状态转换
  如果策略允许则创建通知任务
  一并提交状态和任务

发送通知任务
  检查收件人偏好和抑制规则
  将消息提交给消息服务
  记录结果,并仅在适当时重试

原子步骤很重要。如果应用程序保存了状态变化,却在创建通知任务之前崩溃,客户可能永远收不到提醒。事务性发件箱是一种设计方案:在同一个数据库事务中保存状态变化和待处理任务,然后由工作进程分发任务。

明确处理未知货件引用。将其隔离以供调查或协调,而不是猜测应该向哪个客户发送通知。

5. 添加重复保护和时间顺序检查

设计接收器时,应能够容忍重复回调和工作进程重试。如果文档中提供了稳定的服务提供商事件标识符,应优先使用。否则,可根据合适的字段创建确定性的事件指纹,例如内部货件 ID、事件代码、事件时间和地点。在依赖该指纹之前,请使用实际载荷进行测试。

事件去重和通知抑制解决的是不同问题。去重可防止同一事件被处理两次;抑制可防止多个不同的扫描生成本质相同的客户消息。

围绕业务事件定义通知标识。配送确认可以使用货件 ID 和“已送达”里程碑。配送尝试可能需要特定于尝试的标识,因为稍后的尝试可能是一个真正的新事件。

对于乱序更新,请比较事件时间戳并评估允许的状态转换。不要假设回调只包含新的扫描;应检查其文档规定的结构表示单个事件、快照还是历史记录。将相互矛盾的更新交由协调流程处理,而不是静默丢弃所有更正。

6. 编写能够说明下一步行动的消息

每条通知都应说明相关包裹、已确认的变化以及客户的下一步行动。加入安全的追踪链接和易于识别的订单引用。在短信和锁屏预览中,避免暴露完整地址或不必要的个人信息。

例如:

  • 派送中:“你的订单 {order_reference} 中的包裹正在派送。请在此查看进度:{tracking_link}。”
  • 派送尝试:“承运商报告已尝试派送你的包裹。请查看追踪页面,了解可采取的下一步行动:{tracking_link}。”
  • 已送达:“承运商已将你的订单 {order_reference} 中的包裹标记为已送达。查看可用的配送详情:{tracking_link}。”

仅使用经过验证的数据渲染占位符。如果有可用且适合展示的预计送达时间,请将其标记为预计时间。如果缺失,请省略,而不是编造日期。

对于异常,请区分货件问题和客户任务。配送中断可能只需要解释;经过验证的地址问题可能需要客户采取行动。不要仅根据不受信任的追踪自由文本内容,就将客户引导至付款或上传文件页面。

根据客户偏好、渠道权限、紧急程度和适用规则选择渠道。请查看你所使用的司法管辖区和消息渠道中的同意、退订和免打扰时段要求。将配送服务通知与营销活动分开,不要假定两者适用相同的权限。

7. 定义追踪停止更新时的处理方式

主动沟通不仅应涵盖新事件,也应涵盖进度缺失,但仅凭沉默无法证明货件延迟或丢失。

根据服务级别、路线、上一次有意义的事件以及任何受支持的预计送达时间,创建追踪过期规则。应根据运营数据和支持流程设置阈值,而不是对每个货件采用统一的等待时长。

触发该规则后,请检查是否存在处理遗漏,并在支持的情况下与追踪来源进行协调,然后决定是否创建内部支持任务。如果通知客户,请使用反映已知事实的措辞:“我们尚未收到新的追踪更新”不同于“你的包裹已丢失”。

为未解决的异常指定负责人。一个反复宣布问题却没有解决路径的通知系统,可能会增加客户的不满。

8. 启用自动发送前测试完整路径

首先以影子模式运行工作流:接收真实或获批准的测试事件,生成拟发送的通知,并在不联系客户的情况下检查结果。

  • 重放完全相同的回调,并确认不会创建另一条消息。
  • 在已送达事件之后处理较早的运输事件,并检查生成的状态。
  • 测试缺失时间戳、未知状态和格式错误的载荷。
  • 模拟确认前的数据库故障以及持久化后的工作进程故障。
  • 测试消息超时,包括服务可能已经接受消息但响应不确定的情况。
  • 确认拆分货件会生成针对具体包裹的措辞。
  • 检查已退订的收件人、无效联系信息和免打扰时段处理。
  • 验证追踪链接不会暴露其他客户的订单信息。

监控已接受的回调、处理失败、队列年龄、通知任务、重复抑制和消息结果。分别测量从系统接收时间开始的处理延迟和承运商事件的时间跨度。这一区分有助于确定通知缓慢是由上游数据可用性造成,还是由你自己的处理流程造成。

从一组少量且易于理解的里程碑开始。只有在支持团队和运营团队确认消息准确、可执行且值得接收后,再扩展规则。

常见问题

货件追踪 API 会自动发送电子邮件或短信吗?

不一定。追踪数据访问和客户消息是两个独立的功能。请查看服务提供商文档中规定的范围。在自定义集成中,你的应用程序可以处理追踪更新,并通过独立的消息服务发送通知。

我应该将每一次追踪扫描都通知客户吗?

通常不应该。应优先通知有意义的里程碑和需要采取行动的事件。多个设施扫描可能只代表正常运输,并不会改变客户需要了解的内容。将详细历史记录保留在追踪页面上。

我可以保证实时发送配送通知吗?

你可以在系统收到更新后设定并监控处理目标,但无法保证承运商何时记录或发布扫描。请使用能够反映这一依赖关系的措辞描述服务。

如何防止重复发送配送消息?

使用持久化事件去重、为每个业务里程碑设置独立的通知标识,以及事务性任务创建。如果你的消息服务支持幂等性,请将其作为另一项保护措施。仅依赖内存中的重复检查无法应对重启或多个工作进程。

如果承运商更正了已送达状态,应该怎么办?

保留两个事件并协调货件状态。如果更正对客户有实质影响,请根据你的策略发送清晰的更正通知或转交支持团队。不要仅为了简化代码,就让已送达状态永久不可逆。

来源

以下官方资源是上述 17TRACK 集成的实施参考。本指南中的内部架构、通知规则和处理流程是架构建议,并非引用的 API 契约。