Openapi For Warehouse FAQ – OneWarehouse

Q1：各 API 的含義是什麼？哪些是必要串接的API？

答：為了確保 OneWarehouse (OW) 與貴司 WMS 系統能順暢協作，API 分為「推送（Push）」與「查詢（Query）」兩大類。帶有 ⭐️ 符號的為強烈建議必接的核心接口。

A. 業務推送與回傳API

業務場景	API 名稱	傳遞方向	觸發與應用情境描述
商品	⭐️ 商品同步	OW ➔ WMS	OW 新增或更新商品檔案時，推送資料給 WMS 建檔。
入庫	⭐️ 採購入庫單下單	OW ➔ WMS	OW 建立「採購入庫單」後，推送單據給 WMS 準備收貨。
	⭐️ 退貨入庫單下單	OW ➔ WMS	OW 執行「退貨入庫單」後，推送退貨資訊給 WMS。
	⭐️ 入庫單取消	OW ➔ WMS	OW 發起入庫單（含採購/退貨）作廢時，推送取消請求。
	⭐️ 入庫單回傳 (Callback)	WMS ➔ OW	WMS 實際完成收貨入庫後，回傳「入庫狀態與實際明細」給 OW。
出庫	⭐️ 出庫單下單	OW ➔ WMS	OW 執行出貨時，推送「出庫訂單」給 WMS 安排揀貨包裝。
	⭐️ 出庫單取消	OW ➔ WMS	OW 發起攔截出貨時，推送取消出貨請求給 WMS。
	⭐️ 出庫單回傳 (Callback)	WMS ➔ OW	WMS 完成包裝出庫後，回傳「出庫狀態、包裹與出庫明細」給 OW。
	⭐️ 倉庫取消出貨	WMS ➔ OW	當 WMS 發現異常（如缺貨/破損）需主動中斷出貨時，推送取消請求給 OW。

B. 查詢與輔助API

業務場景	API 名稱	傳遞方向	觸發與應用情境描述
出庫	⭐️ 獲取運單 (面單)	WMS ➔ OW	WMS 查詢出庫訂單的物流運單圖檔（回傳 PDF 格式之下載連結）。
	獲取自畫運單參數	WMS ➔ OW	若 WMS 不直接取圖檔，可獲取運單底層參數，由 WMS 系統自行繪製渲染運單。
	⭐️ 申請拆包介面	WMS ➔ OW	當倉庫發現一筆訂單過大需拆分為多個包裹時，呼叫此介面申請新的子運單號。
庫存	⭐️ 查詢庫存	OW → WMS	OW 根據後臺排程或業務需要，主動向 WMS 查詢倉庫實際庫存數量，並同步更新 OW 庫存數據。
基礎	獲取商家資訊	WMS ➔ OW	WMS 查詢貨主（Merchant）的公司名稱等基本資料。

Q2： API 的系統觸發節點為何

答：以下為 OW 系統觸發呼叫的具體操作節點：

API名稱	業務類型	觸發節點與執行動作	操作路徑 (OW 後台)
商品同步	商品	1. 新商品：點選採購入庫單的【保存】按鈕。 2. 舊商品 (已入庫)：點選編輯商品頁的【保存】按鈕。	1. 採購入庫 > 建立入庫單 2. 商品管理 > 編輯
採購入庫單下單	入庫	點選採購入庫單的【保存】按鈕。	採購入庫 > 建立入庫單
退貨入庫單下單	入庫	點選退貨單 (待處理) 的【執行退貨】按鈕。	退貨管理
入庫單取消	入庫	點選入庫單 (待入庫) 的【作廢】按鈕。	採購入庫
出庫單下單	出庫	點選訂單 (待處理) 的【執行出貨】按鈕。	訂單管理
出庫單取消	出庫	點選訂單 (待出庫) 的【攔截出貨】按鈕。	訂單管理
查詢庫存	庫存	由 OW 內部排程配置的定時觸發。	(系統後台執行)

Q3：回調 Key 和下發 Key 的對應用途為何？以什麼為基準去檢查 Webhook Request？

答：這兩組密鑰在系統交互中扮演身分驗證的關鍵角色：

