Análisis profundo de la API de evaluación empresarial reCAPTCHA

reCAPTCHA Enterprise es el servicio CAPTCHA premium de Google que amplía reCAPTCHA v3 con análisis de riesgos detallados, motivos de puntuación, señales de detección de fraude y capacidades de defensa de cuentas. A diferencia de la versión gratuita estándar que solo devuelve una puntuación y una acción, Enterprise proporciona evaluaciones explicables con factores de riesgo específicos. Esta guía cubre la arquitectura de la API de Enterprise Assessment, la estructura de respuesta y cómo manejar los sitios protegidos por Enterprise en la automatización.

ReCAPTCHA empresarial versus estándar

Flujo de API de evaluación 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)

Integración del 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>

Diferencias clave con respecto al estándar reCAPTCHA v3:

• La URL del script usa .../recaptcha/enterprise.js en lugar de .../recaptcha/api.js
• El objeto API es grecaptcha.enterprise en lugar de grecaptcha
• execute() devuelve el mismo formato de token

Detección en la fuente de la 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 evaluación del lado del servidor

Crear una evaluación (API de 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

Estructura de respuesta de evaluación

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

Razones de la puntuación empresarial

Enterprise proporciona razones específicas que explican por qué una puntuación es baja:

Motivos del veredicto ampliado (detalle adicional)

Defensor de cuenta

Account Defender de Enterprise rastrea las cuentas de usuario a lo largo de su ciclo de vida:

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

Integración WAF

reCAPTCHA Enterprise se integra con proveedores WAF para agregar desafíos CAPTCHA en el borde de la red:

Integración 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

Integración 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

Manejo de Enterprise reCAPTCHA en la automatización

CaptchaAI resuelve Enterprise de la misma manera que el reCAPTCHA estándar

Desde la perspectiva del solucionador de API, los tokens reCAPTCHA Enterprise funcionan de manera idéntica a los tokens 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

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

Cómo detectar Enterprise vs Standard en una 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"

Solución de problemas empresariales

Preguntas frecuentes

¿Es reCAPTCHA Enterprise más difícil de resolver que el reCAPTCHA estándar?

El proceso de generación de tokens es el mismo. Enterprise agrega funciones de análisis del lado del servidor (motivos de puntuación, Account Defender), pero el desafío del lado del cliente es idéntico. Los solucionadores de API generan tokens para Enterprise de la misma manera que lo hacen para las versiones estándar.

¿Necesito una cuenta de Google Cloud para resolver CAPTCHA empresariales?

No. Como desarrollador de automatización que resuelve CAPTCHA empresariales en sitios web de destino, solo necesita el sitekey de la página y un solucionador de API como CaptchaAI. La cuenta de Google Cloud la necesita el operador del sitio web para validar las evaluaciones, no el solucionador de CAPTCHA.

¿Cómo puedo saber si un sitio utiliza reCAPTCHA empresarial o estándar?

Verifique la URL del script. Enterprise usa recaptcha/enterprise.js mientras que estándar usa recaptcha/api.js. El nombre del objeto de la API de JavaScript también difiere: grecaptcha.enterprise.execute() frente a grecaptcha.execute().

¿Se pueden utilizar los motivos de puntuación empresarial para mejorar mi automatización?

Si opera el sitio de destino (probando su propia implementación de CAPTCHA), sí, los motivos le indican qué señales de detección se activaron. Si está resolviendo CAPTCHA en sitios de terceros, los motivos no son visibles para usted; solo el operador del sitio los ve.

Resumen

reCAPTCHA Enterprise amplía el reCAPTCHA estándar con análisis de riesgos detallados, motivos de puntuación, Account Defender e integración WAF. Desde una perspectiva de automatización, los CAPTCHA empresariales se resuelven de manera idéntica al reCAPTCHA estándar: agregue el parámetro enterprise=1 a suCaptchaAISolicitud de API. Detecte Enterprise buscando recaptcha/enterprise.js en la fuente de la página. La diferencia operativa clave es garantizar que se pasa el indicador enterprise correcto y el parámetro action correspondiente.

Artículos relacionados

• Cómo resolver la devolución de llamada de Recaptcha V2 usando Api
• Torniquete Recaptcha V2 Manejo en el mismo sitio
• Cómo resolver Recaptcha V3 Enterprise usando Api