Ключ корпоративного сайта reCAPTCHA против ключа API: Руководство по настройке

Короткий ответ: в задачу для CaptchaAI идёт sitekey — публичный ключ вида 6L..., который лежит прямо в HTML страницы. Ключ Google Cloud API (AIzaSy...) отправлять не нужно вообще: он живёт на бэкенде защищаемого сайта и к генерации токена отношения не имеет.

Путаница между ними — самая частая причина того, что интеграция с reCAPTCHA Enterprise не заводится с первой попытки.

Какой ключ нужен CaptchaAI: короткая таблица

В googlekey всегда идёт публичный 6L.... Ключ AIzaSy... — это секрет чужого бэкенда, и в запросе к решателю ему делать нечего.

Правило простое: ключ, видимый в исходном коде страницы, — это sitekey. Ключ, который пришлось доставать из переменных окружения, к решению CAPTCHA отношения не имеет.

sitekey: публичный ключ виджета

sitekey встроен в HTML и определяет, какую конфигурацию reCAPTCHA загрузить:

<script src="https://www.google.com/recaptcha/enterprise.js?render=6LcR_RsTAAAAADge..."></script>

Или в вызове grecaptcha.enterprise.execute:

grecaptcha.enterprise.execute('6LcR_RsTAAAAADge...', { action: 'login' });

Характеристики:

• Начинается с 6L — тот же префикс, что и у обычной reCAPTCHA
• Виден в исходном коде страницы намеренно
• Привязан к конкретным доменам в Google Cloud Console
• Именно его принимает CaptchaAI

API-ключ: приватный ключ проверки

API-ключ аутентифицирует связку «бэкенд сайта — Google» при проверке уже полученного токена:

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=AIzaSy...

Характеристики:

• Начинается с AIzaSy — стандартный формат ключа Google Cloud API
• Никогда не попадает в клиентский код
• Используется только серверной частью сайта
• CaptchaAI он не нужен

Практическое следствие: ротация ключа Google Cloud на бэкенде не ломает вашу автоматизацию — sitekey при этом не меняется.

Где в этом потоке находится CaptchaAI

1. Браузер загружает enterprise.js, используя ключ сайта
2. Браузер проходит проверку и получает токен
3. Бэкенд сайта отправляет токен и API-ключ в конечную точку Google assessments
4. Google возвращает оценку риска и детали анализа
5. Бэкенд сайта решает по этой оценке, принимать ли запрос

CaptchaAI закрывает шаги 1–2: генерирует валидный токен по sitekey. Проверку токена бэкенд сайта делает своим API-ключом — здесь CaptchaAI уже не участвует.

Чем Enterprise отличается от бесплатной reCAPTCHA

• Источник ключа сайта: обычная версия — консоль администратора reCAPTCHA, Enterprise — Google Cloud Console
• Конечная точка проверки: siteverify против assessments
• Авторизация проверки: общий секретный ключ против API-ключа или сервисного аккаунта
• Оценка в ответе: поле score (0,0–1,0) против riskAnalysis.score с причинами
• Тип задачи CaptchaAI: RecaptchaV2Task / RecaptchaV3Task против RecaptchaV2EnterpriseTask / RecaptchaV3EnterpriseTask

Отличить типы проще всего по адресу скрипта: Enterprise подгружается с /recaptcha/enterprise.js, обычная версия — с /recaptcha/api.js.

Как достать sitekey со страницы

Способ 1: поиск по исходному коду

Найдите в HTML-коде enterprise.js:

View Source → Ctrl+F → "enterprise.js"

Параметр render содержит нужный ключ:

<script src="https://www.google.com/recaptcha/enterprise.js?render=6LcR_RsTAAAAADge..."></script>

Способ 2: консоль JavaScript

Запустите в консоли браузера:

// Check for Enterprise grecaptcha
if (window.grecaptcha && window.grecaptcha.enterprise) {
  console.log('reCAPTCHA Enterprise detected');
}

// Find site key from rendered widgets
document.querySelectorAll('[data-sitekey]').forEach(el => {
  console.log('Site key:', el.getAttribute('data-sitekey'));
});

Способ 3: вкладка «Сеть»

Откройте DevTools и отфильтруйте запросы:

• по enterprise.js — ключ будет в параметре render
• по recaptcha/enterprise — ключ виден в URL запроса или в полезной нагрузке

Отправка задачи в CaptchaAI

Ключ найден — отправляйте задачу:

POST https://ocr.captchaai.com/in.php

Обязательный набор параметров:

• key — ваш API-ключ CaptchaAI (YOUR_API_KEY)
• method — userrecaptcha
• googlekey — sitekey со страницы (6LcR_Rs...)
• pageurl — полный URL страницы, где показывается CAPTCHA
• enterprise — 1, признак Enterprise-задачи

Дополнительно для Enterprise передаются enterprise_type (версия — v2 или v3) и action — имя действия, если речь о v3 Enterprise.

Результат забирается опросом res.php и приходит в поле g-recaptcha-response. Тарификация от типа CAPTCHA не зависит: планы считаются по потокам — BASIC ($15/мес, 5 потоков), ADVANCE ($90/мес, 50 потоков).

Поиск неисправностей

Большая часть обращений в поддержку по Enterprise сводится к пяти ситуациям ниже.

Сценарий: QA-стенд платёжной формы

Команда в Алматы держит staging-копию продукта: на форме оплаты стоит reCAPTCHA Enterprise v3 с действием checkout, автотесты падают. Инженер копирует из конфигурации бэкенда ключ AIzaSy... и отправляет его в googlekey — задача уходит, но токен не принимается.

Правильный порядок: открыть staging-страницу, вытащить 6L... из параметра render, передать его с enterprise=1 и enterprise_type=v3, а в action указать то действие, что настроено в форме, — checkout, а не login. И помните: sitekey на staging и в проде разные, потому что привязаны к разным доменам.

Если на стенде используются реальные пользовательские данные, заранее решите, какие поля вы вправе хранить в логах: требования 152-ФЗ «О персональных данных» и GDPR к тестовым контурам применяются так же, как к продовым.

Частые вопросы

Можно ли использовать один API-ключ CaptchaAI для обычной reCAPTCHA и для Enterprise?

Да. Один ключ аккаунта работает со всеми поддерживаемыми типами CAPTCHA. Разница только в параметрах: для Enterprise добавляется enterprise=1.

Что делать, если sitekey на странице не находится?

Скорее всего, виджет подгружается динамически. Откройте вкладку «Сеть», отфильтруйте запросы по recaptcha/enterprise и посмотрите параметр render в URL — там ключ есть всегда.

Нужно ли передавать action для Enterprise v2?

Нет. action относится к v3, где оценка риска считается для конкретного действия. Для v2 Enterprise достаточно sitekey, pageurl и флага enterprise=1.

Сколько потоков нужно под поток задач Enterprise?

Считайте по одновременным задачам, а не по их числу за день: один поток — одна задача в моменте. Для прогонов автотестов хватает младших планов, для параллельного парсинга берите тариф от 50 потоков.

Влияет ли ротация ключа Google Cloud на стороне сайта на решение задач?

Нет. Он участвует только в серверной проверке токена между бэкендом сайта и Google.

Следующие шаги

• быстрый старт CaptchaAI: первый решённый токен за пять минут
• как решить reCAPTCHA v2 через API
• решение Cloudflare Turnstile через API
• работа с GeeTest v3 через API