Документация

CAPTCHA в SDK и API

Автоматическая обработка одинакова для PHP, JavaScript, TypeScript и Python. Она не привязана к домену целевого сайта. Для стандартного виджета достаточно обычного запроса или открытия браузерной страницы. Поддерживаемые типы, настройки источника, срок прогона, бюджет и правила доступа продолжают действовать.

Автоматический режим и отключение

Язык	HTTP без автоматического прохождения	Браузерная сессия без автоматического прохождения
PHP	`$ctx->http()->get($url, autoCaptcha: false)`	`$ctx->browser()->open($url, autoCaptcha: false)`
JavaScript	`await ctx.http().get(url, false)`	`await ctx.browser().open(url, [], {}, false)`
TypeScript	`await ctx.http().get(url, false)`	`await ctx.browser().open(url, [], {}, false)`
Python	`ctx.http().get(url, auto_captcha=False)`	`ctx.browser().open(url, auto_captcha=False)`

Если аргумент не передан, автоматический режим включён. У HTTP-клиента этот параметр есть также у post, request, pool, pages, tryJson; в Python последний метод называется try_json. В post и request аргумент следует после тела запроса. Отключение HTTP действует на данный вызов; отключение при browser.open действует на всю созданную сессию, её переходы, действия и чтение HTML.

HTTP-загрузка может перейти в браузер, если это разрешено настройками источника. При отключённом автоматическом режиме такой переход не включает прохождение CAPTCHA. Для интерактивной формы используйте браузер и закрывайте страницу в finally.

Признак успешного результата

PHP:

$page = $ctx->browser()->open($url, [], ['success_selector' => '.product-card']);
try {
    $page->waitFor('.product-card', 15000);
    $html = $page->content();
} finally {
    $page->close();
}

JavaScript и TypeScript:

const page = await ctx.browser().open(url, [], { success_selector: '.product-card' });
try {
  await page.waitFor('.product-card', 15000);
  const html = await page.content();
} finally {
  await page.close();
}

Python:

page = ctx.browser().open(url, captcha_hints={"success_selector": ".product-card"})
try:
    page.wait_for(".product-card", 15000)
    html = page.content()
finally:
    page.close()

Используйте селектор результата именно вашей операции. Он не должен постоянно присутствовать до проверки. Для обычной формы успешное заполнение CAPTCHA ещё не означает отправку формы: заполните её поля и нажмите кнопку средствами SDK. Затем проверьте ответ сервера и содержимое записей. HTTP 200 и непустое поле ответа CAPTCHA сами по себе не подтверждают успех.

Явная проверка после действия

После появления новой CAPTCHA доступен $page->solveCaptcha($hints) в PHP, await page.solveCaptcha(hints) в JavaScript/TypeScript и page.solve_captcha(hints) в Python. Метод возвращает страницу для продолжения работы, а не отчёт о допуске к данным.

Явный вызов запрашивает прохождение даже при autoCaptcha=false этой сессии. Он не отменяет отключение функции у сайта, ограничения тарифа и бюджета. Если нужно полностью исключить платные задания, отключите автоматический режим и не вызывайте этот метод.

Параметры hints

Поле	Когда нужно
`kind`	Необязательный тип: `smartcaptcha`, `yandex_image`, `yandex_text`, `turnstile`, `recaptcha_v2`, `recaptcha_v3`
`sitekey`	Открытый ключ виджета, если не определился автоматически
`action`	Действие reCAPTCHA v3
`invisible`	Логическое значение для невидимого виджета
`callback`	Имя существующего callback, если требует интеграция сайта; не исполняемый код
`success_selector`	CSS-селектор нового результата успешной операции
`submit_selector`	CSS-селектор кнопки подтверждения, если сайт не продолжает автоматически
`image_selector`	CSS-селектор только изображения задания
`instructions_selector`	Изображение с порядком выбора объектов для `yandex_image`
`answer_selector`	Поле ввода ответа для `yandex_text`

