跳至主要内容

2.1 總體說明

2.1.1 存取網址​

測試環境
正式環境https://api.racent.com/

2.1.2 介面簽章驗證​

介面使用基於 API 簽章的身分驗證機制，可確保請求的完整性與安全性。每次呼叫介面時，都必須攜帶簽章參數，伺服器端會驗證簽章的正確性。

公共參數​

以下參數 必須 包含在每一次介面請求的 Query String 中：

參數名稱參數類型描述範例值
access_keyString帳號 ID，用於識別呼叫方身分1000000059
signature_nonceString簽章唯一隨機數，用於防止重送攻擊，
每次請求必須使用不同的隨機值		2206561-6450-430e-8b0a-26980754c0de
timestampString請求發起的時間戳（單位：秒）1673418729
signature_versionString簽章演算法版本，固定為 1.01.0
signature_methodString簽章演算法，固定為 md5md5
signatureString本次請求的簽章值，由其他參數與金鑰計算得出85ef54421c69edeb098c7b557c6c5cd5
說明：
  • access_key 和 AccessSecret（金鑰）可在登入後從 介面管理-API存取憑證 處取得。
  • signature_nonce 建議使用 UUID 或足夠隨機的字串，確保每次請求皆為唯一。
  • timestamp 與伺服器時間相差超過一定範圍（例如 5 分鐘）的請求將會被拒絕。

簽章機制​

第一步：建構正規化請求字串​

1.參數排序​

將所有公共參數（除 signature 外）與介面自訂參數依照參數名稱字典序升冪排列。

2.參數編碼​

對每個參數的名稱與值使用 UTF-8 編碼，並遵循 RFC3986 規則進行 URL 編碼：

  • 不進行編碼的字元：A-Z a-z 0-9 - _ . ~
  • 其他字元（例如 空格、/、?、=等）需編碼為 %XX 格式，例如空格編碼為 %20
3.拼接參數​
  • 使用 = 連接編碼後的參數名稱與參數值
  • 使用 & 連接所有參數對，維持字典序

最終取得的字串稱為 stringToSign。

第二步：建構簽章字串並計算簽章​

根據請求類型不同，簽章計算方式如下：

GET 请求
signature = md5(AccessSecret + md5( HTTPMethod + stringToSign ))
POST / PUT 请求（含 Body 参数）
signature = md5(AccessSecret + md5( HTTPMethod + stringToSign ) + md5( jsonStringToBody ))
說明：
  • HTTPMethod 必須為大寫，如 GET、POST
  • jsonStringToBody 為請求 Body 的原始 JSON 字串（需去除空格和換行，並且欄位需排序）
  • 公式中的 + 表示字串拼接，不參與計算

參數編碼規則（RFC3986）​

字元類型處理方式範例
A-Z, a-z, 0-9, -, _, ., ~不編碼abc123 → abc123
空格編碼為 %20a b → a%20b
其他 ASCII 字元編碼為 %XX（十六進位）" → %22

GET 請求範例​

假設：

  • access_key = "1000000059"
  • AccessSecret = "19938c89c13ddf5da7636333a5aa4c0e"
  • signature_nonce = "iobzx72w63"
  • timestamp = "1755597512"

Step1：構造 stringToSign​

access_key=1000000059&signature_method=md5&signature_nonce=iobzx72w63&signature_version=1.0&timestamp=1755597512

步驟2：計算簽名​

temp = md5("GET" + stringToSign)  // 结果为"9bc92e0f3e239dc628ebc416294422ba"
signature = md5(AccessSecret + temp)  // 结果为"a33bdb81ea79eb4ebbac9da043309c00"

最終請求 URL：​

https://api.racent.com/api/v1/domain/tld?access_key=1000000059&signature_nonce=iobzx72w63&timestamp=1755597512&signature_version=1.0&signature_method=md5&signature=a33bdb81ea79eb4ebbac9da043309c00

POST 請求範例（含 Body）​

假設 Body 為：

{"domain":"example.com"}

其 MD5 值為： 640c69595341436be9b0d1516d3d37ac

Step1：構造 stringToSign​

access_key=1000000059&signature_method=md5&signature_nonce=abjipo5ar5a&signature_version=1.0&timestamp=1755598851

Step2：計算簽章​

temp = md5("POST" + stringToSign)  // 结果为 "5aba63e4af1b7a4080eaf47d0fc56efe"
signature = md5(AccessSecret + temp + "640c69595341436be9b0d1516d3d37ac")  // 结果为 "29487fd8ae5b828415d05b691caf015c"

最終請求 URL：​

https://api.racent.com/v1/domain/query-domain?access_key=1000000059&signature_nonce=abjipo5ar5a&timestamp=1755598851&signature_version=1.0&signature_method=md5&signature=29487fd8ae5b828415d05b691caf015c

2.1.3 介面限流​

預設限流規則，針對同一使用者存取同一個介面，限制次數如下：

  • 每分鐘60次
  • 每小時500次
  • 每天1000次

2.1.4 介面回傳參數​

參數說明​

參數名稱參數類型描述範例值
dataObject業務資料，若介面報錯，回傳值為null
codeInt錯誤碼，成功回傳0，報錯回傳對應的錯誤碼0，1000，1001
messageString報錯說明資訊，介面成功回傳"Success"over-rate-limit
errorsObject部分報錯，會透過該欄位提供更具體的錯誤說明
request_idString請求ID，主要用於協助排查問題039ecdca-44d5-430f-8521-020f4953bcc5
最後於 更新