reCAPTCHA Enterprise Assessment API: guía para automatización

Si tu scraper o tu suite de QA se topa con un sitio protegido por reCAPTCHA Enterprise, la respuesta corta es tranquilizadora: el token se genera casi igual que en reCAPTCHA v3 y basta con indicar la variante Enterprise en la solicitud al solver. La diferencia real está en lo que Google evalúa del lado del servidor, donde la Assessment API devuelve una puntuación con score reasons explicables, señales de fraude y etiquetas de Account Defender.

Esa capa de evaluación es la que explica por qué un sitio bloquea tu automatización aunque el CAPTCHA se resuelva. En esta guía vas a encontrar:

• Qué añade Enterprise sobre reCAPTCHA v3 y cómo se factura.
• Cómo leer la respuesta de la Assessment API: score, motivos y Account Defender.
• Cómo resolver tokens Enterprise en producción con CaptchaAI.

Cómo funciona el flujo de la Assessment API

El flujo tiene dos mitades: el navegador genera un token y tu backend lo canjea por una evaluación completa.

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)

El token que viaja al backend es idéntico al de v3; lo nuevo es que Enterprise permite consultar el veredicto detallado antes de dejar pasar la solicitud.

reCAPTCHA Enterprise frente a la versión estándar

Esta tabla resume qué gana el operador del sitio al pasar de v3 a Enterprise:

v3 solo te dice cuánto confía en la sesión; Enterprise te dice además por qué.

Integración en el lado del cliente

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

Frente al v3 estándar cambian tres cosas: la URL del script es .../recaptcha/enterprise.js en vez de .../recaptcha/api.js, el objeto de la API es grecaptcha.enterprise en vez de grecaptcha, y execute() devuelve el token en el mismo formato.

Cómo detectar Enterprise en el código de la página

Antes de resolver conviene saber qué variante corre. Inspecciona el HTML en busca del script de Enterprise y extrae el sitekey:

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

Assessment API en el lado del servidor

Crear una evaluación con la API de Google Cloud

Este paso lo ejecuta el operador del sitio, no quien resuelve el CAPTCHA, pero aclara qué maneja el servidor al canjear tu token:

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

Estructura de la respuesta de evaluación

La respuesta reúne la puntuación, los motivos, las propiedades del token y el veredicto de Account Defender:

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

Score reasons: por qué baja la puntuación

El valor real de Enterprise: en vez de un número opaco, entrega motivos concretos que explican una puntuación baja.

Extended verdict reasons (detalle adicional)

Account Defender

Account Defender sigue a cada cuenta durante su ciclo de vida y devuelve etiquetas de riesgo:

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

Integración con WAF

reCAPTCHA Enterprise se conecta con proveedores de WAF para lanzar desafíos CAPTCHA en el borde de la red, antes de que la solicitud llegue al origen. Los más habituales son:

• Cloudflare, mediante reglas de WAF.
• F5 BIG-IP, con iRules o políticas.
• Fastly, en su capa de edge.

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

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

Cómo resolver reCAPTCHA Enterprise en tu automatización

Desde el punto de vista del solver, los tokens Enterprise funcionan igual que los estándar. Solo necesitas tres datos:

• El sitekey de la página, que sacas del HTML.
• El indicador enterprise=1, que activa la variante Enterprise.
• La action correcta, la misma que dispara el formulario o el login.

Por ejemplo, un equipo de QA en Ciudad de México que valida su propio login en staging solo tiene que enviar el sitekey y la pageurl de su página de pruebas, marcar enterprise=1 y recibir un token con el que comprobar su capa de verificación. El patrón sirve para cualquier flujo autorizado.

CaptchaAI resuelve Enterprise igual que el reCAPTCHA estándar

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

Detectar Enterprise o estándar en la página objetivo

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"

Solución de problemas con Enterprise

Preguntas frecuentes

¿CaptchaAI puede resolver reCAPTCHA Enterprise?

Sí. Se resuelve con el mismo método userrecaptcha que las variantes estándar; la única diferencia operativa es pasar enterprise=1 en la solicitud.

¿Hace falta una cuenta de Google Cloud para resolver Enterprise en sitios de terceros?

No. Solo necesitas el sitekey de la página y un solver como CaptchaAI. La cuenta de Google Cloud la usa el operador del sitio para validar las evaluaciones, no quien resuelve el CAPTCHA.

¿Qué hago si la puntuación sale baja aunque el token sea válido?

Empieza por el parámetro action: si no coincide con el que dispara la página, Enterprise suele devolver un score muy bajo. Revisa también que la pageurl sea exacta y que no aparezca un SITE_MISMATCH en los motivos.

¿El parámetro enterprise=1 es siempre obligatorio?

Solo cuando el sitio carga recaptcha/enterprise.js. Si detectas esa URL en el HTML, marca la variante Enterprise; si el sitio usa recaptcha/api.js, se trata de reCAPTCHA v3 estándar y no debes añadir el indicador.

Resumen

reCAPTCHA Enterprise amplía la versión estándar con análisis de riesgo detallado, score reasons explicables, Account Defender e integración con WAF. Desde la automatización, en cambio, se resuelve igual que el reCAPTCHA de siempre. Lo que conviene recordar:

• Añade enterprise=1 a tu solicitud a la API de CaptchaAI.
• Detecta la variante buscando recaptcha/enterprise.js en la página.
• Pasa la action que dispara el formulario o el login.

Los motivos de puntuación y las etiquetas de cuenta viven en el servidor de quien opera el sitio, no en tu solver.

Artículos relacionados

• Cómo resolver el callback de reCAPTCHA v2 con la API
• Manejar reCAPTCHA v2 y Turnstile en un mismo sitio
• Cómo resolver reCAPTCHA v3 Enterprise con la API