新增串接
目錄
一、功能介紹
每一個要連進 GoWarehouse 的外部系統，都在這裡建立一組專屬憑證。建立時決定三件會長期影響這組串接的事：使用正式或舊版串接類型、允許它做哪些事、允許從哪些 IP 呼叫。建好之後系統會產生 client ID 與 access token，交給對方工程師設定到他們的系統裡。
1.1 基本資料
標示 * 的欄位為必填項目
| 欄位名稱 | 如何填寫 | 注意事項 |
|---|---|---|
| *名稱 | 填對方系統的名稱，例如「官網訂單系統」「XX 資訊 ERP」 | 之後在清單與用量排查時就靠這個名稱辨識，建議寫得具體 |
| 描述 | 補充用途、對接窗口或合約編號 | 選填，但換手時很有用 |
1.2 API 版本
預設只提供正式串接，可使用 v1 與已發布的日期版本。只有已開放舊版相容功能的環境，才會顯示 legacy v1／v2 選項。關閉舊版相容功能後，既有舊版憑證也無法再呼叫舊版 API；串接資料仍保留，可查看、停用或刪除，但切換串接的啟用狀態不會恢復舊版 API。
建立時選擇的是正式或舊版串接類型，這項分類無法變更。正式串接可用同一組憑證呼叫 v1 與已發布日期版本（包含 2026-10）；請對方工程師測試後切換呼叫的版本，不必重建憑證。跨正式／舊版類型才需要另建串接。
| 版本類型 | 適用情況 |
|---|---|
| 正式版本（v1 與日期版本） | 新的串接一律選這個。支援權限範圍設定，功能持續更新 |
| 舊版（legacy） | 只給早期既有系統沿用。沒有權限範圍的概念，憑證可存取該版本開放的全部功能 |
建立前請先與對方工程師確認他們要對接哪一個版本。
1.3 權限範圍
勾選這組憑證被允許做的事。只給對方真正需要的項目——權限範圍是外流時限制損害的主要防線。
| 類別 | 可勾選的項目 | 涵蓋範圍 |
|---|---|---|
| 訂單 | 讀取、寫入 | 訂單，以及這些訂單的託運單與物流追蹤 |
| 商品 | 讀取、寫入 | 商品資料與自訂屬性定義 |
| 入庫 | 讀取、寫入 | 入庫單 |
| 庫存 | 讀取 | 庫存批次、各倉水位與自訂屬性定義 |
| 地址簿 | 讀取、寫入 | 常用收件地址（建單時用 contact_address_code 帶入的那一組） |
| 退貨 | 讀取 | 退貨單 |
| Webhook | 讀取、寫入 | 讀取＝看訂閱設定與送測試；寫入＝建立、修改、刪除訂閱與重產密鑰 |
可以點類別標題一次勾選或取消整組。正式版本至少要勾選一項才能建立；舊版不需要勾選，該區塊不會出現。
地址簿是獨立的一類。給了「訂單」不會連地址簿一起給——對方要讀或寫你的常用收件地址，必須另外勾「地址簿」。
💡 提示：只送單、不需要改商品資料的系統，勾「訂單－寫入」與「庫存－讀取」通常就夠了。事後不夠用再到編輯串接加上去，比一開始全開安全得多。
1.4 IP 限制
限制只有指定來源才能使用這組憑證。留空代表不限制來源。
| 填法 | 範例 |
|---|---|
| 單一 IP | 203.0.113.10 |
| IP 範圍（CIDR 網段） | 203.0.113.0/24 |
一行一筆。格式不正確時儲存會被擋下並指出是哪一筆。對方系統若使用浮動 IP 或雲端服務，請先向他們確認固定的對外 IP 再填，否則會把正常呼叫擋掉。
1.5 Webhook（選填）
如果對方需要在訂單出貨、庫存異動等事件發生時收到即時通知，在這裡填寫接收網址與版本。不填代表對方改用主動查詢的方式取得資料。
Webhook 的簽章驗證與訂閱事件在建立完成後，可到編輯串接調整。訂閱的事件必須在「權限範圍」有對應的讀取權限（例如訂單事件需要訂單讀取），對照表見編輯串接。
1.6 建立完成
儲存後系統立即產生 client ID 與 access token。把這兩個值交給對方工程師——token 等同密碼，請用安全的方式傳遞，不要貼在公開的群組或工單裡。
二、常見問題
2.1 FAQ
▪ 我不知道對方要用哪個 API 版本，可以先建再改嗎？
建立時選擇的是正式或舊版串接類型，這項分類無法變更。正式串接可用同一組憑證呼叫 v1 與已發布日期版本（包含 2026-10）；請對方工程師測試後切換呼叫的版本，不必重建憑證。跨正式／舊版類型才需要另建串接。
▪ 權限範圍我全部勾起來會比較省事嗎？
會比較危險。憑證一旦外流，權限範圍就是唯一限制對方能做多少事的東西。全勾等於讓一組外流的 token 可以改你的商品、改你的訂單。建議照對方實際要做的事給，不夠用再加。
▪ IP 限制我該填嗎？
對方有固定對外 IP 的話建議填，這是很有效的第二道防線——即使 token 外流，從別的地方也用不了。對方若是雲端服務、IP 會變動，填了反而會擋掉正常呼叫，那就留空、改用權限範圍與定期更換 token 來控管。
▪ 一個系統可以建兩組憑證嗎？
可以，常見於對方要區分測試環境與正式環境。要注意每日用量額度是整個貨主共用的，多建幾組不會多拿額度。
▪ 建立之後 access token 還看得到嗎？
看得到，在串接詳情可以再次查看。但仍建議建立當下就交付給對方並妥善保管——能看到 token 的人等於能使用這組串接。
2.2 注意事項
⚠️ 重要提醒
- 正式／舊版串接類型不可互換；日期版升級方式見API 版本。
- access token 等同密碼，請透過安全管道交付，不要留在公開對話或工單附件。
- IP 限制填錯會直接擋掉對方的正常呼叫，且對方看到的是被拒絕、不是格式錯誤。上線前請先請對方測試一次。
三、相關功能
| 功能 | 說明 | 連結 |
|---|---|---|
| 串接管理 | 查看所有串接與每日用量 | 前往 |
| 串接詳情 | 查看已建立的憑證與設定 | 前往 |
| 編輯串接 | 調整權限範圍、IP 限制與 Webhook | 前往 |