Aprofundamento da API de avaliação empresarial reCAPTCHA

reCAPTCHA Enterprise é o serviço CAPTCHA premium do Google que estende o reCAPTCHA v3 com análise de risco detalhada, motivos de pontuação, sinais de detecção de fraude e recursos de defesa de conta. Ao contrário da versão gratuita padrão que retorna apenas pontuação e ação, o Enterprise fornece avaliações explicáveis ​​com fatores de risco específicos. Este guia aborda a arquitetura da API de avaliação empresarial, a estrutura de resposta e como lidar com sites protegidos pela empresa em automação.

ReCAPTCHA empresarial vs padrão

Fluxo da API de avaliação empresarial

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)

Integração do lado do cliente

SDK JavaScript

<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>

Principais diferenças do padrão reCAPTCHA v3:

• URL do script usa .../recaptcha/enterprise.js em vez de .../recaptcha/api.js
• O objeto API é grecaptcha.enterprise em vez de grecaptcha
• execute() retorna o mesmo formato de token

Detecção na origem da página

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://staging.example.com/qa-login"))

API de avaliação do lado do servidor

Como criar uma avaliação (API Google Cloud)

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

Estrutura de resposta de avaliação

{
    "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"]
    }
}

Razões de pontuação empresarial

A empresa fornece motivos específicos que explicam por que uma pontuação é baixa:

Razões estendidas do veredicto (detalhes adicionais)

Defensor da conta

O Account Defender da Enterprise rastreia contas de usuários em todo o seu ciclo de vida:

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

Integração WAF

O reCAPTCHA Enterprise integra-se com provedores WAF para adicionar desafios CAPTCHA na borda da rede:

Integração WAF da Cloudflare

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

Integração 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

Lidando com o Enterprise reCAPTCHA na automação

CaptchaAI resolve Enterprise da mesma forma que o reCAPTCHA padrão

Do ponto de vista do solucionador de API, os tokens reCAPTCHA Enterprise funcionam de forma idêntica aos tokens reCAPTCHA padrão:

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");
}

Como detectar Enterprise vs Standard em uma página de destino

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"

Solução de problemas empresariais

Perguntas frequentes

O reCAPTCHA Enterprise é mais difícil de resolver do que o reCAPTCHA padrão?

O processo de geração de token é o mesmo. A empresa adiciona recursos de análise do lado do servidor (motivos de pontuação, Account Defender), mas o desafio do lado do cliente é idêntico. Os solucionadores de API geram tokens para o Enterprise da mesma forma que fazem para as versões padrão.

Preciso de uma conta do Google Cloud para resolver CAPTCHAs empresariais?

Não. Como desenvolvedor de automação que resolve CAPTCHAs empresariais em sites de destino, você só precisa do sitekey da página e de um solucionador de API como CaptchaAI. A conta do Google Cloud é necessária ao operador do site para validar as avaliações, não ao solucionador CAPTCHA.

Como posso saber se um site usa o Enterprise ou o reCAPTCHA padrão?

Verifique o URL do script. A empresa usa recaptcha/enterprise.js enquanto o padrão usa recaptcha/api.js. O nome do objeto da API JavaScript também é diferente: grecaptcha.enterprise.execute() vs grecaptcha.execute().

Os motivos da pontuação empresarial podem ser usados para aprimorar minha automação?

Se você opera o site de destino (testando sua própria implementação de CAPTCHA), sim – os motivos informam quais sinais de detecção foram acionados. Se você estiver resolvendo CAPTCHAs em sites de terceiros, os motivos não serão visíveis para você – apenas o operador do site os verá.

Resumo

O reCAPTCHA Enterprise estende o reCAPTCHA padrão com análise de risco detalhada, motivos de pontuação, Account Defender e integração WAF. Do ponto de vista da automação, os Enterprise CAPTCHAs são resolvidos de forma idêntica ao reCAPTCHA padrão — adicione o parâmetro enterprise=1 ao seuCaptchaAISolicitação de API. Detecte o Enterprise verificando recaptcha/enterprise.js na origem da página. A principal diferença operacional é garantir que você passe o sinalizador enterprise correto e o parâmetro action correspondente.

Artigos relacionados

• Como resolver o retorno de chamada do Recaptcha V2 usando API
• Torniquete Recaptcha V2 no mesmo local
• Como resolver Recaptcha V3 Enterprise usando API