生產準備

Agent SDK 祕密與 HMAC 手語

保護代理 API 憑證，並了解 SDK 如何產生帶有時間戳記、抗重播的 HMAC——SHA256 請求簽名。

以 Markdown 格式查看

Agent SDK 請求需由 Partner API secret 驗證。把這個秘密放在可信的後端服務裡，讓 SDK 盡可能產生簽名欄位。

兩種簽署協議

Agent SDK 簽名使用排序請求欄位、基於秒數的時間戳和一個 nonce。直接開發者 API 請求使用[請求簽署]（/developer-api/request-signing）中所述的獨立流程。請勿重複使用一種有效載荷格式。

簽署規則

對於 Agent SDK 請求：

  1. 排除 sign 場。
  2. 省略空值欄位。
  3. 將剩餘欄位名稱依 ASCII 順序排序。
  4. 像 k=v&k2=v2一樣加入田野。
  5. 計算 HMAC-SHA256 十六進位簽名，與 apiSecret。

SDK 應該從它傳送的同一資料建立這個值。在簽章產生後更改已簽署欄位會導致驗證失敗。

SDK-管理欄位

場地資料來源描述
agentCodeSDK 設定夥伴特工代碼。
時間戳記目前伺服器時間Unix 的時間戳記在幾秒內。
不行安全隨機值重播保護隨機字串。
標誌HMAC-SHA256請簽名。
貨幣預設貨幣用於轉帳/帳戶時 API 省略貨幣。

秘密儲存

  • 從後端秘密管理器或受保護的執行時設定載入 apiSecret 。
  • 絕不要將秘密資料放在前端套件、行動應用程式、桌面客戶端、截圖或支援工單中。
  • 將開發、舞台設計與製作的資格資料分開。
  • 限制對需要該服務的服務與業者的存取。
  • 刪除請求簽名、授權值及日誌中的秘密。
  • 懷疑有暴露時撤銷並更換憑證。

時鐘與重播保護

SDK 包含timestamp和nonce以降低重播風險。保持後端時鐘同步，且不要重複使用手動製作的 nonce。若簽章驗證失敗，請先確認已設定的秘密、伺服器時間、序列化欄位及環境，然後再嘗試。

整合檢查清單

檢查預期結果
秘密地點僅後端的秘密儲存。
環境基礎 URL 和資格屬於同一個環境。
現場處理SDK 產生 timestamp、 nonce和 sign。
伐木商業識別碼在被遮蔽時仍可見。
旋轉憑證持有人及更換流程都有文件記錄。
Agent SDK 概述

檢視建議的後端整合流程。

Webhook 與冪等性

驗證回撥簽名並防止重複處理。

SDK 故障排除

診斷簽名、時鐘、環境及請求問題。

相關頁面