本文適用於需要將倉庫管理系統（WMS）與 OneWarehouse（OW）進行系統對接的倉庫合作夥伴。透過 OpenAPI 對接後，OneWarehouse 可將商品、入庫單、退貨入庫單、出庫單及取消指令推送至倉庫 WMS；倉庫也可依據實際作業結果，透過回調介面將入庫、出庫、取消、異常等處理結果同步回 OneWarehouse。
如需查看完整欄位、請求示例與錯誤碼，請參閱 OneWarehouse OpenAPI 文件。：OneWarehouse OpenAPI 文檔。
一、整體對接流程
OpenAPI For Warehouse 的接入流程分為四個階段：
- 接入準備
確認雙方系統職責、業務場景與需要對接的 API 範圍。 - 介面配置
倉庫方提供 WMS 接收端點，OneWarehouse 配置 Webhook 推送地址；同時確認倉庫回調 OneWarehouse 的方式與鑑權資訊。 - 沙盒聯調
使用 OneWarehouse 沙盒環境建立商品、入庫單、退貨單、出庫單等測試資料，驗證雙方資料流是否正確。 - 正式上線
完成所有必要 API 測試後，切換至正式環境，並完成線上首單驗證。
二、系統資料流說明
OneWarehouse 與倉庫 WMS 的資料流分為兩個方向：
1. OneWarehouse 推送至倉庫 WMS
此方向由 OneWarehouse 主動發送請求至倉庫方提供的 API URL。主要用於建立或更新商品、入庫單、出庫單及取消指令。
範例場景：
- 商家在 OneWarehouse 建立採購入庫單後，OW 將入庫單資料推送至 WMS。
- 商家在 OneWarehouse 執行出庫後，OW 將出庫單、收件人、商品明細、物流方式等資料推送至 WMS。
- 商家在 OneWarehouse 發起攔截出貨或取消入庫時，OW 將取消請求推送至 WMS。
2. 倉庫 WMS 回調 OneWarehouse
此方向由倉庫 WMS 在作業狀態變更後，將處理結果同步回 OneWarehouse。
範例場景：
- 倉庫完成入庫驗收後，回傳實收數量及入庫狀態。
- 倉庫完成出庫後，回傳出庫完成狀態、物流單號、包裹資訊或面單資訊。
- 倉庫拒絕取消、取消失敗或發生異常時，回傳對應的處理結果與原因。
具體回調接口、請求欄位與狀態碼，請以 OpenAPI 文件中的最新規範為準。
三、倉庫方需提供的 API 接收端點
在建立沙盒環境前，請倉庫方先提供以下 API 接收端點。OneWarehouse 會根據業務觸發節點，將 JSON 格式資料推送至對應 URL。
| API 類型 | 功能說明 | 邏輯說明 |
|---|---|---|
| 商品同步 API | 同步商品基本檔案 | 當商品首次建立或商品資料更新時，OneWarehouse 將商品資料推送至 WMS。若 sku_id 已存在，WMS 應執行更新；若不存在，WMS 應執行新增。 |
| 採購入庫單 API | 建立採購入庫任務 | 用於 OneWarehouse 將採購入庫單資料推送至 WMS，倉庫可依此建立入庫作業任務。 |
| 退貨入庫單 API | 建立退貨入庫任務 | 當商家處理退貨並執行入庫時，OneWarehouse 會將退貨入庫資料推送至 WMS。 |
| 入庫單取消 API | 取消未完成入庫單 | 當商家發起入庫取消或攔截時，WMS 需根據目前作業狀態回傳是否允許取消。 |
| 出庫單下單 API | 建立出庫發貨訂單 | 用於 OneWarehouse 將出庫訂單、收件人資訊、商品明細、物流商資訊等資料推送至 WMS。 |
| 出庫單取消 API | 取消未出庫訂單 | 當商家發起攔截出貨時，WMS 需根據目前出庫進度回傳是否攔截成功。 |
⚠️ 注意：上述 API URL 是建立沙盒測試環境的必要前置資料。若尚未提供，OneWarehouse 無法完成 Webhook 配置，也無法提供完整的沙盒聯調環境。
四、 沙盒環境準備
在正式上線前，請先於 OneWarehouse 沙盒環境完成開發與測試。
1. 倉庫方需提供
請提供以下資訊給 OneWarehouse 對接團隊：
- 商品同步 API URL
- 採購入庫單 API URL
- 退貨入庫單 API URL
- 入庫單取消 API URL
- 出庫單下單 API URL
- 出庫單取消 API URL
- 測試用倉庫代碼
- 技術對接人與聯絡方式
2. OneWarehouse 將提供
OneWarehouse 對接團隊會在完成配置後提供：
- 沙盒客戶端入口
- 沙盒測試帳號
- 測試用 AppSecret 或其他鑑權資料
- 技術對接群組
基於安全考量，AppSecret 等敏感資訊建議透過對接群組或指定方式單獨提供。
五、 聯調與測試流程
步驟 1：登入沙盒客戶端觸發測試
倉庫方可透過 OneWarehouse 沙盒客戶端執行以下操作，觸發對應 API 推送。
| 測試項目 | 觸發方式 |
| 商品同步 API |
首次商品同步通常會在建立採購入庫單並保存時觸發； 既有商品更新則可透過編輯商品並保存觸發。 |
| 採購入庫單 API | 建立並保存採購入庫單時觸發。 |
| 退貨入庫單 API | 針對待處理退貨單，執行入庫處理時觸發。 |
| 入庫單取消 API | 針對待入庫單，執行作廢、取消或攔截入庫時觸發。 |
| 出庫單下單 API | 針對待處理訂單，執行出庫時觸發。 |
| 出庫單取消 API | 針對待出庫訂單，執行攔截出貨或取消出庫時觸發。 |
步驟 2：檢查 WMS 接收結果
倉庫方需確認 WMS 是否正確收到 OneWarehouse 推送資料，並檢查以下項目：
- API 是否有收到請求
- Request Body 是否完整
- 欄位格式是否符合預期
- WMS 是否成功建立對應單據
- WMS 是否正確回傳 Response
- OneWarehouse 是否正確顯示推送結果
步驟 3：測試 WMS 回調 OneWarehouse
若對接範圍包含倉庫回調，倉庫方需根據 OpenAPI 文件完成回調測試，包含但不限於：
- 入庫完成回調
- 出庫完成回調
- 出庫物流資訊回調
- 取消結果回調
- 異常狀態回調
回調測試時，請確認 OneWarehouse 是否能正確更新單據狀態與物流資訊。
步驟 4：異常排查
測試期間若出現資料未同步、狀態不一致、欄位錯誤或接口報錯，請在對接群組中提供以下資訊：
- OneWarehouse 單號
- 錯誤截圖
- WMS 系統日誌
OneWarehouse 技術團隊會根據日誌協助排查。
六、測試驗收標準
完成沙盒聯調前，建議至少通過以下測試項目：
| 測試項目 | 驗收標準 |
| 商品同步 | 商品可從 OneWarehouse 成功推送至 WMS，且新增、更新邏輯正確。 |
| 採購入庫 | 採購入庫單可成功建立至 WMS，商品明細與數量正確。 |
| 退貨入庫 | 退貨入庫單可成功建立至 WMS，退貨商品與數量正確。 |
| 入庫取消 | WMS 可依照實際作業狀態回傳取消成功或取消失敗。 |
| 出庫下單 | 出庫單可成功建立至 WMS，收件人、商品、物流方式等資料正確。 |
| 出庫取消 | WMS 可依照出庫進度回傳攔截成功或攔截失敗。 |
| 倉庫回調 | WMS 可將作業結果成功同步回 OneWarehouse。 |
| 異常處理 | 當資料錯誤或業務狀態不允許時，WMS 可回傳明確錯誤訊息。 |
七、正式上線流程
- 上線申請：當所需對接的所有API通過聯調測試，且雙方確認數據流轉準確無誤後，即可向我方申請切換至生產環境。
-
參數切換：我方將正式提供生產環境專用的
AppSecret以及正式版的客戶端連結。 - 正式發佈：請將貴司 WMS 的接收地址切換為生產網域名稱，配合完成最後的線上首單驗證後，即可正式上線運行。
如有任何技術疑問，請隨時聯繫 OneWarehouse 技術對接團隊。
評論
0 條評論
請登入寫評論。