Подробное описание API оценки предприятия reCAPTCHA

reCAPTCHA Enterprise — это премиальная служба CAPTCHA от Google, которая расширяет reCAPTCHA v3 детальным анализом рисков, причинами оценки, сигналами обнаружения мошенничества и возможностями защиты учетной записи. В отличие от стандартной бесплатной версии, которая возвращает только оценку и действие, Enterprise предоставляет объяснимые оценки с учетом конкретных факторов риска. В этом руководстве описывается архитектура API оценки предприятия, структура ответов и способы автоматизации работы с сайтами, защищенными предприятием.

Корпоративная и стандартная reCAPTCHA

Схема работы API оценки предприятия

Client-side:

  1. Load reCAPTCHA Enterprise script
  2. Call grecaptcha.enterprise.execute(SITE_KEY, {action: 'LOGIN'})
  3. Receive token
  4. Send token to your backend

Server-side:

  1. Create assessment via Enterprise API
  2. Receive detailed risk analysis
  3. Make access decision based on score + reasons
  4. Optionally annotate the assessment (report fraud/legitimate)

Интеграция на стороне клиента

JavaScript SDK

<script src="https://www.google.com/recaptcha/enterprise.js?render=SITE_KEY"></script>
<script>
    grecaptcha.enterprise.ready(function() {
        grecaptcha.enterprise.execute('SITE_KEY', { action: 'LOGIN' })
            .then(function(token) {
                // Send token to backend
                fetch('/api/verify', {
                    method: 'POST',
                    headers: { 'Content-Type': 'application/json' },
                    body: JSON.stringify({ token: token })
                });
            });
    });
</script>

Ключевые отличия от стандартного reCAPTCHA v3:

• В URL-адресе сценария используется .../recaptcha/enterprise.js вместо .../recaptcha/api.js.
• Объект API — grecaptcha.enterprise вместо grecaptcha.
• execute() возвращает тот же формат токена.

Обнаружение в источнике страницы

import requests
import re

def detect_recaptcha_enterprise(url):
    """Detect if a page uses reCAPTCHA Enterprise."""
    html = requests.get(url, timeout=10).text

    indicators = {
        "is_enterprise": False,
        "is_standard": False,
        "site_key": None,
        "actions": [],
    }

    # Enterprise detection
    if "recaptcha/enterprise.js" in html:
        indicators["is_enterprise"] = True
        match = re.search(r"render=([A-Za-z0-9_-]+)", html)
        if match:
            indicators["site_key"] = match.group(1)

    # Standard v3 detection
    elif "recaptcha/api.js?render=" in html:
        indicators["is_standard"] = True
        match = re.search(r"render=([A-Za-z0-9_-]+)", html)
        if match:
            indicators["site_key"] = match.group(1)

    # Extract action names
    actions = re.findall(r"action:\s*['\"](\w+)['\"]", html)
    indicators["actions"] = list(set(actions))

    return indicators

print(detect_recaptcha_enterprise("https://https://staging.example.com/qa-login"))

API оценки на стороне сервера

Создание оценки (Google Cloud API)

from google.cloud import recaptchaenterprise_v1
from google.cloud.recaptchaenterprise_v1 import Assessment

def create_assessment(project_id, site_key, token, action):
    """Create a reCAPTCHA Enterprise assessment."""
    client = recaptchaenterprise_v1.RecaptchaEnterpriseServiceClient()

    event = recaptchaenterprise_v1.Event()
    event.site_key = site_key
    event.token = token
    event.expected_action = action

    assessment = recaptchaenterprise_v1.Assessment()
    assessment.event = event

    request = recaptchaenterprise_v1.CreateAssessmentRequest()
    request.assessment = assessment
    request.parent = f"projects/{project_id}"

    response = client.create_assessment(request)
    return response

Структура ответа на оценку

{
    "name": "projects/123456/assessments/abcdef123",
    "event": {
        "token": "...",
        "siteKey": "6Le...",
        "expectedAction": "LOGIN",
        "hashedAccountId": "abc123..."
    },
    "riskAnalysis": {
        "score": 0.9,
        "reasons": [
            "AUTOMATION",
            "TOO_MUCH_TRAFFIC"
        ],
        "extendedVerdictReasons": [
            "BROWSER_ERROR"
        ]
    },
    "tokenProperties": {
        "valid": true,
        "hostname": "example.com",
        "action": "LOGIN",
        "createTime": "2025-01-15T10:30:00Z",
        "invalidReason": ""
    },
    "accountDefenderAssessment": {
        "labels": ["PROFILE_MATCH"]
    }
}

Причины оценки предприятия

Компания Enterprise приводит конкретные причины, объясняющие низкую оценку:

Причины расширенного вердикта (дополнительная информация)

Защитник аккаунта

Защитник учетных записей Enterprise отслеживает учетные записи пользователей на протяжении всего их жизненного цикла:

{
    "accountDefenderAssessment": {
        "labels": [
            "PROFILE_MATCH",
            "SUSPICIOUS_LOGIN_ACTIVITY",
            "SUSPICIOUS_ACCOUNT_CREATION",
            "RELATED_ACCOUNTS_NUMBER_HIGH"
        ]
    }
}

Интеграция WAF

reCAPTCHA Enterprise интегрируется с поставщиками WAF, чтобы добавить задачи CAPTCHA на границе сети:

