Scarnox · Blog

API решателя капчи: как он работает и как его вызвать

API решателя капчи — это веб-сервис, который вы вызываете по HTTP. Вы передаёте ему данные капчи: тип задачи, sitekey страницы и URL страницы. Он возвращает токен, который сайт принимает как доказательство, что проверка пройдена. Эндпоинт Scarnox работает именно так и синхронный: один запрос даёт ответ.

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

Что делает API, а что нет

Ваш код находит капчу на странице, считывает её sitekey и отправляет решателю. Решатель возвращает токен. Ваш код записывает токен в поле формы, которое ожидает сайт, и отправляет форму.

Решатель не загружает вашу страницу, ничего не нажимает и не отправляет вашу форму. Он только формирует токен. Учёт этой границы упрощает рассуждения об интеграции: всё, что касается сессии, cookie и тайминга запросов, остаётся в вашем коде.

Сегодня единственный живой тип задачи — PopularCaptcha, proxyless, то есть PopularCaptchaTaskProxyless. Другие типы капчи в планах. Гайд по типам капчи показывает, что есть что.

Эндпоинт

Отправьте POST-запрос на:

POST https://api.scarnox.com/api/tasks/create
Authorization: Bearer scarnox_YOURAPIKEY
Content-Type: application/json

Тело запроса описывает задачу:

{
  "captcha_type": "PopularCaptchaTaskProxyless",
  "site_key": "10000000-ffff-ffff-ffff-000000000001",
  "site_url": "https://example.com/signup"
}

Три обязательных поля:

captcha_type: тип задачи. Для живых решений сегодня это PopularCaptchaTaskProxyless.
site_key: sitekey, считанный со страницы. Sitekey PopularCaptcha — это UUID.
site_url: URL страницы, на которой появляется капча. Используйте реальную страницу, а не главную, потому что токен привязан к странице, которая показала виджет.

Есть три необязательных поля. proxy принимает значение вида http://user:pass@host:port и используется с типами задач с прокси. rqdata и is_invisible нужны для отдельных вариантов виджетов. Полный список типов задач и полей — в справочнике API.

Синхронный вызов: без опроса

Вызов блокируется, пока токен не готов. Опрашивать ничего не нужно, и во второй запрос «получить результат» в этом сценарии нет. Установите таймаут HTTP-клиента около 185 секунд, чтобы медленное решение не выглядело как сетевой сбой.

В Python с библиотекой requests это выглядит так:

import requests

r = requests.post(
    "https://api.scarnox.com/api/tasks/create",
    headers={"Authorization": "Bearer scarnox_YOURAPIKEY"},
    json={
        "captcha_type": "PopularCaptchaTaskProxyless",
        "site_key": "10000000-ffff-ffff-ffff-000000000001",
        "site_url": "https://example.com/signup",
    },
    timeout=185,
)
data = r.json()

Читайте ключ из переменной окружения, а не вписывайте его в скрипт. Тот, кто может прочитать исходный код, не должен иметь возможность тратить ваш баланс.

Разбор ответа

Успешное решение возвращает errorId равный 0, токен внутри solution и поле cost:

{"errorId": 0, "solution": {"token": "..."}, "cost": ...}

Неудачное решение возвращает errorId не равный 0, а также машиночитаемый errorCode и понятный человеку errorDescription:

{"errorId": 1, "errorCode": "...", "errorDescription": "..."}

Проверяйте errorId в теле ответа при каждом вызове. Не считайте, что завершённый HTTP-запрос — это уже токен. Самое важное правило: вы платите только когда errorId равен 0. Неудачные решения не списываются. Актуальные тарифы — на странице цен.

Время жизни токена

Токены PopularCaptcha истекают примерно через две минуты. Отправляйте токен сразу, как получили. Не кешируйте токены для последующего использования и не решайте заранее до отправки формы. Если между получением токена и отправкой формы у вас несколько шагов, переносите решение на самый последний момент.

Передача токена в форму

Большинство сайтов читают ответ PopularCaptcha из поля формы h-captcha-response. Многие также принимают g-recaptcha-response с тем же значением, поэтому отправка обоих полей — распространённый безопасный выбор:

requests.post("https://example.com/signup", data={
    "email": "you@example.com",
    "h-captcha-response": token,
    "g-recaptcha-response": token,
})

Если форма не принимает токен, обычно причина в sitekey или URL страницы, которые не совпадают со страницей, где реально был виджет. Перепроверьте значения, прежде чем винить решатель.

Обработка ошибок

Продакшн-интеграции нужна короткая памятка привычек:

Проверяйте errorId и каждый раз записывайте errorCode в лог. Этот код поддержка спросит в первую очередь.
Повторяйте неудачные решения с небольшим backoff. Так как неудачные решения не списываются, повтор не стоит вам решения, но плотный цикл всё равно тратит время и может упереться в ваши собственные лимиты запросов.
Установите клиентский таймаут около 185 секунд и считайте таймаут ошибкой, которую нужно повторить, а не успехом.
Держите токен и отправку формы близко друг к другу во времени, потому что токен быстро истекает.

Подробнее обо всём этом — в гайде по повторам и обработке ошибок.

Начало работы

Создайте аккаунт: вы можете начать с пробного баланса, карта не нужна. Затем выполните запрос из примера выше на тестовой странице, которой управляете, и проверьте, что форма принимает токен, прежде чем подключать что-то важное.