Справочник 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 (中文)
• 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.

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

{
  "code": 0,
  "data": {
    "valid": true,
    "challenge_id": "ch_xxx",
    "action": "login",
    "uid": null,
    "client_ip": "1.2.3.4",
    "risk_score": 12
  }
}

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 передаёт при инициализации запроса.

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

Параметры тела (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	Слишком много запросов на выпуск для этого приложения. Сделайте паузу и повторите.