如何设置 API 订单完成通知

哪些事件应视为订单完成

首先确定 API 中哪个状态表示订单实际完成。不同供应商可能使用已完成、已送达、已取消、已拒绝、已退回或部分完成等状态。不要只把自动化绑定到“成功”这个词上：订单可能经过多个中间状态，然后因限额、审核或取消而停止。

不仅需要处理成功结果。如果服务发送错误、取消、退回或部分完成的通知，也应将其写入内部系统。否则，在面板、CRM 或机器人中，订单会一直处于等待状态，尽管后续执行已经不会发生。

建立状态映射表

不要未经处理就把 API 状态传到界面。供应商的名称和逻辑可能变化，而同一个内部状态有时会合并多个外部状态。请单独保存原始值：它可用于排查错误和与文档核对。

• pending、created、queued — 新建或等待处理的订单。
• processing、in_progress、running — 订单正在执行。
• completed、delivered、success — 已完成的订单。
• partial、partially_completed — 部分完成的订单。
• cancelled、rejected、failed — 已取消或因错误结束的订单。
• refunded、returned — 需要退款或调整的订单。
• 未知状态 — 不自动更改卡片，转交人工检查。

上述名称仅作为映射方案示例。最终表格必须根据具体 API 的状态来构建。手动映射的缺点在于，API 更新后需要维护它：新状态可能在对应规则出现之前就进入处理程序。

选择 Webhook、API 轮询或两种方案

Webhook 是服务在订单状态变化时向你的 URL 发送的请求。API 轮询则相反：你的系统按间隔请求订单信息。对于完成通知，通常 Webhook 更方便，因为更新无需持续请求状态检查方法即可到达。

• Webhook 适合快速响应：更新卡片、启动下一阶段或向负责人发送消息。
• 如果供应商不支持回调通知，或服务器无法接收外部请求，则适合使用轮询。
• 组合方案以 Webhook 作为主要通道，轮询用于查找遗漏或卡住的订单。

轮询的缺点是延迟和对 API 的额外负载。Webhook 的缺点是必须保护 endpoint、考虑重复事件，并且不能依赖事件投递顺序。

设置用于接收事件的 endpoint

通知需要一个可从 API 服务侧访问的公共 HTTPS 地址。在集成设置中通常指定处理程序 URL、签名密钥和事件列表：状态变更、完成、取消、错误或部分完成。

为 API 事件单独分配一个路由。这样更容易设置日志记录、限制访问、设置请求限额，并且不会将服务流量与网站表单混在一起。不要将测试环境地址用于生产订单：环境更新后，供应商会继续向保存的 URL 发送事件。

启动前，请根据文档检查请求方法和请求体格式。最常见的是带 JSON 的 POST，但也会遇到 form-data、query 参数或自定义序列化方案。解析错误必须写入日志，否则将难以区分错误 payload 和应用故障。

保存订单与事件之间的关联

通过 API 创建订单时，保存供应商返回的标识符。同时保存内部订单号、服务类型、原始状态、最后修改时间以及安全形式的原始 API 响应。传入的 Webhook 应按供应商 ID 匹配，而不是按频道链接、服务名称或客户姓名匹配。

如果 API 允许在创建时传递外部标识符，请将你的订单号添加到类似 external_id 或 client_reference 的字段中。这可以简化日志搜索和争议情况排查。但不要让外部编号成为唯一键：部分供应商不会在每个通知中返回它。

不要根据 Webhook 中的未知 ID 创建新订单。未知事件应保存到日志并单独检查。自动创建记录可能导致错误数据或处理伪造请求。

使用清晰的 payload 结构

字段的确切名称取决于 API。以下不是某个具体服务的契约，而是 JSON 事件示例，可用于设计内部处理程序时参考。重要的是事件标识符、供应商订单 ID、状态、修改时间以及用于诊断的数据。

{

  "event_id": "evt_7f31",

  "event_type": "order.status_changed",

  "created_at": "2025-01-15T12:40:00Z",

  "data": {

    "order_id": "provider_order_4815",

    "external_id": "internal_order_9021",

    "status": "completed",

    "completed_quantity": 1000,

    "requested_quantity": 1000

  }

}

不要在没有状态的情况下将已完成单位数量作为完成标志。订单可能部分完成，而 payload 中的数字可能被四舍五入、延迟更新或根本未传递。保存完整事件体的缺点是其中可能包含个人数据或服务字段，因此此类记录需要脱敏并限制保存期限。

根据原始请求体验证签名

开放的处理器 URL 可能收到不仅来自 API 服务的请求。如果供应商传递签名、密钥或令牌，请在更改订单之前验证它们。常见方案是 HMAC-SHA256：供应商根据请求体字节和共享密钥计算签名，然后将结果放在 HTTP 头中传递。

计算原理如下：取原始请求体，例如未经修改的 JSON 字节，以及集成密钥。然后计算 HMAC-SHA256。如果十六进制结果与头中的值一致，则说明签名后请求体未被修改，并且请求很可能由知道密钥的一方发送。

条件示例：HMAC_SHA256(secret, raw_body) = X-Signature 头中的签名。头名称、算法和结果格式只能取自 API 文档。某些服务会将时间戳或事件 ID 添加到用于签名的字符串中。在这种情况下，不能只验证 JSON 请求体。

验证签名前不要修改 JSON

签名应基于原始请求字节验证，而不是基于应用已经解析并重新组装后的 JSON 对象。重新序列化可能改变字段顺序、空格、字符转义、换行或编码。对用户来说 JSON 看起来相同，但字节集合会变化，HMAC 将不再匹配。

为避免这种情况，先将 raw body 获取为 bytes 或 buffer，将其保存在内存中，计算签名，并且只有在验证成功后才解析 JSON。不要对请求体执行 trim、编码转换、键排序和格式化。在框架的 middleware 中检查 JSON 是否在访问原始请求体之前被自动解析。

