API — Распознавание капч

Что это

BlankTrail Proxy умеет принимать задачи на распознавание капч по протоколу anti-captcha.com. Это отдельный слушатель на своём порту: стороннее ПО, уже умеющее работать с этим протоколом, достаточно направить на ваш адрес вместо адреса сервиса распознавания.

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

Как включить

Три поля в разделе captcha_api файла настроек. Рубильник и адрес можно поменять и в панели: «Настройки» → карточка «Капча-API».

captcha_api:
  enabled: true
  addr: ":8892"
  allow_lan: false
  max_concurrent: 10
  task_ttl: "5m"
  port_idle_timeout: "10m"

В контейнере

В образе всё, кроме рубильника, уже настроено: порт 8892 объявлен, поставляемые compose-файлы публикуют его на 127.0.0.1, а конфиг образа разрешает слушателю привязку не к петле. Остаётся включить — переменной либо прямо в панели. Перекрытие переменными одностороннее: они включают и задают, но не гасят включённое в конфиге.

docker run -d \
  -e BT_CAPTCHA_API_ENABLED=1 \
  -p 127.0.0.1:8892:8892 \
  ... blanktrail-proxy

Ключ и доступ

clientKey — это ключ API вашей панели, тот же самый. Отдельного ключа для капча-API нет: заводить вторую тайну с собственным хранением и ротацией ради одной поверхности незачем.

• Ключ приезжает в ТЕЛЕ запроса, как того требует протокол, а не в заголовке.
• Подбор ключа ограничивается: после серии неудач адрес получает отказ независимо от того, верен ли следующий ключ.
• Запросы не с этой машины отвергаются, пока не включён allow_lan, — включая getQueueStats и test.

Поддерживаемые типы задач

Прочие типы протокола отвечают ERROR_TASK_NOT_SUPPORTED. Это штатный ответ, а не сбой: клиент видит его сразу при создании задачи и может уйти к другому сервису, не тратя ожидания.

Как устроена работа

1. Создаёте задачу через createTask и получаете числовой taskId.
2. Опрашиваете getTaskResult, пока в ответе стоит processing.
3. Получаете ready и объект решения — его состав зависит от типа задачи.

Распознавание картинки

Картинка передаётся в base64. Ответ несёт распознанный текст в поле text.

{
  "clientKey": "YOUR_API_KEY",
  "task": {
    "type": "ImageToTextTask",
    "body": "iVBORw0KGgoAAAANSUhEUg..."
  }
}

Куки доступа

AntiGateTask проходит защиту сайта и возвращает куки. Вместе с ними в ответе приезжает адрес порта, через который эти куки обязаны предъявляться.

{
  "clientKey": "YOUR_API_KEY",
  "task": {
    "type": "AntiGateTask",
    "websiteURL": "https://example.com/",
    "proxyType": "http",
    "proxyAddress": "203.0.113.7",
    "proxyPort": 8080,
    "proxyLogin": "user",
    "proxyPassword": "pass"
  }
}

reCAPTCHA v2

Задаче нужны адрес страницы и публичный ключ сайта. Вариант без вашего прокси называется RecaptchaV2TaskProxyless и полей прокси не требует.

{
  "clientKey": "YOUR_API_KEY",
  "task": {
    "type": "RecaptchaV2Task",
    "websiteURL": "https://example.com/login",
    "websiteKey": "6Lc_aCMTAAAAA...",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...",
    "proxyType": "http",
    "proxyAddress": "203.0.113.7",
    "proxyPort": 8080
  }
}

Что происходит с присланным userAgent

Присланный userAgent не уезжает на провод. Он ВЫБИРАЕТ ближайший профиль по семейству браузера, мажорной версии и операционной системе, а на провод идёт user-agent этого профиля — вместе с согласованными с ним отпечатками TLS и HTTP/2.

Методы

{
  "errorId": 0,
  "taskId": 12
}

{
  "clientKey": "YOUR_API_KEY",
  "taskId": 12
}

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "gRecaptchaResponse": "03AGdBq26...",
    "userAgent": "Mozilla/5.0 ..."
  }
}

Коды ошибок

Коды и их названия — протокольные: клиентские библиотеки сравнивают именно строку errorCode. Ниже те, которые выдаёт этот сервис.

Границы

• Задачи живут в памяти и перезапуск не переживают: после него taskId прежних задач отвечает ERROR_NO_SUCH_CAPCHA_ID.
• Задача, не завершившаяся за отведённый бюджет, признаётся провалившейся и освобождает место в потолке.
• Обратного вызова нет: поле callbackUrl принимается и игнорируется, результат забирается опросом.
• Задачи на один и тот же сайт с одного прокси выполняются по очереди — это свойство защиты от повторов, а не потолок настроек.

Что дальше

• Обзор API и общие правила
• Порты: открытие, настройка, отпечаток
• Панель управления