Справочник API

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

Базовый URL

https://apiv1.captcha.la

Базовый URL только один

Все эндпоинты на этой странице находятся на apiv1.captcha.la. Резервные хосты (bypass.*, fallbackapiv1.*) — это цели аварийного переключения, к которым SDK обращаются сами во время сбоя: если направить туда свою интеграцию, вернётся service_online.

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

Все запросы к 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 (中文)
Go — go get github.com/Captcha-La/captchala-go · README

После того как пользователь проходит 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 с вашего 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.

Резервные офлайн-эндпоинты

CaptchaLa держит резервный сервис на отдельных хостах, чтобы проверка продолжала работать, пока основной API недоступен:

Хост	Кто вызывает	Назначение
`bypass.captchala.com` · `bypass.captcha-cdn.net`	Web / нативный SDK (сторона пользователя)	Проводит офлайн-проверку и выдаёт pass token `offline_`, пока основной API лежит
`fallbackapiv1.captchala.com` · `fallbackapiv1.captcha-cdn.net`	Серверные SDK	Проверяет токены `offline_` (`POST /api/validate`)

Это цели аварийного переключения, а не альтернативный API. SDK переключаются на них самостоятельно и только после реального отказа основного API, а после восстановления возвращаются обратно. Ничто в вашей конфигурации не должно указывать на эти хосты.

`service_online` (HTTP 503)

json

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

Эта ошибка приходит, пока основной API работает: резервный сервис принимает трафик только во время сбоя. Запрос ушёл на bypass.* вместо https://apiv1.captcha.la — исправьте URL, повторы не помогут.

Частые причины:

Причина	Что сделать
В опции SDK `apiServer` указан bypass-хост	Вернуть `https://apiv1.captcha.la` либо убрать опцию и дать SDK выбрать сервер
`bypassServers` переопределён вручную	Убрать переопределение, если мы не выдавали вам конкретные хосты
Самописный HTTP-клиент скопировал bypass-URL (например, из devtools во время инцидента)	Обращаться к `https://apiv1.captcha.la`, а переключение оставить SDK — резервный сервис не принимает обычный трафик проверок
Балансировщик / прокси / DNS переписывает хост API	Вернуть upstream на `apiv1.captcha.la`

TIP

Серверной проверке резервный хост тоже не нужен: достаточно POST /v1/validate на apiv1.captcha.la, а токены offline_ серверные SDK для PHP / Go проверяют через резервный API автоматически.

Коды ошибок

Код	Описание
`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`	Слишком много запросов на выпуск для этого приложения. Сделайте паузу и повторите.
`service_online`	Запрос попал в резервный офлайн-сервис, хотя основной API работает. Используйте `https://apiv1.captcha.la` — см. Резервные офлайн-эндпоинты.

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

Базовый URL ​

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

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

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

Token запроса, выданный сервером ​

Выпуск Server Token ​

Параметры тела (form-urlencoded) ​

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

Резервные офлайн-эндпоинты ​

service_online (HTTP 503) ​

Коды ошибок ​

Справочник API

Базовый URL

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

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

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

Token запроса, выданный сервером

Выпуск Server Token

Параметры тела (form-urlencoded)

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

Резервные офлайн-эндпоинты

`service_online` (HTTP 503)

Коды ошибок