Передавайте hints третьим аргументом browser.open либо в явном методе проверки. В Python используется именованный captcha_hints. Секретный ключ сайта и содержимое всей страницы сюда не передаются. Новые задания обрабатываются в той же сессии до предела попыток; изменившееся задание не получает старый ответ. Не создавайте бесконечные повторы при отказе.

Настройки через REST API

Аутентификация: Bearer API-ключ пространства. Изменение сайта требует прав записи; доступ к чужому пространству не предоставляется. PATCH /api/v1/sites/{site} принимает настройки в params.captcha:

{
  "params": {
    "captcha": {
      "enabled": true,
      "hints": {"success_selector": ".product-card"}
    }
  }
}

Сначала прочитайте текущие params и объедините параметры клиента: PATCH верхнего уровня не означает поэлементное слияние всех вложенных объектов. Для отключения укажите enabled:false. Для агента у сайта задаются execution_target:"agent" и agent_id своего пространства.

POST /api/v1/script-versions/{version}/trial-run запускает пробную версию. Параметр params.auto_captcha действует, только если ваш исходник читает его через ctx.param и передаёт в SDK; сам по себе произвольный параметр не меняет поведение кода. Смотрите состояние через GET /api/v1/runs/{run}, сообщения через /log, результат через /preview. После проверки публикуйте версию штатным методом; это отдельное действие.

GET /api/v1/billing возвращает блок captcha: enabled, limit, used, remaining, unlimited, payg, period_end, per_run, prices, plan_limits, maximum_spending_limit. В prices находятся id, name, minimum, maximum, available, spending_limit. Денежные значения делите на unit из ответа; это стоимость одного задания. Для цены за 1 000 умножьте результат на 1 000. minimum:null означает отсутствие опубликованной нижней границы, а не бесплатное задание. Настройки стоимости меняются в приложении; отдельного публичного REST-метода прохождения CAPTCHA нет.

Ошибки, агент и проверка

Неизвестный тип, непринятый ответ, исчерпание количества или бюджета, превышение предела цены, отмена и окончание времени не должны превращаться в успешную пустую выгрузку. SDK сообщает ошибку; у прогона проверьте status и error. Готовый ответ может учитываться в расходах при отказе сайта. При неопределённом результате дождитесь сверки резерва.

На агенте используются те же методы и hints, без дополнительных ключей CAPTCHA. Связь с Akmelo должна работать. Количество попыток и расходы относятся к пространству агента.

Проверьте три ситуации: страница без CAPTCHA; форма с настоящим подтверждённым результатом; та же форма при отключении автоматического режима. Для выбора объектов дополнительно проверьте именно визуальное задание: текстовый вариант не заменяет этот тест.

Руководство пользователя · PHP · JavaScript · TypeScript · Python · Цены

spending_limit и maximum_spending_limit также выражены во внутренних денежных единицах за одно задание. Нулевой предел типа отключает платные задания; null возвращает общий предел. В приложении эти значения показаны в рублях за 1 000 заданий.

Разборы сценариев по языкам

В каждом SDK есть группа «Работа с CAPTCHA»: общий алгоритм и 12 подробных разборов с полным кодом.

PHP · JavaScript · TypeScript · Python

Явный API заданий

В SDK есть ctx.captcha() (PHP: $ctx->captcha()) для заданий, которые разработчик создаёт явно: актуальные типы, схемы, оценка цены, отправка, чтение статуса, ожидание и обратная связь. Новые типы этого каталога не определяются и не применяются браузером автоматически. Внешний ключ не нужен; вся работа учитывается в пространстве.

PHP · JavaScript · TypeScript · Python

Каталог и оценка цены не создают платное задание. Его создаёт createTask (Python: create_task). Вернувшийся taskId принадлежит Akmelo. getTaskResult читает его, waitForResult ожидает без новой отправки. Предел options.maxCost задаётся в микро₽: 1 000 000 единиц = 1 ₽. Полученный ответ сам по себе не доказывает принятие сайтом. Таймаут ожидания и остановка прогона не обещают отмену задания или возврат.