Errores comunes de reCAPTCHA v2 Enterprise y cómo solucionarlos

reCAPTCHA v2 Enterprise falla por las mismas razones que el estándar v2 (clave de sitio incorrecta, URL de página incorrecta, tokens vencidos) además de algunos problemas específicos de la empresa. El mayor problema de Enterprise es identificar erróneamente la implementación: usar parámetros estándar v2 en un widget de Enterprise, o viceversa. Si envía method=userrecaptcha sin el indicador enterprise=1 para un widget empresarial, el backend del sitio de destino rechazará el token devuelto.

Esta guía cubre todas las fallas comunes al resolver reCAPTCHA v2 Enterprise a través de la API CaptchaAI. Si no estás seguro de si se trata del estándar o Enterprise, lee Cómo identificar la implementación de reCAPTCHA Enterprise primero.

En qué se diferencia reCAPTCHA v2 Enterprise del estándar

Errores específicos de la empresa

Envío de parámetros estándar para un widget empresarial

Síntoma: La API devuelve un token, pero el sitio de destino lo rechaza.

Causa: Enviaste la tarea sin enterprise=1. CaptchaAI lo resolvió como estándar v2, pero el backend lo verifica con la API empresarial, que rechaza los tokens estándar.

Solución: Agregue enterprise=1 a su solicitud:

import requests

response = requests.get("https://ocr.captchaai.com/in.php", params={
    "key": "YOUR_API_KEY",
    "method": "userrecaptcha",
    "googlekey": "6LcR_RsTAAAAAFJR-JhNbC6CC42wKCbR9Hq_kVCd",
    "pageurl": "https://staging.example.com/qa-login",
    "enterprise": 1,
    "json": 1
})

data = response.json()
task_id = data["request"]

const params = new URLSearchParams({
  key: "YOUR_API_KEY",
  method: "userrecaptcha",
  googlekey: "6LcR_RsTAAAAAFJR-JhNbC6CC42wKCbR9Hq_kVCd",
  pageurl: "https://staging.example.com/qa-login",
  enterprise: 1,
  json: 1,
});

const res = await fetch(`https://ocr.captchaai.com/in.php?${params}`);
const data = await res.json();
const taskId = data.request;

Parámetro de datos faltante

Síntoma: ERROR_BAD_PARAMETERS o el sitio rechaza el token.

Causa: Algunas implementaciones empresariales incluyen un atributo data-s en el div reCAPTCHA. Este es un token de sesión adicional necesario para resolver. Si está presente, debes incluirlo.

Solución: Consulte la página de data-s e inclúyala si la encuentra:

# Look for: <div class="g-recaptcha" data-sitekey="..." data-s="..."></div>
response = requests.get("https://ocr.captchaai.com/in.php", params={
    "key": "YOUR_API_KEY",
    "method": "userrecaptcha",
    "googlekey": sitekey,
    "pageurl": page_url,
    "enterprise": 1,
    "data-s": data_s_value,  # Include if present on the page
    "json": 1
})

Identificación de script incorrecta

Síntoma: El token funciona de manera inconsistente o siempre se rechaza.

Causa: Identificaste el widget como estándar cuando es Enterprise (o viceversa).

Solución: Verifique la fuente del script en la página HTML:

// Enterprise uses enterprise.js
// <script src="https://www.google.com/recaptcha/enterprise.js?render=SITEKEY"></script>

// Standard uses api.js
// <script src="https://www.google.com/recaptcha/api.js"></script>

// Also check the JS object:
// Enterprise: grecaptcha.enterprise.render(...)
// Standard: grecaptcha.render(...)

Errores generales (compartidos con el estándar v2)

Flujo de resolución completo con manejo de errores

import requests
import time

def solve_recaptcha_v2_enterprise(api_key, sitekey, page_url, data_s=None):
    params = {
        "key": api_key,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": page_url,
        "enterprise": 1,
        "json": 1
    }
    if data_s:
        params["data-s"] = data_s

    response = requests.get("https://ocr.captchaai.com/in.php", params=params)
    data = response.json()

    if data.get("status") != 1:
        raise RuntimeError(f"Submit failed: {data.get('request')}")

    task_id = data["request"]

    for _ in range(40):
        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:
            return result["request"]
        if result.get("request") == "CAPCHA_NOT_READY":
            continue
        raise RuntimeError(f"Solve failed: {result.get('request')}")

    raise TimeoutError("Solve timed out after 200 seconds")

token = solve_recaptcha_v2_enterprise("YOUR_API_KEY", "SITEKEY", "https://staging.example.com/qa-login")

async function solveRecaptchaV2Enterprise(apiKey, sitekey, pageUrl, dataS) {
  const params = new URLSearchParams({
    key: apiKey, method: "userrecaptcha", googlekey: sitekey,
    pageurl: pageUrl, enterprise: 1, json: 1,
  });
  if (dataS) params.set("data-s", dataS);

  const submitRes = await fetch(`https://ocr.captchaai.com/in.php?${params}`);
  const submitData = await submitRes.json();
  if (submitData.status !== 1) throw new Error(`Submit failed: ${submitData.request}`);

  const taskId = submitData.request;
  for (let i = 0; i < 40; i++) {
    await new Promise(r => setTimeout(r, 5000));
    const res = await fetch(`https://ocr.captchaai.com/res.php?${new URLSearchParams({
      key: apiKey, action: "get", id: taskId, json: 1,
    })}`);
    const data = await res.json();
    if (data.status === 1) return data.request;
    if (data.request === "CAPCHA_NOT_READY") continue;
    throw new Error(`Solve failed: ${data.request}`);
  }
  throw new Error("Timed out after 200s");
}

Preguntas frecuentes

¿Cómo sé si un sitio utiliza reCAPTCHA Enterprise o estándar?

Verifique la etiqueta del script en el HTML. Enterprise carga recaptcha/enterprise.js mientras que estándar carga recaptcha/api.js. El objeto JavaScript también es diferente: Enterprise usa grecaptcha.enterprise mientras que estándar usa grecaptcha.

¿Necesito cambiar mi llamada API para Enterprise?

Sí. Agregue enterprise=1 a su solicitud CaptchaAI. Sin este indicador, el token se genera para el estándar v2, que los backends empresariales rechazan.

¿Qué es el parámetro data-s?

Algunas implementaciones empresariales incluyen un atributo data-s en el div reCAPTCHA. Este es un token de sesión adicional. Si está presente en la página, inclúyalo en su solicitud de API.

¿Por qué se rechaza mi token Enterprise incluso con empresa=1?

Verifique tres cosas: (1) la clave del sitio es correcta, (2) el parámetro data-s está presente en la página pero falta en su solicitud, o (3) el token expiró antes de enviar el formulario.

¿Puedo usar el mismo código para estándar y Enterprise v2?

Sí, agregue enterprise=1 para cambiar. Todo lo demás (nombre del método, parámetros, sondeo) permanece igual.

Optimiza tu workflow Enterprise

1. Verifica el tipo de implementación: busca enterprise.js en la etiqueta del script
2. Agrega enterprise=1 a tu solicitud CaptchaAI
3. Comprueba data-s: inclúydelo si la página tiene este atributo.
4. Envía el token de inmediato: los tokens Enterprise también caducan después de aproximadamente 2 minutos.

Obtén tu clave API en captchaai.com/api.php.

Guías relacionadas

• Cómo identificar la implementación de reCAPTCHA Enterprise
• Cómo resolver reCAPTCHA v2 usando la API
• reCAPTCHA v2 estándar vs. Enterprise
• Referencia de códigos de error CaptchaAI