物流 API 串接：WMS 與電商訂單同步的五個檢查點

這篇文章適合誰

• 電商營運／客服主管：需要掌握「平台顯示有貨、倉庫卻出不了」的根因，評估 API 串接時程。
• 技術／倉儲系統負責人：維護 WMS、OMS 或 .NET 中介層，負責訂單下拋、庫存回寫與物流狀態同步。

問題背景

電商平台、品牌官網與倉儲系統（WMS）往往由不同供應商或部門維護。訂單成立在平台、揀貨在倉庫、物流狀態在第三方——若仍靠 CSV 匯入或定時人工對單，促銷檔期的訂單量會讓延遲從「幾分鐘」變成「半天」。

常見症狀包括：

• 平台已扣庫存，WMS 尚未收到訂單，超賣客訴上升
• 出貨單已在倉庫完成，電商後台仍顯示「備貨中」
• 逆物流（退貨入庫）只更新一邊，財務與客服各持一份 Excel

決策者摘要：物流 API 的價值不是「少按幾次匯出」，而是訂單與庫存狀態有單一可對帳的時間軸；上線前先定義誰是庫存權威、狀態怎麼流。

檢查點一：釐清庫存權威與預留策略

決策者關注： 超賣一次對品牌傷害大於串接專案預算；必須先回答「以誰的庫存數字為準」。

技術重點：

• 指定庫存權威系統（通常 WMS 實際庫存，平台為可售庫存展示）
• 訂單成立時：先預留（reserve）再確認扣減，避免並發下單穿透
• 可售量 = 實際庫存 − 已預留 − 安全庫存；公式寫進整合規格
• 多倉、多通路時，路由規則（就近倉、指定倉）要在 API 層可設定
• 缺貨時回寫平台可預期狀態（部分出貨、拆單），而非靜默失敗

檢查點二：訂單狀態機與事件順序

決策者關注： 客服與消費者看到的狀態若與倉庫不一致，信任感比技術債更難修復。

技術重點：

• 定義跨系統狀態機：已付款 → 已下拋 WMS → 揀貨中 → 已出貨 → 配送中 → 已完成
• 每個轉換由單一事件觸發（Webhook、輪詢或訊息佇列），禁止雙向任意改狀態
• 使用冪等鍵處理重複 webhook（物流商常重送同一出貨通知）
• 狀態回寫延遲可接受範圍寫入 SLA（例如 WMS 出貨後 5 分鐘內平台必須更新）
• 異常狀態（取消、改址、攔截）有獨立流程，不與正常出貨共用同一 API

狀態	建議寫入系統	對外顯示
已預留庫存	中介層 / OMS	平台：備貨中
已出貨	WMS	平台：已出貨 + 物流單號
配送簽收	物流 API	平台：已完成

檢查點三：API 契約、節流與尖峰演練

決策者關注： 大檔促銷若把 WMS 打掛，停倉成本遠高於平日介接維護費。

技術重點：

• 訂單下拋與庫存查詢分離 API，讀寫分離與速率限制分開設定
• .NET 中介服務實作佇列緩衝：平台訂單先進佇列，依 WMS 吞吐平滑送出
• 契約版本化：欄位（收件人、SKU、數量、倉別）有 schema 驗證與錯誤回傳
• 尖峰演練：模擬 3× 平日訂單量，觀察佇列深度、錯誤率、最舊未處理訂單年齡
• 與物流商 API 設定逾時、重試與斷路器；失敗訂單進死信佇列人工處理

檢查點四：逆物流與部分出貨

決策者關注： 退貨旺季若只串正向出貨，退貨單仍靠人工，庫存準確度會在季末暴雷。

技術重點：

• 退貨入庫、換貨、部分出貨從第一天就納入狀態機——不要「第二階段再做」
• 退貨授權號與原訂單關聯，WMS 入庫後回寫平台釋放可售庫存
• 拆單出貨：子單各自物流單號，母單狀態由子單聚合（全部出貨才標完成）
• 取消訂單需釋放預留；若已揀貨，走攔截流程而非直接刪單

檢查點五：對帳、告警與人工例外

決策者關注： 自動化上線後，管理層要問的是「昨天有沒有漏單」，不是「API 通不通」。

技術重點：

• 每日對帳：平台訂單筆數 vs. WMS 接收筆數 vs. 出貨回寫筆數
• 差異報表附訂單編號與 trace id，客服與倉儲可協同處理
• 告警：佇列堆積超過閾值、連續 webhook 失敗、庫存差異超過比例
• 人工例外工作台：允許單筆重送、強制同步狀態（需權限與稽核 log）
• 保留降級模式：API 中斷時改為受限批次匯入，並標記待補同步訂單

上線節奏建議

階段	範圍	驗收
第一階段	單一倉、單一平台、正向出貨	對帳零差異連續 7 日
第二階段	多 SKU 促銷、佇列與節流	尖峰演練通過
第三階段	逆物流、拆單	退貨季前完成

下一步

若貴單位電商與 WMS 仍靠檔案交換，建議先完成庫存權威與狀態機工作坊，再評估 .NET 中介層範圍。我們在電商訂單與倉儲串接有類似專案經驗——歡迎透過網站聯絡討論現況盤點。