---
title: Tài liệu API
---

# 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`](https://github.com/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" }
```

`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.

```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` 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 {#server-token}

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