Skip to content

Справочник 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, обрабатывает повторы, выдаёт типизированные ошибки:

После того как пользователь проходит 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 конечного пользователя из вашего входящего запроса, используется для дополнительных проверок риска; можно безопасно опустить.

Параметры запроса ​

ПараметрОбязателенОписание
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), поэтому его нельзя использовать повторно.

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
    },
    "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 уже принят.

Ответ при несовпадении:

json
{ "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 в native
  • pkg — package / bundle id приложения (native); null в web
  • solved_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 на вашем сервере возвращает:
json
{
  "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-KeyX-App-Secret
Всегда проходитtest_pass_7f3c9a2e5b18d4f6test_secret_pass_c41e8b0d27a95f3e
Всегда отклоняетtest_fail_2d9e6b4a0c7f1835test_secret_fail_9b5f03e7d1a46c28
  • Всегда проходит — любой непустой pass_token возвращает valid: true. Ответ содержит те же поля, что и настоящий успешный ответ, плюс test: true, так что ваш код разбора тоже проверяется:
json
{
  "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 возвращает:
json
{ "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 передаёт при инициализации запроса.

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.netWeb / нативный 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_usedToken уже использован
token_not_foundToken не найден
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 — см. Резервные офлайн-эндпоинты.

MIT-licensed examples · CaptchaLa is operated independently