Skip to content

串接詳情 ​


目錄 ​


一、功能介紹 ​

查看一組串接的完整設定:它被授權做什麼、憑證是什麼、最後一次被呼叫是什麼時候,以及 Webhook 推送的狀況。排查「對方說串不進來」或「要收回權限」時,都從這一頁開始。

快速跳轉:基本資料 | 憑證 | 權限範圍 | Webhook

1.1 基本資料 ​

欄位說明
名稱這組串接的名稱
串接類型建立時的相容識別;正式日期版升級不須重建憑證
啟用狀態目前是否可用。停用中的憑證,對方的呼叫會被擋在認證階段
描述建立時填的用途說明
建立時間建立時間
最後使用時間最後一次成功呼叫的時間。長期空白代表對方根本沒接上,或早就不用了

1.2 憑證 ​

Client ID 可隨時複製;access token 只顯示末碼,舊密鑰若沒有末碼則顯示「完整密鑰不再顯示」。完整值只在建立或輪替當次顯示。此頁同時列出到期、上次輪替與目前密鑰的使用時間;使用時間最多延遲五分鐘更新,空白不能作為已完成切換的證明。

既有密鑰維持「永不過期」,不會因這次改版而失效。一般編輯不會改變效期。新建或輪替時,需選擇六個月、一年或永不過期;到期後必須換發新密鑰才能繼續使用。密鑰到期本身不會停用 Webhook 簽章或通知。

▸ 一般輪替

  1. 需要串接管理權限。按「輪替密鑰」,選擇新密鑰的效期並確認。
  2. 新密鑰立即生效,保存視窗顯示完整值與到期日,可重複複製;勾選已保存後才能關閉。Client ID、權限範圍與 Webhook 設定不變。
  3. 舊密鑰最多仍可使用 24 小時,或至原到期時間(以較早者為準)。請在畫面列出的切換期限前,讓對方系統改用新密鑰。
  4. 確認切換後,可按「撤銷舊密鑰」讓舊密鑰提早失效;不可復原。切換期間無法再次輪替,須先撤銷舊密鑰或等期限結束。

▸ 密鑰疑似外流

按「立即撤銷所有密鑰」並確認,會立即撤銷新舊密鑰,同時停用串接與 Webhook;此操作不可復原,重新啟用也不會讓舊密鑰恢復。需要繼續串接時,先輪替產生並交付新密鑰,再啟用串接,Webhook 需另行啟用。

1.3 權限範圍 ​

這組憑證被允許做的事。要增減請到編輯串接。

舊版(legacy)API 版本沒有權限範圍的概念,這個區塊不會出現——該憑證可存取舊版開放的全部功能。

1.4 Webhook ​

如果這組串接設定了事件推送,這裡顯示:

項目說明
URL事件要送到對方的哪個端點
Webhook 版本推送內容的格式版本,與這組串接的 API 版本各自獨立
訂閱事件目前會推送哪些事件
簽章驗證平時顯示遮罩值。按「重新產生密鑰」後,完整新密鑰會在保存視窗顯示並可複製;關閉後無法再次查看
發送次數這個 Webhook 至今累積的推送筆數

啟用狀態的開關在這個區塊的標題列右側(只有勾/叉圖示,沒有文字),可以直接在這一頁切換,不需要進編輯頁。關掉後停止推送、設定本身保留,隨時可以開回來;這期間發生的事件不會在重新開啟時補送。

⚠️ Webhook 簽章密鑰換發後舊值立即失效,沒有 24 小時切換期。請先與對方約定切換時間,並在保存視窗交付新值。

要調整網址、版本或訂閱事件,請到編輯串接。

測試:按下後會真的送出一次推送到上面那個網址——對方系統會實際收到一筆測試事件,不是模擬。送出後跳出的視窗顯示這次的狀態、回應碼與耗時,可用來確認對方端點通不通、簽章設定對不對。從回應碼可初步判斷是對方伺服器回了錯誤(5xx)還是網址或簽章設定錯誤(4xx);連不上或逾時則沒有回應碼,會顯示為 N/A。

要注意的副作用:這次測試會被記成一筆正式的推送紀錄,發送次數會加一,在「Webhook 紀錄」裡也查得到(標記為手動觸發,與系統自動推送分開)。測試失敗不會自動重試。

