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

Chỉ có một base URL

Mọi endpoint trong trang này đều nằm trên apiv1.captcha.la. Các host dự phòng (bypass.*, fallbackapiv1.*) là đích failover mà SDK tự chuyển sang khi API chính gặp sự cố — trỏ tích hợp của bạn vào đó sẽ nhận service_online.

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.

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 là tùy chọn nhưng nên truyền — IP của người dùng cuối trong request gửi tới backend của bạn, dùng cho các kiểm tra rủi ro bổ sung; bỏ qua cũng an toàn.

{
  "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 là các trường mang tính tham khảo (dùng cho ghi log hoặc phân tích rủi ro): platform, user_ip, referer, pkg, solved_at, risk_score.

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.

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

{
  "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ệ.

Endpoint dự phòng offline

CaptchaLa duy trì một dịch vụ dự phòng trên các host riêng để việc xác minh vẫn chạy khi API chính không truy cập được:

Host	Ai gọi	Mục đích
bypass.captchala.com · bypass.captcha-cdn.net	SDK web / native (phía người dùng cuối)	Thực hiện xác minh offline và cấp pass token offline_ khi API chính sập
fallbackapiv1.captchala.com · fallbackapiv1.captcha-cdn.net	SDK server	Xác minh token offline_ (POST /api/validate)

Đây là đích failover, không phải một API thay thế. SDK tự chuyển sang, và chỉ chuyển sau khi API chính thực sự lỗi, rồi tự quay lại khi API chính hồi phục. Không cấu hình nào của bạn nên trỏ tới các host này.

service_online (HTTP 503)

{ "code": -1, "error": "service_online", "message": "Main API is online, please use main API" }

Bạn gặp lỗi này khi API chính vẫn chạy: dịch vụ dự phòng chỉ nhận lưu lượng lúc có sự cố. Request đã đi tới bypass.* thay vì https://apiv1.captcha.la — hãy sửa URL, thử lại không có tác dụng.

Nguyên nhân thường gặp:

Nguyên nhân	Cách xử lý
Tùy chọn apiServer của SDK trỏ vào host bypass	Đặt lại https://apiv1.captcha.la, hoặc bỏ hẳn tùy chọn để SDK tự chọn
bypassServers bị ghi đè thủ công	Bỏ ghi đè, trừ khi chúng tôi đã cấp host riêng cho bạn
Client HTTP tự viết sao chép URL bypass (ví dụ lấy từ devtools lúc có sự cố)	Gọi https://apiv1.captcha.la và để SDK lo failover — dịch vụ dự phòng không nhận lưu lượng challenge thông thường
Load balancer / proxy / DNS ghi đè host API	Trỏ upstream về lại apiv1.captcha.la

TIP

Xác minh phía server cũng không cần host dự phòng: chỉ cần POST /v1/validate trên apiv1.captcha.la; SDK server PHP / Go tự xử lý token offline_ qua API dự phòng.

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.
service_online	Request đi vào dịch vụ dự phòng offline trong khi API chính vẫn hoạt động. Hãy dùng https://apiv1.captcha.la — xem Endpoint dự phòng offline.