Справочник 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_SECRETWARNING
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" }client_ip необязателен, но рекомендуется — IP конечного пользователя из вашего входящего запроса, используется для дополнительных проверок риска; можно безопасно опустить.
Параметры запроса
| Параметр | Обязателен | Описание |
|---|---|---|
pass_token | Да | Token, возвращённый frontend SDK |
client_ip | Нет | IP конечного пользователя из вашего входящего запроса |
keep_token | Нет | true = проверить, не расходуя Token (по умолчанию false) |
expected_action | Нет | Action, который вы ожидаете для этого endpoint, например login. Если задан, а Token был выдан для другого action, ответ — valid: false с error: "action_mismatch". Точное совпадение с учётом регистра. |
expected_hostname | Нет | Ожидаемый hostname (web) или package / bundle id приложения (native), например www.example.com. Принимает строку через запятую или массив; *.example.com соответствует любому поддомену (но не самому домену). Без учёта регистра. Если задан, а Token был решён в другом месте — или источник не удалось определить, — ответ — valid: false с error: "hostname_mismatch". |
Если не передавать expected_action / expected_hostname, поведение остаётся прежним. При несовпадении Token всё равно расходуется (если только keep_token не равен true), поэтому его нельзя использовать повторно.
{
"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
},
"hostname": "your-site.com",
"challenge_ts": "2025-06-15T15:06:40Z",
"risk_level": "low",
"risk_labels": []
}
}TIP
Проверяйте data.valid === true и что data.action соответствует ожидаемому сценарию (отклоняйте, если Token из потока pay предъявляется на /login) — или просто передайте expected_action / expected_hostname, и API сделает это за вас. Token одноразовые.
Дополнительные поля
Добавлены в успешные ответы (все существующие поля не изменились):
hostname— hostname страницы, на которой был решён запрос (web), или package / bundle id приложения (native).null, если неизвестно.challenge_ts— время решения запроса, ISO 8601 в UTC.null, если неизвестно.risk_level— уровень риска на момент решения:low/medium/high/critical.risk_labels— грубые категории риска, замеченные в этой сессии, напримерautomation,proxy,velocity,ip_reputation,device,inconsistency. Пустой массив, если ничего примечательного. Со временем могут добавляться новые метки — относитесь к неизвестным значениям как к информационным.
Это мягкие сигналы для вашего логирования и собственных решений о риске; Token уже принят.
Ответ при несовпадении:
{ "code": 0, "data": { "valid": false, "error": "action_mismatch" } }captcha_args
captcha_args возвращает контекст, зафиксированный на момент решения, — для логирования / вашей собственной оценки риска:
platform—web/android/ios/flutter/windows/ …user_ip— IP конечного пользователя на момент решения запросаreferer— URL страницы решения (web);nullв nativepkg— package / bundle id приложения (native);nullв websolved_at— время завершения решения (unix-секунды)risk_score— оценка риска на момент решения (0-100, чем выше, тем рискованнее)
Типы Token
В зависимости от состояния сервиса SDK может передать вашему frontend Token разных типов. Всё определяет префикс:
| Префикс | Когда выдаётся | Что возвращает /v1/validate | Рекомендуемая обработка |
|---|---|---|---|
pt_ | Проверка пройдена в обычном режиме | valid: true (одноразовый) | Принять |
dg_ | Квота тарифа исчерпана (деградированный режим) | valid: false, degraded: true, reason | На ваше усмотрение — см. ниже |
offline_ | Основной API недоступен; выдаётся обходным worker | При использовании серверного SDK автоматически проверяется через резервный API | Принять после проверки через резервный API |
co_ | Недоступны основной и резервный API; генерируется на стороне клиента | Не может быть проверен на сервере | Применяйте собственные меры контроля риска (лимиты частоты и т. п.) |
Деградированный режим (квота исчерпана)
Когда приложение исчерпало месячную квоту (а сверхлимитная тарификация недоступна), виджет не прерывает сценарий конечного пользователя. Вместо показа ошибки SDK сразу завершается с Token dg_:
- Конечный пользователь не видит ошибки — ваша форма отправляется как обычно.
/v1/validateна вашем сервере возвращает:
{
"code": 0,
"data": {
"valid": false,
"degraded": true,
"reason": "quota_exhausted",
"expired": false
}
}Ключевые свойства:
- Для деградированных Token
validвсегдаfalse— безопасно по умолчанию. Если ваш код проверяет толькоvalid, для вас ничего не меняется. - Пропускать ли запрос — решаете вы: принимайте
valid || degraded, чтобы не терять конверсии, пока вы повышаете тариф, или отклоняйте и показывайте собственный запасной вариант. - Token
dg_подписаны HMAC для каждого приложения и истекают через 5 минут. Их выдача не расходует квоту и никогда не тарифицируется. - Серверные SDK предоставляют это как
isDegraded()/getDegradedReason()(PHP) иresult.Degraded/result.DegradedReason(Go).
INFO
Истёкшие подписки никогда не включают деградированный режим — они автоматически переходят на тариф Free и продолжают работать в рамках бесплатной квоты. Деградированный режим касается только использования сверх квоты вашего тарифа.
Тестовые ключи
Используйте эти публичные пары ключей, чтобы тестировать обработку /v1/validate на вашем сервере — в CI, staging или локальной разработке — без создания приложения и решения CAPTCHA. С серверными SDK они работают точно так же, как настоящие App Key / Secret.
| Поведение | X-App-Key | X-App-Secret |
|---|---|---|
| Всегда проходит | test_pass_7f3c9a2e5b18d4f6 | test_secret_pass_c41e8b0d27a95f3e |
| Всегда отклоняет | test_fail_2d9e6b4a0c7f1835 | test_secret_fail_9b5f03e7d1a46c28 |
- Всегда проходит — любой непустой
pass_tokenвозвращаетvalid: true. Ответ содержит те же поля, что и настоящий успешный ответ, плюсtest: true, так что ваш код разбора тоже проверяется:
{
"code": 0,
"data": {
"valid": true,
"test": true,
"challenge_id": null,
"action": "test",
"uid": null,
"captcha_args": {
"platform": "web",
"user_ip": null,
"referer": null,
"pkg": null,
"solved_at": 1750000000,
"risk_score": 0
},
"hostname": null,
"challenge_ts": "2025-06-15T15:06:40Z",
"risk_level": "low",
"risk_labels": []
}
}- Всегда отклоняет — любой непустой
pass_tokenвозвращает:
{ "code": 0, "data": { "valid": false, "error": "test_always_fail", "test": true } }Примечания:
- Secret должен соответствовать своему ключу; неверный или перепутанный secret возвращает
invalid_app_secret, а пустойpass_token—missing_token, как и у настоящих приложений. keep_token,expected_actionиexpected_hostnameдля тестовых ключей игнорируются.- Тестовые ключи никогда не создают записей, не учитываются ни в какой квоте и никогда не тарифицируются. Их нельзя использовать как учётные данные настоящего приложения.
- В production проверяйте
data.testи отклоняйте такие ответы — или просто убедитесь, что тестовые ключи никогда не настроены в production. - Пока только на стороне сервера. Эти ключи тестируют вызов проверки на вашем backend; это не frontend sitekey, и с ними нельзя отобразить виджет. Тестовые frontend sitekey появятся позже.
- Token, начинающиеся с
pt_test_, зарезервированы для тестирования и всегда отклоняются настоящими приложениями (valid: false,error: "token_invalid").
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.
Резервные офлайн-эндпоинты
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)
{ "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 не найден |
token_invalid | /v1/validate: Token недействителен для этого приложения (например, тестовый Token pt_test_, отправленный настоящему приложению). |
test_always_fail | /v1/validate: возвращается тестовым ключом «всегда отклоняет». |
quota_exceeded | Квота превышена |
rate_limited | Превышен лимит частоты |
rate_limit_exceeded | Слишком много запросов на выпуск для этого приложения. Сделайте паузу и повторите. |
action_mismatch | /v1/validate: задан expected_action, а Token принадлежит другому action. |
hostname_mismatch | /v1/validate: задан expected_hostname, а Token был решён на другом (или неизвестном) hostname / package. |
service_online | Запрос попал в резервный офлайн-сервис, хотя основной API работает. Используйте https://apiv1.captcha.la — см. Резервные офлайн-эндпоинты. |