API 參考

CaptchaLa 提供 RESTful API 介面，支援所有功能的伺服器端呼叫。

API 位址

https://apiv1.captcha.la

認證方式

所有 API 請求都需要攜帶認證標頭：

X-App-Key:    YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

WARNING

X-App-Secret 僅限伺服器端使用，切勿暴露於瀏覽器、行動 App 或公開的程式碼倉庫中。

伺服器端驗證 API

💡 用伺服器端 SDK 省去 boilerplate。 封裝端點 + 重試 + 型別化錯誤:
PHP — Captcha-La/captchala-php
Go — go get github.com/Captcha-La/captchala-go

使用者通過前端驗證碼後，您的伺服器需要驗證 SDK 返回的 Token。以下是伺服器端驗證介面。

伺服器端驗證 Token

驗證前端 SDK 返回的 pass_token（前綴為 pt_）。需要攜帶 X-App-Key 和 X-App-Secret 標頭。

bash

POST /v1/validate
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "pass_token": "pt_xxx", "client_ip": "1.2.3.4" }

client_ip 為選填但建議帶上 — 終端使用者在您後端請求中的來源 IP，用於額外的風險檢查；省略亦可。

json

{
  "code": 0,
  "data": {
    "valid": true,
    "challenge_id": "ch_xxx",
    "action": "login",
    "uid": null,
    "captcha_args": {
      "platform": "web",
      "user_ip": "1.2.3.4",
      "referer": "https://your-site.com/login",
      "pkg": null,
      "solved_at": 1750000000,
      "risk_score": 12
    }
  }
}

captcha_args 為資訊性欄位（供您記錄與風控使用）：platform、user_ip、referer、pkg、solved_at、risk_score。

TIP

請同時驗證 data.valid === true 以及 data.action 與您預期的場景一致（若一張 pay 流程簽發的 token 被送到 /login，應予以拒絕）。Token 為單次使用。

伺服器端簽發驗證 Token

由您的伺服器端簽發短時效 server_token，再由瀏覽器在初始化挑戰時攜帶該 Token，以證明請求來自受信任的伺服器。

簽發 server_token

僅允許從您的伺服器端呼叫。需要 X-App-Key + X-App-Secret。回應回傳 server_token（前綴 sct_），前端需在驗證初始化時帶上。

bash

POST /v1/server/challenge/issue
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/x-www-form-urlencoded

action=login&ttl=300&max_uses=1&bind_ip=1.2.3.4

json

{
  "code": 0,
  "data": {
    "server_token": "sct_xxxxxxxxxxxx",
    "expires_in": 300,
    "issued_at": 1713600000
  }
}

請求體參數（form-urlencoded）

欄位	說明
`action`	業務場景，如 login、register、pay。需與後續驗證初始化使用的 action 一致。
`ttl`	Token 有效期（秒）。預設 300，最大 900。
`max_uses`	Token 最大可用次數。預設 10。
`bind_ip`	將 Token 綁定到指定用戶端 IP，來自其他 IP 的初始化請求將被拒絕。
`bind_device_id`	將 Token 綁定到指定裝置 ID。
`bind_fingerprint`	將 Token 綁定到指定瀏覽器指紋。

初始化挑戰

由 SDK 呼叫以開始一次驗證碼挑戰。可選參數 server_token 由 /v1/server/challenge/issue 簽發。

欄位	說明
`app_key`	您的公開 App Key。
`action`	業務場景，需與簽發 server_token 時使用的 action 一致。
`server_token`	可選；當應用開啟 server_token_required = true 時必填。

INFO

如在控制台為該應用啟用了 server_token_required，驗證初始化將拒絕所有未攜帶有效 server_token 的請求。

錯誤碼

錯誤碼	說明
`invalid_app_key`	App Key 無效
`invalid_app_secret`	App Secret 無效
`challenge_expired`	驗證碼已過期
`challenge_not_found`	驗證碼不存在
`invalid_answer`	答案錯誤
`token_expired`	Token 已過期
`token_already_used`	Token 已被使用
`token_not_found`	Token 不存在
`quota_exceeded`	配額已用盡
`rate_limited`	請求頻率超限
`rate_limit_exceeded`	該應用的簽發請求過於頻繁，請稍後再試。

API 參考 ​

API 位址 ​

認證方式 ​

伺服器端驗證 API ​

伺服器端驗證 Token ​

伺服器端簽發驗證 Token ​

簽發 server_token ​

請求體參數（form-urlencoded） ​

初始化挑戰 ​

錯誤碼 ​