Интеграция Cloudflare WAF

Request arrives at Cloudflare edge
    ↓
Cloudflare WAF rule evaluates request
    ↓
Rule triggers reCAPTCHA Enterprise challenge
    ↓
Client solves CAPTCHA → token returned
    ↓
Cloudflare validates token via Enterprise API
    ↓
If valid + score above threshold → request forwarded to origin

Интеграция F5 BIG-IP

F5 iRule or policy evaluates request
    ↓
Triggers reCAPTCHA Enterprise challenge page
    ↓
Client solves → token validated server-side
    ↓
F5 forwards or blocks based on assessment score

Обработка корпоративного reCAPTCHA в автоматизации

CaptchaAI решает Enterprise так же, как и стандартная reCAPTCHA.

С точки зрения решателя API токены reCAPTCHA Enterprise работают идентично стандартным токенам reCAPTCHA:

import requests
import time

API_KEY = "YOUR_API_KEY"

# Enterprise is solved with the same method
# The solver handles the Enterprise variant automatically
submit = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": API_KEY,
    "method": "userrecaptcha",
    "googlekey": "6LcR_RsTAAAAAN_r0GEkGBfq3L7KmU5JbPHJtwNp",
    "pageurl": "https://enterprise-site.com/login",
    "enterprise": 1,  # Flag for Enterprise variant
    "json": 1,
})

task_id = submit.json()["request"]

for _ in range(60):
    time.sleep(5)
    result = requests.get("https://ocr.captchaai.com/res.php", params={
        "key": API_KEY,
        "action": "get",
        "id": task_id,
        "json": 1,
    }).json()

    if result.get("status") == 1:
        token = result["request"]
        print(f"Enterprise token: {token[:50]}...")
        break

Node.js

const axios = require("axios");

async function solveEnterprise(sitekey, pageurl) {
    const API_KEY = "YOUR_API_KEY";

    const { data: submit } = await axios.post(
        "https://ocr.captchaai.com/in.php",
        new URLSearchParams({
            key: API_KEY,
            method: "userrecaptcha",
            googlekey: sitekey,
            pageurl: pageurl,
            enterprise: 1,
            json: 1,
        })
    );

    const taskId = submit.request;

    for (let i = 0; i < 60; i++) {
        await new Promise(r => setTimeout(r, 5000));
        const { data: result } = await axios.get(
            "https://ocr.captchaai.com/res.php",
            { params: { key: API_KEY, action: "get", id: taskId, json: 1 } }
        );

        if (result.status === 1) return result.request;
    }

    throw new Error("Timeout");
}

Как определить Enterprise или Standard на целевой странице

def identify_recaptcha_version(html):
    """Determine which reCAPTCHA version a page uses."""
    if "recaptcha/enterprise.js" in html:
        return "enterprise"
    elif "recaptcha/api.js?render=" in html:
        return "v3"
    elif "g-recaptcha" in html and 'data-size="invisible"' in html:
        return "v2_invisible"
    elif "g-recaptcha" in html:
        return "v2"
    else:
        return "none"

Устранение неполадок предприятия

Часто задаваемые вопросы

Сложнее ли решить проблему reCAPTCHA Enterprise, чем стандартную reCAPTCHA?

Процесс генерации токена тот же. Enterprise добавляет функции анализа на стороне сервера (причины оценки, Защитник учетной записи), но задача на стороне клиента идентична. Решатели API генерируют токены для Enterprise так же, как и для стандартных версий.

Нужна ли мне учетная запись Google Cloud для решения корпоративных CAPTCHA?

Нет. Как разработчику средств автоматизации, решающему корпоративные CAPTCHA на целевых веб-сайтах, вам понадобится только sitekey со страницы и решатель API, такой как CaptchaAI. Учетная запись Google Cloud необходима оператору веб-сайта для проверки оценок, а не решателю CAPTCHA.

Как узнать, использует ли сайт Enterprise или стандартную reCAPTCHA?

Проверьте URL-адрес сценария. Enterprise использует recaptcha/enterprise.js, тогда как стандарт использует recaptcha/api.js. Имя объекта API JavaScript также отличается: grecaptcha.enterprise.execute() и grecaptcha.execute().

Можно ли использовать причины оценки предприятия для улучшения моей автоматизации?

Если вы управляете целевым сайтом (тестируете собственную реализацию CAPTCHA), да — причины подскажут вам, какие сигналы обнаружения сработали. Если вы решаете CAPTCHA на сторонних сайтах, причины вам не видны — их видит только оператор сайта.

Краткое содержание

reCAPTCHA Enterprise расширяет стандартную reCAPTCHA детальным анализом рисков, причинами оценки, Защитником учетных записей и интеграцией WAF. С точки зрения автоматизации корпоративные CAPTCHA решаются идентично стандартной reCAPTCHA — добавьте параметр enterprise=1 в свойCaptchaAIAPI-запрос. Обнаружьте Enterprise, проверив наличие recaptcha/enterprise.js в источнике страницы. Ключевое отличие заключается в том, что вы передаете правильный флаг enterprise и соответствующий параметр action.

Похожие статьи

• Как решить обратный вызов Recaptcha V2 с помощью API
• Cloudflare Turnstile Recaptcha V2. Обработка на той же площадке.
• Как решить Recaptcha V3 Enterprise с помощью API