ERP、電商、金流與物流不同步？可靠 API 串接的實作重點

具體問題與執行難點：網路恢復了，資料不一定會自己正確

API 呼叫回傳逾時，不等於對方沒有完成工作。電商送出建立出貨要求後如果沒有收到回應，盲目再送一次可能建立兩張託運單；金流 Webhook 重送同一個付款成功事件，若系統沒有去重，也可能重複入帳、發送通知或增加點數。可靠性設計必須區分尚未處理、已完成但回應遺失，以及確定失敗。

事件也不保證按照商業流程抵達。退款通知可能早於本地端的付款成功事件，物流的已送達可能在處理中之後才被系統接收，舊資料重送也可能覆蓋較新的狀態。只要收到事件就直接更新資料庫，容易讓訂單倒退或產生不可能的狀態。

多系統之間還會出現資料語意差異：ERP 的已出貨可能表示倉庫過帳，物流的已取件才代表包裹離開；金流交易編號、網站訂單編號與發票號碼也不是同一個鍵。若沒有共同識別碼、欄位映射與責任邊界，團隊只能在事故發生後用人工比對猜測哪一筆資料可信。

• 逾時與斷線造成結果未知，直接重送可能重複執行
• Webhook 可能重複、延遲或亂序，不能假設只來一次且依序抵達
• ERP、電商、金流與物流對狀態、金額和識別碼可能有不同定義

何時值得做：當串接已經影響收款、出貨或客戶承諾

如果每天只有少量交易，人工匯出與核對可能比即時整合更經濟。當訂單跨越電商、ERP、金流、發票與物流，且失敗會造成重複扣款、錯誤出貨、庫存不準或客服大量查單時，就值得把可靠性視為正式系統需求，而不是上線後再補的技術細節。

另一個訊號是問題只能由工程師查資料庫處理。營運人員若看不到某筆事件在哪一站失敗、是否已重試、應該重新執行或人工確認，每次異常都會變成臨時救火。可靠整合除了程式碼，也必須提供可供營運使用的狀態、告警、搜尋和處理介面。

以電商平台的出貨串接為例：系統在付款後建立 ERP 訂單，再向物流申請託運單。促銷期間物流服務短暫逾時，系統同步重送請求，隔天發現部分訂單有兩張託運單，另一些訂單在物流成功後仍停留於待出貨。此時需要的不是增加一次重試，而是為每一步建立唯一識別、冪等處理、佇列、狀態轉移與對帳機制。

• 跨系統錯誤已影響金額、庫存、出貨或對客戶的承諾
• 交易量或尖峰使人工逐筆補救無法在合理時間內完成
• 企業需要知道失敗位置、影響範圍、處理責任與是否已恢復

AgentTech 方法與技術設計：驗證來源、只執行一次，並允許安全恢復

入口先驗證事件是否可信。AgentTech 會依供應商規格使用簽章、共享密鑰、時間戳與容許時間差驗證 Webhook，並保留必要的原始事件與標頭供查核；密鑰放在受控環境中並建立輪替方式。驗證失敗、過期或格式不符的請求不進入商業流程，同時避免在日誌中暴露完整個資、憑證或付款資訊。

每個外部事件以供應商事件 ID 或可重現的複合鍵去重。對外建立訂單、退款或託運單時使用 idempotency key（冪等鍵），本地端也建立唯一限制與處理紀錄，確保同一意圖即使被重送仍只產生一次結果。若第一次回應遺失，系統會先依冪等鍵或外部交易編號查詢結果，而不是直接建立第二筆。

接收端快速驗證並寫入事件後，將耗時工作交給非同步佇列。暫時性錯誤採限制次數與退避間隔重試；不可解析、規則衝突或超過重試上限的事件進入 dead-letter queue（死信佇列），等待告警與人工處理。每次嘗試保留時間、回應摘要與追蹤 ID，讓一次交易能跨服務被搜尋。

亂序事件由明確狀態機處理，而不是直接覆寫。系統比較外部版本、事件時間與允許的狀態轉移；無法安全判斷時先保留事件並標示待確認。即使即時流程設計完整，仍要定期以訂單、交易、金額與狀態進行 reconciliation（對帳），找出漏接事件、長時間卡住或兩邊結果不一致的紀錄。

• 簽章與時間戳驗證來源，事件 ID 與唯一限制防止重複處理
• 冪等鍵保護建立、退款、扣款與託運等不可隨意重複的操作
• 非同步佇列、受控重試、死信佇列與狀態機處理暫時失敗及亂序
• 追蹤 ID、結構化日誌、指標、告警與定期對帳建立完整可觀測性

分階段落地：先保護高風險交易，再逐步接管更多流程

第一階段盤點所有介接點、資料方向、認證方式、速率限制、逾時、重送規則與供應商服務窗口，並畫出付款、訂單、庫存、出貨、取消與退款的狀態對照。接著用歷史異常案例建立風險清單，優先處理會造成金額錯誤、重複履約或資料遺失的流程。

第二階段建立整合骨架：統一識別碼與欄位映射、Webhook 接收器、事件儲存、冪等紀錄、佇列工作、重試與死信處理，再將一條高價值流程接入。測試環境會模擬重複事件、逾時、斷線、亂序、無效簽章、速率限制與部分成功，確認重送不會製造額外交易。

第三階段加入營運監控與對帳。儀表板顯示成功量、失敗率、重試次數、佇列延遲、死信數與長時間未完成交易；告警依影響程度通知負責人。每日或定期對帳將本地訂單與外部交易、物流或 ERP 紀錄比較，並提供重試、忽略、修正映射或人工完成等受權限控制的處理動作。

• 階段一：介接盤點、狀態與資料映射、風險分級、失敗責任與復原流程
• 階段二：可靠事件處理骨架、單一關鍵流程、故障注入與整合測試
• 階段三：營運後台、分級告警、定期對帳與持續容量調整

最終交付物與驗收：每筆交易都能查到、重送且對得起來

AgentTech 的交付可包含 API／Webhook 介接服務、簽章驗證、事件儲存、去重與冪等機制、非同步佇列、重試策略、死信處理、狀態轉換、跨系統追蹤，以及營運查詢與人工復原後台。依專案範圍，也會提供 reconciliation 對帳工作、監控儀表板與告警規則，讓整合不是只有工程師才能理解的黑盒子。

文件交付包含介接契約、欄位與狀態映射、識別碼規則、認證與密鑰管理方式、錯誤分類、重試與升級處理表、資料保留原則、部署設定與操作手冊。若外部供應商有速率限制、維護時段或資料一致性限制，也會明確記錄，不把第三方能力包裝成無條件保證。

驗收應以可重現的失敗情境為核心：相同 event ID 傳送多次只產生一次結果；同一 idempotency key 重試不重複建立交易；亂序事件不讓狀態倒退；暫時失敗按規則重試；永久失敗進入死信並產生告警；人工重送保留操作者與原因；對帳能找出預先植入的漏單與金額差異。上線前還應確認尖峰容量、告警接收人、供應商憑證輪替和災難復原方式。

• 可執行服務：介接端點、事件處理、佇列工作、狀態同步與營運後台
• 可靠性機制：驗證、去重、冪等、重試、死信、亂序保護、對帳與監控
• 技術與營運文件：契約、映射、錯誤手冊、權限、部署與復原程序
• 驗收證據：重複、逾時、亂序、部分失敗、對帳差異與容量測試紀錄