跳转到主要内容

​
幂等性与重试

配送标签涉及实际的成本和物流影响。重复标签会导致运营混乱、配送费用浪费以及库存追踪错误。Flex Forward API 内建幂等性来防止此问题。

​
幂等性的工作方式

POST /labels 端点使用 idempotencyKey 字段来确保每个标签创建请求只会被处理一次。 第一次请求 — API 创建标签并返回 HTTP 201： 
curl -X POST https://api.flexforward.com/labels \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "ord-20250301-abc123",
    "courier": "yunexpress",
    ...
  }'
201 Created
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": "YT2503010001CN",
  "error": null
}
重放的请求 — 相同的 idempotencyKey 会返回原始结果（HTTP 200），而不会创建新标签：
200 OK（幂等重放）
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": "YT2503010001CN",
  "error": null
}
幂等性密钥的范围限于您的 API 账户。不同账户可以使用相同的密钥而不会冲突。

​
选择幂等性密钥

密钥应该唯一标识预期的标签创建。良好的模式：
模式示例使用场景
订单 IDord-20250301-abc123每个订单一个标签
订单 + 序号ord-20250301-abc123-1每个订单多个标签
UUIDf47ac10b-58cc-4372-a567-0e02b2c3d479通用
重试相同的逻辑请求时，绝不要生成新的 idempotencyKey。请重复使用原始密钥，以便 API 能检测重复。
400 验证错误后，由于未创建标签，可以重复使用相同的 idempotencyKey。修正请求后使用相同密钥重试。

​
重试策略

对于暂时性失败（HTTP 500、502 或网络超时），请使用指数退避重试：
1

设置请求超时

为 HTTP 请求设置合理的超时时间（例如 30 秒）。
2

失败时等待再重试

使用指数退避：1 秒、2 秒、4 秒、8 秒。
3

重复使用相同的幂等性密钥

始终使用与原始请求相同的 idempotencyKey 重试。即使原始请求已成功但响应丢失，也能确保不会创建重复标签。
4

限制重试次数

在 3–5 次重试后停止。如果请求仍然失败，记录错误并升级调查。
尝试 1: POST /labels → 超时
  等待 1 秒
尝试 2: POST /labels → 502
  等待 2 秒
尝试 3: POST /labels → 200（幂等重放 — 标签在尝试 1 时已创建）

​
各端点的幂等性

端点幂等机制
POST /labels是idempotencyKey 字段 — 每个请求中必填
GET /labels/{id}是只读 — 天然幂等
GET /tracking/{id}是只读 — 天然幂等

​
失败场景

标签可能已创建也可能未创建。使用相同的 idempotencyKey 重试。如果标签已创建，API 会返回 HTTP 200 和原始结果。如果未创建，API 会创建标签并返回 HTTP 201。
暂时性服务器错误。使用相同的 idempotencyKey 并以退避策略重试。
物流商服务返回错误。标签以 status: failed 保存。重试前请检查错误消息 — 部分物流商错误需要修改请求（如无效地址）。对于暂时性的物流商问题，使用相同的 idempotencyKey 重试。
请求无效。未修正请求前请勿重试。由于未创建标签，修正请求体后可以重复使用相同的 idempotencyKey。