Vanta Connect 串接
目錄
一、使用情境
快速連結：自建系統要接上單一倉庫 ｜ 跨倉系統要讀取資料 ｜ 串接廠商換人或憑證外流 ｜ 外部系統要即時收到出貨與庫存變動
情境 1：自行開發的揀貨系統要接上其中一個倉庫
狀況：A 倉導入了外包廠商開發的揀貨作業系統，需要一組帳號讓它向倉庫系統取揀貨單、回報揀貨結果。您不希望這套系統看得到其他倉庫的資料。
用這個功能：替這套系統建立一組串接，綁定 A 倉、只勾選揀貨單相關的權限範圍，再把 Client ID 與 Access Token 交給廠商；規格請對方看這組憑證的 API 文件。
結果：對方只看得到 A 倉的揀貨單、只能做您勾選的事，日後要收回時也只動這一組，不影響其他串接。
情境 2：跨倉的中介系統要讀取多個倉庫的訂單與庫存
狀況：您的組織有一套自建的中介系統，要同時讀各倉的訂單與貨主庫存，彙整給內部報表或轉單系統使用。
用這個功能：建立串接時綁定倉庫留空，代表可存取組織內全部倉庫；權限範圍只勾需要讀取的項目，並把中介系統主機的固定 IP 填進 IP 白名單。
結果：中介系統用一組憑證就能讀取全部倉庫的資料，且只接受來自您指定主機的連線。
情境 3：串接廠商換人或懷疑憑證外流
狀況：原本合作的串接廠商換了，或您發現 Access Token 被貼在不該出現的地方。這組憑證能讀寫倉庫資料，必須馬上處理。
用這個功能：還要繼續使用的系統，進「檢視憑證」重發 Token；暫停合作就把串接停用；確定不再使用就刪除。三者的差別見常見問題。
結果：舊的憑證立即失效，持有它的人無法再存取倉庫資料。
情境 4：外部系統要即時知道哪些訂單出貨、庫存變了
狀況：組織的 ERP 要在訂單出貨或取消、庫存數量變動時馬上更新自己的資料。一直定時來查詢既慢又浪費，您希望由倉庫系統主動通知它。
用這個功能：在 ERP 使用的那組串接設定 Webhook 訂閱：填 ERP 接收通知的網址、勾選要收的事件，再把簽章金鑰交給 ERP 端驗證請求來源。
結果：事件發生後，倉庫系統主動推送通知到 ERP，ERP 不必再輪詢；串接若有綁倉庫，只會收到該倉庫的事件。
二、功能介紹
Vanta Connect 串接是外部系統（ERP、WMS 中介系統、自行開發的程式）以組織層級的 Vanta Connect API 連進倉庫系統的入口。每一組串接是一份獨立的憑證：建立時綁定一個 API 版本，您再決定它能存取哪個倉庫、能做哪些事、只接受哪些來源 IP，交給對方設定後，對方就能依該版本的 API 文件取揀貨單、建訂單、查庫存。一套系統建一組，出問題時只需處理那一組。
快速跳轉：串接清單 ｜ 新增與管理 ｜ 串接設定欄位 ｜ 檢視憑證與重發 Token ｜ Webhook 訂閱
2.1 串接清單
從 「開發者工具」 → 「Vanta Connect 串接」 進入。清單只列出在這個頁面手動建立的串接。
| 欄位 | 說明 |
|---|---|
| API 版本 | 這組憑證能呼叫的 API。藍色「Vanta Connect API 2026-10」等日期版標籤是在這頁新建的憑證；橘色「舊版 WCS API」是舊版 WCS API 時期就建立的憑證，只能呼叫舊的 API，見常見問題 |
| 綁定倉庫 | 這組憑證限定的倉庫；顯示「全部倉庫」標籤代表沒有綁倉，可存取組織內所有倉庫 |
| 權限範圍 | 這組憑證被允許做的事，只列前 3 項，其餘以「+數字」表示還有幾項；滑鼠移到「+數字」上會列出其餘項目，只有檢視權限的人員也看得到完整範圍。對照見串接設定欄位 |
| 啟用狀態 | 停用中的憑證，所有呼叫都會被拒絕 |
| Webhook | 這組串接的 Webhook 訂閱狀態，以實際會不會推送為準：「啟用」、「停用」或「未訂閱」。串接本身停用時一律不推送，即使訂閱開著也顯示「停用」並註明「串接已停用，訂閱不會投遞」；串接缺少某個訂閱事件需要的權限範圍時，顯示「部分事件不投遞」並列出缺少的項目。投遞連續失敗時，下方會多一行失敗次數 |
| 最後使用時間 | 對方最後一次成功連入的時間；顯示「-」代表從未成功連入過。在連入檢查階段就被拒絕的呼叫不會更新，例如串接已停用、來源 IP 不在白名單、路徑與憑證的 API 版本不符。同一組憑證 5 分鐘內只更新一次，所以可能比實際最後一次呼叫早最多 5 分鐘 |
2.2 新增與管理
| 操作 | 前置條件與副作用 |
|---|---|
| 建立 | 選擇 API 版本並填寫串接設定欄位後確認；要接收事件通知時，同一個視窗下方可一併設定 Webhook 訂閱。建立完成會跳出「串接建立成功」視窗，顯示 API 版本、該版本的 API 文件連結、Client ID 與 Access Token，可直接複製交給對方；之後仍可在「檢視憑證」查看。新建立的串接預設為啟用 |
| 檢視憑證 | 點操作欄的鑰匙圖示，查看 Client ID 與 Access Token，並可重發 Token，見檢視憑證與重發 Token |
| 編輯 | 點鉛筆圖示，可修改 API 版本以外的所有設定欄位與啟用狀態。關閉啟用狀態後，對方下一次呼叫就會被拒絕；重新開啟後用原本的 Token 即可恢復，不需要重新設定對方系統 |
| 刪除 | 點垃圾桶圖示並確認。刪除後對方立即無法存取，無法復原；要再串接只能建立新的一組，Client ID 與 Token 都會不同。設有 Webhook 訂閱時，訂閱會一併停止推送，過去的投遞紀錄仍可在 「開發者工具」 → 「Webhook 紀錄」 查到 |
| API 文件 | 在新分頁開啟 Vanta Connect API 文件，內容是對方工程師串接時要看的規格。側欄 「開發者工具」 → 「API 文件」 也是同一份文件。個別憑證對應版本的文件，在憑證視窗開啟 |
建立、編輯、刪除、重發 Token，以及 Webhook 訂閱的重新啟用與測試投遞，都需要 Vanta Connect 串接的管理權限；只有檢視權限的人員，這些按鈕會鎖定無法操作，但可以查看憑證、訂閱狀態與簽章金鑰。
2.3 串接設定欄位
標示 * 的欄位為必填項目
| 欄位名稱 | 如何填寫 | 注意事項 |
|---|---|---|
| *名稱 | 用系統的用途命名，例如「ERP 訂單同步」 | 一套系統一組時，看名稱就知道要處理哪一組 |
| 說明 | 補充串接廠商、聯絡人或上線日期 | 選填 |
| *API 版本 | 選擇對方要串接的 Vanta Connect API 版本，預設為最新版；選項下方會說明這個版本能呼叫的路徑 | 只在新增時能選，建立後無法更改；對方要改用其他版本時，請另建一組串接。編輯時只顯示版本標籤。不能新建舊版 WCS API 的憑證 |
| 綁定倉庫 | 選擇這組憑證能存取的倉庫；留空代表全部倉庫 | 綁定後，揀貨單、訂單與庫存只查得到該倉庫的，倉庫清單也只回該倉庫；建立訂單、入庫單、退貨單只能建在該倉庫，指定其他倉庫會被拒絕。貨主、商品、電商帳號、銷售通路、庫存類型不受綁倉限制。只能選自己組織的倉庫 |
| *權限範圍 | 勾選對方需要的項目，例如揀貨系統只需要「查詢揀貨單」與「確認揀貨結果」 | 至少勾一項。沒勾的項目，對方呼叫時會被拒絕 |
| IP 白名單 | 每行一個 IP 位址或網段，例如「192.168.1.100」或「10.0.0.0/24」；也可以用逗號分隔 | 選填。留空代表任何來源都可連入；填了之後，只有名單內的來源能連入。格式錯誤時欄位下方會列出無效的項目，修正後才能儲存 |
| 啟用狀態 | 開啟或關閉這組串接 | 只在編輯時出現 |
2.4 檢視憑證與重發 Token
點操作欄的鑰匙圖示會開啟憑證視窗：
- API 版本：這組憑證的版本標籤與說明；旁邊的「API 文件」依版本開啟對應的文件：日期版開該版本的 Vanta Connect API 文件，「舊版 WCS API」開舊版 WCS API 文件。
- Client ID：這組串接的識別碼，可直接複製。
- Access Token：預設以遮罩顯示，點眼睛圖示顯示完整內容，點複製圖示複製。
- 重發 Token：確認後產生新的 Token，舊 Token 立即失效，沒有並存的緩衝時間；Client ID 不變。重發後新 Token 會直接顯示在視窗中，請把它更新到對方系統上。
視窗下方的「Webhook 訂閱」區塊顯示這組串接的訂閱狀態與操作，見 Webhook 訂閱。
2.5 Webhook 訂閱
每組串接可以設定一條 Webhook 訂閱：事件發生時，倉庫系統以 HTTP POST 把事件內容推送到您指定的網址，對方不必定時來查詢。在新增或編輯視窗下方的「Webhook 訂閱」區塊設定：
| 欄位名稱 | 如何填寫 | 注意事項 |
|---|---|---|
| URL | 對方接收通知的網址，例如 https://erp.example.com/hooks | 留空且沒勾事件代表不訂閱。已經有訂閱時不能清空，要暫停請關閉「啟用訂閱」 |
| Webhook 版本 | 選擇對方程式支援的事件內容格式，預設為最新版 | 修改後只影響之後的新事件。這是通知內容的格式版本，與憑證的「API 版本」無關，可以各自設定 |
| 訂閱事件 | 勾選要接收的事件，至少一項 | 只能訂閱下表三個事件，且這組串接要勾有對應的權限範圍，缺少時儲存會被拒絕並列出缺少的項目。已訂閱後才取消串接的權限範圍仍可儲存，但會跳出提示列出缺少的項目，需要它們的事件之後不會推送；清單的訂閱欄也會列出缺少的項目 |
| 啟用訂閱 | 開啟或關閉這條訂閱 | 只在已有訂閱的串接編輯時出現；關閉後不再推送，憑證本身不受影響 |
| 事件 | 何時推送 | 串接需具備的權限範圍 |
|---|---|---|
庫存變動（inventory.updated） | 任一貨主的庫存數量變動；同一商品在同一倉庫短時間內的多次變動會合併成一則，內容是推送當下的最新數量 | 查詢貨主庫存數量 |
訂單出貨（order.shipped） | 任一貨主的訂單出貨 | 查詢訂單及貨主可用物流類型 |
訂單取消（order.cancelled） | 任一貨主的訂單取消 | 查詢訂單及貨主可用物流類型 |
推送範圍跟著串接走：有綁定倉庫的串接只會收到該倉庫的事件，沒綁則收組織內所有倉庫的事件；串接停用期間不推送。改綁到其他倉庫後，改綁前已排入、還沒送出（含等待重試）的原倉庫事件不會再送出，這些投遞在 Webhook 紀錄中狀態為失敗，回應內容註明未授權（not authorized）。每則通知都標明事件屬於哪個貨主。
驗證請求來源：點鑰匙圖示開啟憑證視窗，「Webhook 訂閱」區塊的「簽章密鑰」預設遮罩，可顯示與複製。每個請求都帶 X-GW-Timestamp 與 X-GW-Signature 標頭，簽章是以此金鑰對「X-GW-Timestamp 的值 + . + 原始內容」計算的 HMAC-SHA256（標頭值為 sha256= 加上十六進位字串），對方重算比對相符，就能確認請求來自倉庫系統。
狀態與維護（都在憑證視窗的同一區塊）：
| 項目 | 說明 |
|---|---|
| 連續失敗次數 | 一則事件經過自動重試仍送不到，才算一次失敗；成功送達就歸零。連續 10 次失敗，訂閱會自動停用，並通知倉庫端人員 |
| 重新啟用訂閱 | 訂閱停用時出現。請先確認對方接收端已修好再按；重新啟用後失敗次數歸零，之後的新事件恢復推送，停用期間的事件不會補送。串接本身停用時，按下會提示先啟用串接；串接缺少訂閱事件需要的權限範圍時，按下會被拒絕並列出缺少的項目，請先補勾權限範圍或取消那個事件。用編輯視窗打開「啟用訂閱」也是同樣的檢查 |
| 測試投遞 | 訂閱啟用時出現。立即送一則測試通知（不重試），畫面顯示對方回應的狀態碼與耗時。網址指向內部網路或格式不合法時，不會送出，畫面直接顯示網址被擋；與「連線失敗或逾時」（對方沒有回應）分開顯示 |
| 查看投遞紀錄 | 開啟只顯示這條訂閱的「Webhook 紀錄」，可看每一則推送的內容、對方回應，並重送失敗的推送。需要紀錄檢視權限才看得到這個按鈕，重送需要紀錄管理權限；庫存、訂單事件的推送只有被指派該事件貨主的倉庫人員看得到，測試推送則組織內能查看 Webhook 紀錄的人都看得到 |
三、常見問題
3.1 FAQ
▪ 為什麼 App 安裝後的憑證不在這裡？
組織安裝的 App（例如 POS 等第三方應用）連入倉庫系統時用的憑證，是安裝 App 時由系統代為建立的，由該 App 自己管理，不會出現在這份清單，也不能在這裡編輯或重發。這類憑證與 App 的 Webhook 訂閱改在 「應用程式」 → 「管理應用程式」 展開該 App 查看，被自動停用的訂閱也在那裡重新啟用，見App 的憑證與 Webhook。要停止某個 App 存取倉庫資料，請到 「應用程式」 → 「管理應用程式」 將它「解除安裝」，解除安裝後該 App 就無法再存取倉庫資料。
▪ 這頁以前叫「WCS 串接」，原本建立的串接還能用嗎？
能。原本建立的串接、Client ID 與 Access Token 都照常可用，在清單上標示為「舊版 WCS API」，呼叫的 API 路徑（/api/wcs/v1）沒變，對方系統不需要重新設定。人員原本的檢視、管理權限也已一併沿用。
▪ 「舊版 WCS API」的串接要怎麼改用 Vanta Connect API？
憑證的 API 版本建立後無法更改，請另建一組串接（新建一律是 Vanta Connect API 日期版），把新的 Client ID 與 Access Token 交給對方，請對方依新憑證視窗裡的 API 文件改打 /api/connect/…；對方切換完成後，再停用或刪除舊的那組。舊版 WCS API 的憑證已不能新建，但既有的可以繼續檢視、編輯其他欄位、停用、重發 Token 與刪除。
▪ 對方呼叫時收到 api_version_mismatch？
代表對方打的 API 路徑與這組憑證的版本不符：日期版的憑證只能呼叫 /api/connect/ 加上該版本（例如 /api/connect/2026-10），「舊版 WCS API」的憑證只能呼叫 /api/wcs/v1。請對方對照憑證視窗的版本標籤與文件連結修正路徑。
▪ 停用、刪除、重發 Token 有什麼差別？
- 停用：憑證保留，對方暫時連不進來，重新啟用後用原本的 Token 即可恢復。適合暫停合作或排查問題。
- 刪除：憑證永久消失，無法復原。適合確定不再使用的系統。
- 重發 Token：同一組串接換一個新 Token，舊 Token 立即失效。適合系統還要繼續用、但 Token 可能外流的情況，記得先跟對方約好更新時間。
▪ 對方明明設定好了，卻一直連不進來？
依序確認：這組串接是否為啟用狀態；IP 白名單有填時，對方主機實際連出的 IP 是否在名單內（經過防火牆或代理時，對外 IP 常與主機本身的 IP 不同）；對方使用的 Token 是否是重發之後的新 Token；呼叫的路徑是否與憑證的 API 版本相符。另外，組織方案若不再包含 Vanta Connect 串接功能，所有串接都會立即無法連入。
▪ 綁定倉庫和不綁有什麼差別？該怎麼選？
綁定後，揀貨單、訂單與庫存只看得到該倉庫的，建單也只能建在該倉庫；不綁則可存取組織內所有倉庫。但綁倉管不到貨主、商品、電商帳號、銷售通路、庫存類型這些組織層級的資料，勾了對應的權限範圍就看得到整個組織的資料，這部分要靠權限範圍控管。只服務單一倉庫的系統就綁那一倉，並只勾它用得到的權限範圍；只有需要跨倉彙整資料的系統才不綁。
▪ 這裡的 IP 白名單，跟「組織管理」的 IP 白名單有什麼不同？
這裡的 IP 白名單只限制這一組串接可以從哪些來源連入，每組串接各自設定。「組織管理」的 IP 白名單 限制的是倉庫人員從哪些網路登入倉庫作業系統，不影響 Vanta Connect 串接。
▪ Webhook 設好了卻收不到某些事件？
依序確認：訂閱與串接都是啟用狀態；串接有綁定倉庫時，事件是否發生在該倉庫；串接是否仍有該事件需要的權限範圍（設定後才拿掉權限，該事件會被略過、不會推送，其他事件不受影響；清單的訂閱欄會顯示「部分事件不投遞」並列出缺少的項目），對照見 Webhook 訂閱。可以先按「測試投遞」確認對方網址收得到。
▪ 為什麼只能訂閱這三個事件？入庫完成、退貨等事件呢？
組織層級的訂閱只會推送有組織層級推送路徑的事件：庫存變動、訂單出貨、訂單取消。其他事件目前只推送給貨主自己設定的 API 憑證訂閱，訂了也收不到，所以不開放勾選。
▪ 這裡的簽章金鑰跟 App 的簽章密鑰一樣嗎？
不一樣。這裡每條訂閱有自己的簽章金鑰，在憑證視窗查看。組織安裝的 App 由系統代建的訂閱，改用該 App 的簽章密鑰簽章，由 App 開發者持有，不在這頁顯示。
▪ 好幾套系統可以共用同一組憑證嗎？
可以，但不建議。一套系統各建一組，才能分別設定綁定倉庫、權限範圍與 IP 白名單；要收回某一套的存取權時，也只需停用那一組，其他系統不受影響。
▪ 我在側欄看不到「Vanta Connect 串接」？
這個功能需要組織方案包含 Vanta Connect 串接（Pro 或 Enterprise 方案），而且您的帳號要有 Vanta Connect 串接的檢視權限。方案或權限任一不符，選單都不會出現；權限請聯繫管理員到人員管理確認。
3.2 注意事項
⚠️ 重要提醒
- 刪除串接無法復原，對方會立即失去存取權。只是暫停合作，請改用停用。
- 重發 Token 後舊 Token 立即失效，對方會在下一次呼叫時開始失敗，務必先約好更新時間。
- API 版本建立後無法更改，要換版本只能另建一組串接。
- Webhook 訂閱停用期間的事件不會補送，重新啟用後只推送之後的新事件；對方需要完整資料時，請改用 API 查詢補齊。
- 組織方案不再包含 Vanta Connect 串接時，所有串接立即無法連入，恢復方案後才會恢復。
💡 提示：「最後使用時間」長期顯示「-」或停在很久以前的串接，多半是已經不再使用的系統留下的，確認後停用或刪除，可以少一組可能外流的憑證。
四、相關功能
| 功能 | 說明 | 連結 |
|---|---|---|
| App | 管理組織安裝的 App，查看 App 代建的憑證與 Webhook 訂閱並重新啟用 | 前往 |
| IP 白名單 | 限制倉庫人員可以從哪些網路登入系統 | 前往 |
| 人員管理 | 調整誰可以查看與管理 Vanta Connect 串接 | 前往 |