---
title: Справочник API
---

# Справочник API

CaptchaLa предоставляет RESTful API для всех серверных интеграций.

## Базовый URL

```
https://apiv1.captcha.la
```

## Аутентификация

Все запросы к API требуют заголовков аутентификации:

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

::: warning
`X-App-Secret` предназначен только для сервера. Никогда не передавайте его в браузер, мобильные приложения или публичные репозитории.
:::

## API серверной проверки

> 💡 **Используйте серверный SDK, чтобы пропустить шаблонный код.** Оборачивает endpoint, обрабатывает повторы, выдаёт типизированные ошибки:
> - **PHP** — [`Captcha-La/captchala-php`](https://github.com/Captcha-La/captchala-php) ([中文](https://github.com/Captcha-La/captchala-php/blob/main/README_zh.md))
> - **Go** — `go get github.com/Captcha-La/captchala-go` · [README](https://github.com/Captcha-La/captchala-go)

После того как пользователь проходит CAPTCHA на frontend, ваш сервер должен проверить Token, возвращённый SDK. Ниже перечислены endpoint серверной проверки.

### Серверная проверка Token

Проверяет pass_token из frontend SDK (с префиксом 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` (IP на момент решения), `referer`, `pkg`, `solved_at`, `risk_score`.

::: tip
Проверяйте `data.valid === true` **и** что `data.action` соответствует ожидаемому сценарию
(отклоняйте, если Token из потока `pay` предъявляется на `/login`). Token одноразовые.
:::

## Token запроса, выданный сервером {#server-token}

Выпустите короткоживущий server_token с вашего backend. Браузер затем передаёт этот Token при инициализации запроса, подтверждая, что запрос поступил с вашего доверенного сервера.

### Выпуск Server Token

Вызывайте этот endpoint только со своего сервера. Требует X-App-Key + X-App-Secret. Ответ содержит server_token (префикс sct_), который frontend передаёт при инициализации запроса.

```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 к конкретному идентификатору устройства. |
| `bind_fingerprint` | Привязка Token к конкретному отпечатку браузера. |

### Инициализация запроса

Вызывается SDK для запуска запроса CAPTCHA. Принимает опциональный server_token, выданный через /v1/server/challenge/issue.

| Поле | Описание |
| --- | --- |
| `app_key` | Ваш публичный App Key. |
| `action` | Бизнес-сценарий. Должен совпадать с action, использованным при выпуске server_token. |
| `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` | Слишком много запросов на выпуск для этого приложения. Сделайте паузу и повторите. |