Tài liệu API

CaptchaLa cung cấp RESTful API cho mọi tích hợp phía server.

Base URL

https://apiv1.captcha.la

Xác thực

Mọi yêu cầu API đều cần các header xác thực sau:

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 xác minh phía server

💡 Dùng SDK server để bỏ qua boilerplate. Gói endpoint, retry, lỗi có kiểu:
PHP — Captcha-La/captchala-php
Go — go get github.com/Captcha-La/captchala-go

Sau khi người dùng vượt qua CAPTCHA ở frontend, server của bạn cần xác minh token do SDK trả về. Dưới đây là các endpoint xác minh phía server.

Xác minh Token phía server

Xác minh pass_token do SDK frontend trả về (tiền tố pt_). Yêu cầu header X-App-Key và 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.

Challenge Token do server cấp

Cấp một server_token có thời gian sống ngắn từ backend của bạn. Trình duyệt sẽ truyền token này khi khởi tạo challenge để chứng minh request xuất phát từ server đáng tin cậy của bạn.

Cấp Server Token

Chỉ gọi endpoint này từ server của bạn. Yêu cầu X-App-Key + X-App-Secret. Phản hồi chứa server_token (tiền tố sct_) để frontend chuyển tiếp đến khởi tạo xác minh.

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
  }
}

Body Parameters (form-urlencoded)

Trường	Mô tả
`action`	Scene nghiệp vụ, ví dụ login, register, pay. Phải khớp với action dùng trong khởi tạo xác minh.
`ttl`	Thời gian sống của token tính bằng giây. Mặc định 300, tối đa 900.
`max_uses`	Số lần token có thể được tiêu thụ. Mặc định 10.
`bind_ip`	Gắn token với một IP client. Khởi tạo từ IP khác sẽ bị từ chối.
`bind_device_id`	Gắn token với một device id cụ thể.
`bind_fingerprint`	Gắn token với một fingerprint trình duyệt cụ thể.

Khởi tạo Challenge

Được SDK gọi để bắt đầu một CAPTCHA challenge. Chấp nhận server_token tùy chọn do /v1/server/challenge/issue cấp.

Trường	Mô tả
`app_key`	App Key công khai của bạn.
`action`	Scene nghiệp vụ. Phải khớp với action dùng khi cấp server_token.
`server_token`	Tùy chọn; bắt buộc khi app có server_token_required = true.

INFO

Nếu server_token_required được bật cho app này trong dashboard, khởi tạo xác minh sẽ từ chối các request không mang server_token hợp lệ.

Mã lỗi

Mã	Mô tả
`invalid_app_key`	App Key không hợp lệ
`invalid_app_secret`	App Secret không hợp lệ
`challenge_expired`	Challenge đã hết hạn
`challenge_not_found`	Không tìm thấy challenge
`invalid_answer`	Đáp án không hợp lệ
`token_expired`	Token đã hết hạn
`token_already_used`	Token đã được sử dụng
`token_not_found`	Không tìm thấy token
`quota_exceeded`	Đã vượt hạn mức
`rate_limited`	Bị giới hạn tần suất
`rate_limit_exceeded`	Quá nhiều yêu cầu cấp token cho app này. Hãy lùi lại và thử lại.

Tài liệu API ​

Base URL ​

Xác thực ​

API xác minh phía server ​

Xác minh Token phía server ​

Challenge Token do server cấp ​

Cấp Server Token ​

Body Parameters (form-urlencoded) ​

Khởi tạo Challenge ​

Mã lỗi ​