reCAPTCHA v2, v3 и Enterprise: какие поля CapSkip отправлять

recaptcha v2 vs v3 - reCAPTCHA v2 vs v3 vs Enterprise: CapSkip Fields to Send

Вопрос reCAPTCHA v2 или v3 имеет практический ответ для всех, кто получает токены в коде: он определяет, какие поля попадают в запрос к сервису. Для v2 нужны sitekey и адрес страницы, для v3 дополнительно имя action, а Enterprise добавляется флагом к любому из них. Это шпаргалка по запросам. Что представляет собой каждый виджет и как его распознать, сначала прочтите в материале о том, что такое reCAPTCHA и возвращайтесь сюда за полями.

Какие поля CapSkip нужны для каждого варианта reCAPTCHA

CapSkip совместим с 2captcha, поэтому каждый вариант отправляется методом userrecaptcha с разными флагами: именно флаги выбирают вариант. Названия взяты из раздела Документация API и проверены по исходникам SDK для Python и Node.js версии 1.7.0.

ВариантПоля, отправляемые в in.phpВызов PythonВызов Node.js
v2 checkboxgooglekey, pageurlrecaptcha(sitekey, url)recaptcha(sitekey, url)
v2 invisibleдобавляет invisible=1добавляет invisible=1options с invisible, равным 1
v3добавляет version=v3 и actionversion="v3", action="login"options с version, равным v3, и action
Enterprise v2добавляет enterprise=1добавляет enterprise=1options с enterprise, равным 1
Enterprise v2 invisibleдобавляет enterprise=1 и invisible=1оба именованных аргументаобе опции
Enterprise v3добавляет version=v3, action и enterprise=1все три именованных аргументавсе три опции

Три детали сэкономят время при отладке. Во-первых, документация API указывает action=verify как значение по умолчанию для v3. Ни один SDK не отправляет action, если его не указать, поэтому значение по умолчанию подставляет приложение, а проверить это я не смог. Если страница проверяет action=login то его нужно передавать явно. Во-вторых, callback не входит в запрос: CapSkip возвращает токен, а для виджета с callback или invisible код вашей страницы вызывает callback с этим токеном. В-третьих, в документации API сказано, что страница v2 Enterprise может нести дополнительную пользовательскую строку в параметре s или data-s. Если она есть на странице, отправьте её в поле data-s, которое SDK принимают под именем datas.

Вот варианты v2 на Python. Токен возвращается под ключом code в результате.

# pip install capskip
from capskip import CapSkip

solver = CapSkip(host="127.0.0.1", port=8080)
PAGE = "https://example.com/page-with-recaptcha"
KEY = "YOUR_SITEKEY"

# Checkbox v2, then the invisible flavour of v2.
v2 = solver.recaptcha(sitekey=KEY, url=PAGE)
invisible = solver.recaptcha(sitekey=KEY, url=PAGE, invisible=1)

# Enterprise is a flag. Add the page's data-s value if it has one.
ent = solver.recaptcha(sitekey=KEY, url=PAGE, enterprise=1,
                       datas="YOUR_DATA_S")
ent_inv = solver.recaptcha(sitekey=KEY, url=PAGE, enterprise=1, invisible=1)

print(v2["code"][:20])   # token, ready for the form field

Для v3 укажите версию и action, который страница передаёт в свой вызов execute.

# pip install capskip
from capskip import CapSkip

solver = CapSkip(host="127.0.0.1", port=8080)
PAGE = "https://example.com/page-with-recaptcha"
KEY = "YOUR_SITEKEY"

v3 = solver.recaptcha(sitekey=KEY, url=PAGE, version="v3", action="login")

# v3 Enterprise adds the same flag as v2 Enterprise.
ent_v3 = solver.recaptcha(sitekey=KEY, url=PAGE, version="v3",
                          action="login", enterprise=1)

print(v3["code"][:20])   # token for the action you named

SDK для Node.js принимает те же варианты в виде объекта options после sitekey и адреса страницы.

// npm install capskip
const { CapSkip } = require('capskip');

const solver = new CapSkip({ host: '127.0.0.1', port: 8080 });
const PAGE = 'https://example.com/page-with-recaptcha';

(async () => {
  const v3 = await solver.recaptcha('YOUR_SITEKEY', PAGE,
    { version: 'v3', action: 'login' });
  const ent = await solver.recaptcha('YOUR_SITEKEY', PAGE,
    { enterprise: 1, invisible: 1 });
  console.log(v3.code.slice(0, 20), ent.code.slice(0, 20));
})();

Оба SDK также отклоняют смешанные запросы ещё до отправки. Action в задании v2 и флаг invisible в задании v3 вызывают исключение валидации, и это дешевле, чем узнавать об ошибке по неудачной отправке формы.

# pip install capskip
from capskip import CapSkip, ValidationException

solver = CapSkip(host="127.0.0.1", port=8080)
PAGE = "https://example.com/page-with-recaptcha"

try:
    # An action only exists on v3, so this v2 task is refused locally.
    solver.recaptcha(sitekey="YOUR_SITEKEY", url=PAGE, action="login")