停用整組串接時,Webhook 會一併停用;重新啟用串接時 Webhook 不會自動恢復,需要用上面那個開關手動開回來。

1.5 刪除 ​

刪除這組憑證。不可復原,對方保留的 token 立即失效,其 Webhook 也會先被停用再解除關聯。只是暫時中止合作的話,請改用停用。


二、常見問題 ​

快速跳轉:FAQ | 注意事項

2.1 FAQ ​

▪ 自動處理閘門已結束,串接還能補加訂單品項嗎? ​

可以。通用訂單品項追加不受 App 閘門期限限制,但訂單必須仍可編輯、尚未進入揀貨,串接也須有訂單寫入權限。既有品項會保留。若送出後連線中斷,請先查核操作結果;查不到結果不代表沒有寫入,不應直接重送。

▪ 對方說一直收到 401/認證失敗,我該看哪裡? ​

先確認串接是否啟用,以及密鑰是否過期、已撤銷或已超過舊密鑰切換期限。請對方核對密鑰末碼,確認沒有使用已失效的值;再檢查 IP 限制與對方來源是否相符。

▪ 對方說收到 403/權限不足? ​

那不是憑證問題,是權限範圍沒給到他要做的事。到編輯頁把對應的項目勾上即可,不需要重新產生 token。

▪ 對方說收到 429? ​

代表撞到用量限制。可能是短時間呼叫太密集,也可能是當日總額度用完了。到串接管理看每日用量卡確認是哪一種。

▪ 最後使用時間一直是空的,代表串接失敗嗎? ​

代表從來沒有一次成功的呼叫。可能是對方還沒開始接,也可能是憑證、IP 或版本設定有落差。先請對方提供他們收到的錯誤訊息,再對照上面幾題判斷。

▪ Webhook 一直推送失敗,會影響訂單本身嗎? ​

不會。Webhook 是額外的通知管道,推送失敗不影響訂單或庫存資料本身,對方仍可以主動呼叫 API 查詢。但請盡快處理,否則對方的系統會一直拿到過期的狀態。

▪ 商品刪除後,對方還能查到原本的庫存嗎? ​

正式版本(v1、2026-09、2026-10、2026-11)的庫存列表預設排除已刪除商品。歷史對帳時,請對方工程師明確選擇包含已刪除商品;既有庫存詳情仍可查閱,刪除不會清空實體庫存。未刪除商品的耗盡與鎖定批次則仍可查到,可用篩選只查看正常批次。

若對方需要同步商品刪除,須同時具備商品讀取權限,並從包含已刪除商品的商品清單取得刪除時間;只接收庫存異動通知不會得知商品刪除。同一 SKU 可被新商品重用,請對方以商品識別碼區分,避免把新舊商品的庫存加在一起。參數與欄位請依對應版本的串接文件設定。

▪ 對方能知道每筆訂單實際使用的庫存批號嗎? ​

使用 2026-11 版本並開啟庫存讀取權限後,對方可查出庫異動的批號、效期與數量,並以公開的訂單品項識別碼對回訂單明細;讀取訂單內容仍需要訂單讀取權限。來源明細已刪除或關聯無法確認時,可能無法對回原單,不能只靠這份資料作永久成本帳本。

▪ 對方可以查詢或修改加工費嗎? ​

使用 2026-11 版本、具備加工單讀取權限且方案支援加工單時,可在單張加工單詳情查到倉方已登錄的費用及各列入帳狀態。費用仍由倉方維護,串接不能修改;已結單也不代表已付款。尚未登錄費用不代表免收費,完工後仍可能補登。幣別及含稅口徑依您與倉方的約定;需要最新費用時請對方重新查詢單張,不能只同步最近更新的加工單列表。

2.2 注意事項 ​

⚠️ 重要提醒 ​

  • 切換期限後舊密鑰無法使用,請依一般輪替完成切換。
  • 刪除不可復原,且會一併解除 Webhook 設定。暫時中止請用停用。
  • 完整密鑰關閉後無法再次取得,遺失時須輪替產生新密鑰。

功能說明連結
串接管理查看所有串接與每日用量前往
編輯串接調整權限範圍、IP 限制與 Webhook前往
新增串接建立另一組憑證前往

最後更新 2026-11-16 19:57