編輯串接
目錄
一、功能介紹
調整既有串接的設定。日常最常用到的是增減權限範圍（對方要新增功能）、調整 IP 限制（對方換了伺服器）與設定 Webhook。API 版本是唯一無法在這裡修改的欄位。
1.1 可修改的項目
| 欄位 | 可否修改 | 修改後的影響 |
|---|---|---|
| 名稱 | 可 | 只影響後台顯示，對方無感 |
| 描述 | 可 | 同上 |
| 串接類型 | 不可 | 正式／舊版分類固定；正式日期版升級不須改此欄位 |
| 權限範圍 | 可 | 立即生效，對方下一次呼叫就依新的範圍判定 |
| IP 限制 | 可 | 立即生效，填錯會馬上擋掉對方的正常呼叫 |
| Webhook | 可 | 立即生效 |
修改設定不會變更 client ID 或 access token，對方不需要換憑證。
舊版串接能否呼叫 API，也取決於環境是否開放舊版相容功能；修改這裡的設定不會恢復已關閉的舊版 API。詳見API 版本。
1.2 權限範圍
勾選或取消這組憑證被允許做的事，儲存後立即生效。項目清單與各類別的意義見新增串接。
- 加權限：對方要接新功能時在這裡加上，不需要重新產生 token。
- 收權限：取消勾選後，對方下一次呼叫該功能就會收到權限不足的錯誤。收權限前建議先通知對方，否則他們會突然看到一批失敗。
正式版本至少要保留一項權限範圍；舊版（legacy）沒有這個區塊。
打開舊串接時看到「偵測到已停用的權限名稱」
部分權限項目改過名稱。改名前建立的串接打開時，畫面會列出舊名稱與它對應的新名稱，並先幫你勾好等效的項目——在你按儲存之前，對方的存取範圍不變；按下儲存後就換成新名稱，實際能做的事一樣。
一個例外要留意：地址簿以前包含在「訂單」裡面，現在是獨立的一類。改版後，只勾了「訂單」的既有串接不再能讀寫你的常用收件地址；對方如果本來就有在用地址簿功能，請在這裡補勾「地址簿」。
1.3 IP 限制
一行一筆，支援單一 IP 與 CIDR 網段，留空代表不限制來源。格式錯誤時儲存會被擋下並指出是哪一筆。
對方換伺服器或增加機器時要記得同步更新。這是最容易造成「昨天還好好的，今天突然全部失敗」的設定——對方看到的是被拒絕，不會知道是 IP 名單的問題，所以調整後請主動通知。
1.4 Webhook
設定事件發生時要推送到哪個網址。
| 項目 | 說明 |
|---|---|
| URL | 對方提供的接收端點，必須是有效的網址 |
| Webhook 版本 | 推送內容的格式版本，與這組串接的 API 版本各自獨立 |
| 訂閱事件 | 勾選要推送哪些事件 |
| 簽章驗證 | 對方用來驗證推送確實來自我們。這一頁也有重新產生按鈕，但同樣不會顯示新金鑰、只看得到遮罩值——要換金鑰請到「Webhook 設定」頁面，那裡才會在產生當下顯示完整金鑰供複製 |
推送事件等同把資料交給對方，所以勾選的事件必須在上方「權限範圍」有對應的讀取權限，否則無法儲存：
| 事件 | 需要的讀取權限 |
|---|---|
| 訂單出貨、訂單取消、出貨單出貨、出貨單狀態變更 | 訂單 讀取 |
| 入庫完成 | 入庫單 讀取 |
| 庫存異動 | 庫存 讀取 |
| 退貨驗收完成、退貨單結案 | 退貨單 讀取 |
之後若拿掉某項讀取權限，已勾選的對應事件會停止推送（其他事件照常），Webhook 本身不會被停用。要恢復，把讀取權限加回來即可；停止期間的事件不會補送。
啟用狀態的開關不在這一頁，在串接詳情。
停用整組串接會連帶停用 Webhook；之後重新啟用串接時，Webhook 不會自動恢復，需要到串接詳情用那裡的開關打開。這是刻意的設計，避免中止期間累積的事件在恢復瞬間一次送出去。
二、常見問題
2.1 FAQ
▪ 改了權限範圍，對方需要重新設定嗎？
不需要。client ID 與 access token 都不變，對方下一次呼叫就會套用新的權限範圍。
▪ 我想換 API 版本，真的沒辦法嗎？
建立時選擇的是正式或舊版串接類型，這項分類無法變更。正式串接可用同一組憑證呼叫 v1 與已發布日期版本（包含 2026-10）；請對方工程師測試後切換呼叫的版本，不必重建憑證。跨正式／舊版類型才需要另建串接。
▪ 我把權限範圍全部取消了，會怎樣？
正式版本至少要保留一項，全部取消會無法儲存。真的要完全停止對方的存取，請用停用或刪除整組串接，而不是清空權限。
▪ Webhook 的簽章金鑰重新產生後，對方會怎樣？
對方會開始驗簽失敗，通常他們的系統會把推送視為不可信而丟棄。請先與對方約好時間，並且到「Webhook 設定」頁面重新產生——只有那一頁在產生當下會顯示完整金鑰可供複製，串接頁面上看到的是遮罩值。
▪ 我停用串接又重新啟用，為什麼對方收不到 Webhook？
這是預期行為。停用時 Webhook 一併被關閉，重新啟用串接不會自動把 Webhook 開回來，需要到串接詳情手動啟用。
▪ 改完之後怎麼確認對方真的接上了？
看串接詳情的最後使用時間有沒有更新。要確認 Webhook 通不通，可在該頁按「測試」實際送一次（會計入發送次數，見串接詳情）。
2.2 注意事項
⚠️ 重要提醒
- IP 限制與權限範圍的調整立即生效，對方會在下一次呼叫時受影響。收緊設定前請先通知對方。
- 重新產生 Webhook 簽章金鑰後舊金鑰立即失效，沒有並存期間（欄位在 UI 上叫「簽章驗證」）。
- 停用後重新啟用，Webhook 需要到串接詳情手動開啟，不會自動恢復。
- 正式／舊版串接類型不可互換；日期版升級方式見API 版本。
三、相關功能
| 功能 | 說明 | 連結 |
|---|---|---|
| 串接管理 | 查看所有串接與每日用量 | 前往 |
| 串接詳情 | 查看憑證與最近推送結果 | 前往 |
| 新增串接 | 建立另一組憑證 | 前往 |