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

Вопрос 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 checkbox | googlekey, pageurl | recaptcha(sitekey, url) | recaptcha(sitekey, url) |
| v2 invisible | добавляет invisible=1 | добавляет invisible=1 | options с invisible, равным 1 |
| v3 | добавляет version=v3 и action | version="v3", action="login" | options с version, равным v3, и action |
| Enterprise v2 | добавляет enterprise=1 | добавляет enterprise=1 | options с 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 namedSDK для 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. Подробнее о каждом варианте в руководствах:
- Распознавание reCAPTCHA v2, для флажка, невидимой формы и виджетов с callback
- Распознавание reCAPTCHA v3, для страниц с оценкой
- Распознавание reCAPTCHA 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, а значит, перед вами безлимитный сервис распознавания капчи, поэтому запрос свежего токена для каждого варианта или повторный запрос после истечения срока не увеличивает счёт.