except ValidationException as err:
    print("refused:", err)

Я запускал эти блоки против имитации in.php и res.php, а не настоящего приложения, на Python 3.11.7, 3.13.7 и 3.14.0 и на Node.js 24.22.0, везде с capskip 1.7.0. Имитация записывала поля, отправленные каждым вызовом, и они совпали с таблицей: каждый вызов нёс метод, sitekey и адрес страницы, а также явное значение enterprise, 0 или 1, которое подставляет SDK, а остальные варианты добавляли ровно перечисленные флаги. Это доказывает форму запроса, а не решение.

Что проверяет сервер для каждого варианта

Различия на принимающей стороне и делают флаги необходимыми. В этой таблице сравнивается только то, что видит бэкенд сайта.

ВариантОткуда берётся токенПроверка на бэкендеКакие поля можно прочитать
v2 checkboxВиджет, отправленный как g-recaptcha-responseКлассическая проверкаSuccess, время challenge, hostname
v2 invisibleВызов execute или привязанная кнопка, результат передаётся в callbackКлассическая проверкаSuccess, время challenge, hostname
v3Вызов execute с указанием actionКлассическая проверкаДобавляет score и action
Enterprise, ключ на основе оценкиВызов enterprise executeОценка (assessment) на бэкендеВалидность токена, action, оценка риска
Enterprise, ключ-флажокВиджет, отрисованный из скрипта enterpriseОценка (assessment) на бэкендеВалидность токена, оценка риска

У всех них одно правило: токен действителен две минуты и проверяется один раз. В руководстве Google по проверке это сказано для классической конечной точки, а руководство по оценке повторяет это для Enterprise, поэтому руководство по сроку жизни токена важно для каждой строки. Кроме того, Документация по v3 от Google добавляет, что сайт должен сверять возвращённый action с ожидаемым, а руководство по оценке говорит, что оценки относятся к бэкенду.

О Enterprise и v3: Google описывает два вида ключей Enterprise. Ключи на основе оценки вызывают функцию enterprise execute, как v3. Ключи-флажки отрисовывают виджет из скрипта enterprise, как v2, и эту функцию не вызывают. Поэтому Enterprise задаётся флагом в запросе, а не отдельной третьей версией.

Оценка принадлежит Google, а не является опцией CapSkip

Google оценивает визит v3 от 0,0 (скорее всего бот) до 1,0 (скорее всего нормальное взаимодействие) и предлагает 0,5 как порог по умолчанию. В CapSkip нет настройки, которая запрашивает оценку, поэтому ничто в вашем коде распознавания не может обещать конкретное число. Вы управляете тем, какой action передаёте и когда запрашиваете.

Как считать значения со страницы

Sitekey находится в атрибуте data-sitekey или в параметре k адреса фрейма виджета. Для v3 и ключей Enterprise на основе оценки action это строка в вызове execute на странице. Enterprise выдаёт себя скриптом enterprise и вызовами объекта enterprise. Подробнее о каждом варианте в руководствах:

Вызов с другой машины

CapSkip является приложением для Windows, а примеры выше обращаются к нему по 127.0.0.1. Если ваши скрипты запускаются в другом месте, переключите CapSkip в Server mode и укажите в настройке host этот ПК с Windows. Руководство по установке описывает переключение в разделе Настройки подключения и рекомендует статический публичный IP для стабильного удалённого доступа. Server mode оставляет порт доступным с любого адреса, потому что CapSkip добавляет для него разрешающее правило при каждом запуске. Чтобы ограничить вызывающих, добавьте блокирующее правило Windows Firewall для адресов, которым вы не доверяете.

FAQ

Что сложнее автоматизировать: reCAPTCHA v2 или v3?

Ни для одной не нужны другие инструменты: обе сводятся к одному заданию с разными флагами. Практическая разница в том, что у v3 нет виджета, за которым можно наблюдать. Вы находите action в скрипте страницы, а результат зависит от оценки Google, которую вы задать не можете.

Показывает ли v3 когда-нибудь задачу?

Нет, по словам Google, v3 никогда не прерывает пользователей. Сайту, которому нужен видимый шаг после низкой оценки, придётся создать его самому.

Enterprise относится к v2 или к v3?

К любой. Enterprise является уровнем продукта, поэтому стиль определяет страница. В CapSkip вы добавляете флаг enterprise к заданию v2 или v3, и больше ничего в запросе не меняется.

Можно ли выбрать оценку, которую получит CapSkip?

Нет. В CapSkip нет для этого настройки. Передайте правильный action, запрашивайте токен прямо перед запросом, который его использует, и читайте результат на сайте.

Какой из них вы решаете?

Сначала посмотрите на страницу: флажок или невидимый триггер означают v2, вызов execute с action означает v3, а скрипт enterprise означает флаг для любого из них. Затем найдите строку в таблице запросов. CapSkip работает на вашем ПК с Windows, а значит, перед вами безлимитный сервис распознавания капчи, поэтому запрос свежего токена для каждого варианта или повторный запрос после истечения срока не увеличивает счёт.