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 is server-side only. Never expose it to browsers, mobile apps, or public repos.

伺服器端驗證 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" }

json

{
  "code": 0,
  "data": {
    "valid": true,
    "challenge_id": "ch_xxx",
    "action": "login",
    "uid": null,
    "client_ip": "1.2.3.4",
    "risk_score": 12
  }
}

TIP

Validate data.valid === true and that data.action matches the scene you expected (reject if a token from a pay flow is presented at /login). Tokens are single-use.

伺服器端簽發驗證 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） ​

初始化挑戰 ​

錯誤碼 ​