此方案的缺点是处理程序会依赖 middleware 顺序。配置错误时，应用将只能看到转换后的对象，合法通知会开始被拒绝。

带 HMAC 验证的处理程序示例

以下是 Python 条件示例。它展示操作顺序，而不是现成集成：头、算法、签名格式和 payload 字段需要替换为供应商文档中的值。

import hmac

import hashlib

import json

from hmac import compare_digest

def handle_webhook(request):

  raw_body = request.body

  received_signature = request.headers.get("X-Signature", "")

  secret = get_webhook_secret()

  expected_signature = hmac.new(

    secret.encode("utf-8"), raw_body, hashlib.sha256

  ).hexdigest()

  if not compare_digest(expected_signature, received_signature):

    log_invalid_signature(request)

    return response(status=401)

  payload = json.loads(raw_body.decode("utf-8"))

  return process_event(payload)

比较时请使用不会在第一个不匹配字符处停止的函数。这可以降低通过响应时间泄露签名数据的风险。不要将密钥传递到客户端代码中，不要添加到 URL 中，也不要完整写入日志。

使事件处理具备幂等性

供应商可能多次投递同一事件。原因很常见：你的服务器响应时间过长、保存数据后连接中断、endpoint 临时返回错误，或服务按其规则启动了重新投递。重复并不意味着 API 创建了新订单。

幂等性意味着相同事件只会改变结果一次。如果不考虑此规则，重复事件会再次向客户发送消息、为经理创建多个任务、发放补偿或启动重复操作。

最好使用 payload 中的 event_id。将其保存在单独的表或已处理事件日志中，并设置唯一约束。如果没有单独 ID，则从稳定字段生成键：供应商订单 ID、事件类型、状态和修改时间。此方案较差：时间戳不准确时，不同事件可能看起来相同。

在同一操作中保存事件和状态

“事件是否已处理”的检查和结果写入必须原子执行。否则，同时到达的两个相同请求都会看到没有记录，并两次启动操作。实用方案是按 event_id 建立唯一索引并使用数据库事务。

处理程序的条件续写如下：

def process_event(payload):

  event_id = payload["event_id"]

  provider_order_id = payload["data"]["order_id"]

  new_status = map_status(payload["data"]["status"])

  with database_transaction():

    if event_exists(event_id):

      return response(status=200)

    order = find_order_by_provider_id(provider_order_id)

    if order is None:

      save_unmatched_event(event_id, payload)

      return response(status=200)

    apply_status_if_allowed(order, new_status, payload)

    save_processed_event(event_id, provider_order_id)

  enqueue_follow_up_actions(event_id)

  return response(status=200)

对未知订单返回成功代码的缺点是供应商可能不会重新投递。因此，未知事件需要单独监控并快速排查。如果 API 文档建议对此类情况使用其他响应代码，请遵循文档。

考虑事件顺序被打乱

Webhook 并不总是严格按照状态修改时间到达。可能先收到完成事件，然后才收到延迟的“进行中”状态通知。如果只是写入最后收到的值，已完成的订单会再次变为活动状态。

设置允许的转换。例如，中间状态不能覆盖最终状态，已取消订单在没有单独检查的情况下不能转为已完成。如果 API 允许调整最终状态，请保存原因、原始值和修改来源。

如果 payload 包含订单修改时间，请比较它，而不是 Webhook 接收时间。当 API 不传递此类标记时，使用状态优先级并通过获取订单方法进行核对。优先级的缺点是它们不能替代真实顺序，尤其是当供应商允许从最终状态退回时。

快速确认投递并将操作放入队列

不要在响应供应商之前执行长时间操作。签名验证、订单查找、事件写入和状态更新通常可以快速完成。发送消息、与 CRM 同步、生成报告或请求第三方系统最好交给任务队列。

工作顺序如下：验证签名、原子保存事件和状态变更、返回成功响应，然后执行次要操作。如果在保存之前响应，发生故障时数据会丢失。如果在长时间发送通知后才响应，供应商可能认为投递失败并发送重复事件。

队列的缺点是会出现一个需要控制的独立组件：任务错误、延迟和重复运行。但经理通知失败不会阻塞订单状态的接收。

为团队和客户设置通知

状态变更后，不需要以相同方式通知所有人。经理通常关心取消、错误、部分完成以及长时间未变化的订单。对客户而言，通常足够的是清晰的最终结果：订单已完成、已取消或需要澄清。

• 已完成订单 — 更新个人中心或向客户发送简短消息。
• 执行错误 — 向负责人发送通知，并附上 API 传递的原因。
• 部分完成 — 创建检查调整、退款或下一步操作的任务。
• 未知状态 — 写入日志并通知技术人员。
• 未知订单 ID — 单独检查你的系统与供应商之间的关联。

不要在每次技术转换时发送消息。信息流很快会变成噪音，而重要问题会被忽略。内部通知应包含订单号、服务、当前状态、外部 ID 和卡片链接。

维护日志并核对未完成订单

日志用于了解服务是否发送了事件、收到了什么请求体、签名为何未通过以及处理在哪个阶段停止。保存接收时间、事件 ID、订单 ID、事件类型、签名验证结果、内部状态和响应代码。对密钥、令牌和个人数据进行脱敏。

单独跟踪投递错误、无效签名、未知订单、不支持的状态、重复事件以及因状态顺序而无法应用的事件。此类记录增长可能意味着 API 架构变化、密钥过期、路由故障或处理程序逻辑错误。

定期通过 API 数据获取方法核对处于中间状态的订单。此检查不能替代 Webhook，但有助于发现遗漏事件、队列故障或外部状态在没有正确通知的情况下发生变化的情况。