電商整合不可能假設每次 API 都成功。Shopify rate limit、網路 timeout、ERP maintenance、WMS partial response 和程式部署都會造成失敗。真正風險是重試後重複訂單、漏庫存或營運無法知道哪些資料卡住。
可靠性設計要讓失敗可見、可安全重送，也能用權威來源補回。
先分類操作
讀取、建立、更新、adjust、set、刪除和外部副作用的重試風險不同。為每個 operation 定義 idempotency、唯一鍵、timeout、retryable status、permanent error 和 reconciliation 方式。
付款、退款、建單、發票和出貨屬高風險，需更嚴格確認結果。Timeout 不代表失敗，可能是對方完成但 response 遺失。
使用 durable queue
Webhook/排程只接收和驗證，將 message 寫入可靠 queue 後快速回應。Message 包含 event ID、resource ID、operation、occurred_at、schema version 和 attempt，不放不必要 PII。
Worker 可水平擴展但需控制同一 resource 的 concurrency。Queue outage 時明確 backpressure，不把事件只留在 process memory。
冪等避免重複副作用
建立外部訂單、退款和發票使用穩定 idempotency/external ID。處理前查 local ledger，完成後保存 target ID。相同 message 重送回既有結果，不再執行。
Inventory adjustment 若無冪等支持，優先使用 versioned absolute state 或保存 adjustment ledger。不能遇 timeout 就盲目再加十件。
重試只處理暫時錯誤
429、5xx、timeout 和短暫網路問題使用 exponential backoff、jitter、最大次數與 Retry-After。Validation、permission、not found 和 business rule 通常需人工或程式修正，不要無限重試。
Circuit breaker 防止下游故障時持續壓垮；恢復後逐步放量。Retry budget 與 queue age 進監控。
Dead letter 可操作
超過重試或 permanent error 進 DLQ，保存原因、payload reference、attempt、owner 和 next action。營運介面可查 resource、修正 mapping/資料後 replay，需權限與 audit。
不要讓 DLQ 成為無人查看的倉庫。按訂單、付款、庫存、內容分 severity 和 SLA。
Reconciliation 補漏
Webhook 不保證完全送達或按順序，定期以 updated_at watermark 和 overlap 從 Shopify/owner system 拉取。逐 ID、version 和關鍵欄位比較，補 missing/stale，跳過已處理。
全量 count 只能找大差異。訂單、庫存、refund 等需要 item-level 對帳。
處理順序和版本
保存 occurred_at、updated_at、source version。舊 update 晚到時不可覆蓋新狀態；delete、recreate 和 merge 需 tombstone/規則。對狀態型 resource 可重新 fetch latest，不依事件重播推導。
Webhook 細節可參考 Shopify Webhook 驗證。
建立可觀測性
Metrics 包括 success/failure、latency、queue depth/age、retry、DLQ、rate limit、reconciliation differences 和 end-to-end freshness。Log 用 correlation ID 串 Shopify event、message、target request 和結果，敏感資料遮蔽。
Alert 以商業影響設計：付款/訂單立即、庫存延遲依銷速、內容同步可較低。每個告警有 runbook。
人工 fallback
ERP/WMS 中斷時，定義哪些訂單可人工建立、庫存安全值、資料 freeze 和恢復後 merge。人工補單使用相同 external ID，避免系統恢復後再建一張。
所有手動變更進 ledger，reconciliation 能識別。高峰前演練 queue backlog、下游 outage、token 失效和 rollback。
可靠整合不代表零失敗。它代表失敗不會悄悄丟資料，重試不會重複副作用，且團隊能在 SLA 內找出、補回和證明一致。