【回調 Key (Callback Key)】

用途：WMS 在入庫/出庫操作成功後，回調 OW 系統時的「身分驗證」。確保請求來源合法，防止未經授權的訪問。
檢查基準：
1. 密鑰一致性：檢查請求中的密鑰與 OW 系統中儲存的回調 Key 是否完全一致。
2. 來源驗證：確認請求確實來自 WMS 系統。
3. 時間戳與簽名 (如適用)：結合時間戳和簽名進行驗證，確保即時性與數據完整性。

【下發 Key (Push Key)】

用途：OW 系統呼叫 WMS 系統時的「身分驗證」。OW 會將包含 sign (簽名)、timestamp (時間戳) 等欄位的請求發給 WMS。
檢查基準：
1. 加密結果一致性：WMS 需使用下發 Key 及指定加密方式對請求參數進行加密，結果必須與請求中的 sign 完全一致。
2. 參數驗證：驗證 timestamp 等參數，確保請求沒有過期。
3. 安全性：確保使用的加密算法安全，無已知漏洞。

Q4：在多貨主 (Multi-Merchant) 業務場景中，WMS 如何區分貨主身份？

答：在 API 參數中，系統統一使用 account_no 欄位作為貨主的唯一身分 ID。

實作建議：請在貴司 WMS 系統中，將內部建立的貨主檔案與 OW 下發的 account_no 進行對應關聯。如此一來，WMS 即可準確識別並處理不同商家的商品、單據與庫存資訊。

Q5：是否需要設置 IP 白名單限制？

答：視 WMS 系統的安全需求而定，OW 端不設 IP 限制。

WMS 端限制（可選配置）：如果貴司 WMS 系統有訪問來源的安全限制需求，我們提供了 OneWarehouse 系統的固定出口 IP。請在貴司的防火牆/網關中將以下 IP 加入白名單，以便順利接收 OW 的推送請求。
OW 端限制（無需配置）：當 WMS 系統回調 OneWarehouse 網關時，OW 系統不會進行 IP 白名單限制，貴司無需提供出口 IP 予我們。

OneWarehouse 系統固定出口 IP 地址列表（供 WMS 設定白名單使用）：

121.11.221.130
121.11.221.131
52.77.143.211
122.248.196.11
46.51.219.5
13.214.244.173
18.143.33.165
13.215.123.123
120.78.70.56
120.78.69.89
120.78.67.40
120.78.71.91

Q6：推送到倉庫才發現「庫存不足」（需行政配貨）的建議處理方式？

常態情況下，OW 會保持庫存數量與倉庫相等，若庫存不足以出庫，訂單在 OW 系統端就會被阻擋，不會推送到倉庫。因此，推送到倉庫才發現庫存不足屬於較異常的少數情況（如倉庫自行調整WMS庫存數量，未通知OW進行同步更新）。
若倉庫在訂單下達時無法立即判斷庫存是否充足，可先按正常單接收處理。後續若確認庫存不足，建議採用以下兩種處理方式：

方法一：呼叫「倉庫取消出貨」API——強烈推薦

貴司 WMS 可呼叫「倉庫取消出貨API」，並在 message 欄位中註明取消原因為「庫存不足」，OW 收到通知後系統會自動將此單據攔截作廢。此方法能有效自動化流程並節省人工溝通成本。

方法二：人工通知商家

採線下通知方式（如客服/Email），讓商家自行至 OW 系統後台操作攔截訂單。

Q7：訂單取消的時機點，平台端是否有特別的規範或限制？

倉庫端不需要去考量上游平台取消訂單的時間節點和規則。

只要訂單尚未完成出貨，隨時都有可能發起取消動作。但是否能「成功取消」，完全由倉庫方（WMS）來判斷和決定：

允許取消：若倉庫評估作業流程尚可攔截，則接受取消請求，終止出貨作業。

拒絕取消：若倉庫判斷該訂單出貨已進入關鍵節點（如已打包裝車）不允許取消，請倉庫在收到取消訂單 API時直接拒絕取消訂單。OW 系統接收後便會阻擋商家的攔截流程。若商家後續仍有攔截需求，會透過人工方式聯絡倉庫發起線下溝通。