# 資料簽章規範

# 簽章說明

在 API 請求透過網際網路傳輸的過程中，為防止請求被篡改或偽造，所有**私有介面（如資金相關、交易類介面）**必須進行簽章驗證。

透過簽章機制可確保參數在傳輸過程中未被篡改，並有效防止重放攻擊。

請求組成結構

一個合法請求包含以下關鍵欄位（其中除 secret_key 外，全部透過請求 Header 傳遞）：

參數名 說明
access_key API 存取金鑰，標識使用者身份
secret_key 簽章所使用的金鑰，僅在建立 API Key 時展示一次，請妥善保管，不得傳輸
timestamp 發起請求時的時間戳（毫秒級，13 位，如：1632811287325），用於防止重放攻擊
nonce 隨機 UUID（如：053a1b81-48a0-4bb1-96b2-60f6e509d911），確保請求唯一性
sign 透過簽章演算法產生的簽章字串，用於驗證參數完整性

除 secret_key 外，以上欄位需全部作為 Header 參數傳遞。

# 簽章步驟

# 步驟 1：定義參數 Map

定義一個字典（Map）物件，將介面請求中使用的業務參數按 key-value 形式放入其中。

# 步驟 2：加入公共參數

將以下三個簽章公共參數加入該 Map 中：

  • access_key：存取金鑰
  • timestamp：毫秒級時間戳（13 位）
  • nonce：隨機 UUID 字串

# 步驟 3：參數排序 & 拼接

對 Map 中的所有參數按 ASCII 字典序進行升冪排序。

然後將排序後的參數拼接為如下格式的字串：

key1=value1&key2=value2&key3=value3

# 步驟 4：產生簽章值 sign

使用 secret_key 對上一步拼接的字串執行以下加密操作：

  • 加密方式：HMAC-SHA1
  • 編碼方式：Base64

最終輸出的值即為簽章參數 sign。

secret_key 是您在商戶平台建立 API Key 時產生的金鑰，僅展示一次，請務必妥善儲存。

# 步驟 5：建構請求並發送

將以下欄位加入到 HTTP 請求的 Header 中：

access_key: your_access_key
timestamp : 毫秒時間戳
nonce     : UUID 隨機字串
sign      : 第 4 步產生的簽章

然後將請求發送至對應介面位址。

商戶簽章流程圖例

img

# 簽章除錯工具使用

為協助開發者快速驗證簽章邏輯，平台提供內建的簽章除錯工具 SignUtil，支援線上產生簽章並校驗參數格式。

# 存取路徑

登入收銀台後台 → 【開發者中心】 → 【API 文件】 → 點選【簽章工具】入口

img

# 使用說明

  1. 開啟簽章工具頁面；
  2. 輸入介面所需的業務參數；
  3. 填寫有效的 access_key；
  4. 輸入對應的 secret_key（用於本地除錯，不會上傳）；
  5. 點選「產生簽章」按鈕查看計算結果；
  6. 將產生的 sign 值用於請求 Header 測試呼叫介面。

用詞說明:

img

# 安全建議

  • 簽章工具僅供除錯使用，請勿在生產環境暴露 secret_key；
  • 除錯所用的 access_key 建議將其 IP 白名單設定為 0.0.0.0，便於測試；
  • 強烈建議在除錯完成後，廢棄該 access_key 並重新建立新 Key 用於生產呼叫；
  • 請勿使用現有生產環境的 API Key 進行除錯，以避免潛在風險。

← 介面連通性測試 →