跳轉到主要內容

​
冪等性與重試

配送標籤涉及實際的成本和物流影響。重複標籤會導致營運混亂、配送費用浪費以及庫存追蹤錯誤。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。