reCAPTCHA Enterprise: diferencia entre sitekey y clave API

¿Te aparece ERROR_WRONG_CAPTCHA_ID al resolver un reCAPTCHA Enterprise con CaptchaAI? En la mayoría de los casos el motivo es el mismo: enviaste la clave equivocada. Enterprise maneja dos claves de aspecto parecido, y solo una sirve para resolver el desafío.

La que necesitas es el sitekey público (6L...), nunca la clave API privada (AIzaSy...) que el backend usa para verificar el token ante Google. Distinguirlas separa una integración que funciona de otra que solo devuelve errores.

Qué clave necesita CaptchaAI

En resumen:

• CaptchaAI necesita el sitekey: la clave pública 6L... del widget.
• No necesita la clave API privada AIzaSy....
• El resto se reduce a marcar la tarea con enterprise=1.

Las dos claves de reCAPTCHA Enterprise

Conviene tener claro qué hace cada clave y dónde vive.

El sitekey (público)

El sitekey va incrustado en el HTML de la página. Su función es identificar qué configuración de reCAPTCHA debe cargarse:

<script src="https://www.google.com/recaptcha/enterprise.js?render=6LcR_RsTAAAAADge..."></script>

O dentro de una llamada a grecaptcha.enterprise.execute:

grecaptcha.enterprise.execute('6LcR_RsTAAAAADge...', { action: 'login' });

• Empieza por 6L, el mismo prefijo que el reCAPTCHA estándar.
• Es visible en el código fuente de la página: público por diseño.
• Está vinculado a dominios concretos en Google Cloud Console.
• Es lo que CaptchaAI necesita para resolver el desafío.

La clave API (privada)

La clave API autentica la comunicación entre el servidor del sitio y Google al verificar el token:

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=AIzaSy...

• Empieza por AIzaSy, el formato de API key de Google Cloud.
• Nunca se expone en el código del lado del cliente.
• La usa únicamente el backend del sitio para verificar tokens.
• CaptchaAI no necesita esta clave.

El flujo de verificación, paso a paso

Ver el recorrido completo aclara por qué, para resolver, solo importa el sitekey:

1. El navegador carga enterprise.js con el sitekey.
2. El navegador ejecuta el desafío y obtiene un token.
3. El backend del sitio envía el token junto con la clave API al endpoint assessments de Google.
4. Google devuelve la puntuación de riesgo y los detalles de la evaluación.
5. El backend del sitio decide si acepta la acción según esa puntuación.

CaptchaAI cubre los pasos 1 y 2: genera un token válido a partir del sitekey. La verificación (pasos 3 a 5) la hace el sitio con su clave API, y ahí CaptchaAI no interviene.

Dónde encontrar el sitekey

Localizar el sitekey no requiere herramientas especiales; estos tres métodos van de menos a más técnico.

Método 1: buscar en el código fuente

Busca enterprise.js en el HTML:

View Source → Ctrl+F → "enterprise.js"

El parámetro render contiene el sitekey:

<script src="https://www.google.com/recaptcha/enterprise.js?render=6LcR_RsTAAAAADge..."></script>

Copia el valor tras render=: ese es el sitekey que enviarás a CaptchaAI.

Método 2: consola de JavaScript

Ejecuta esto en la consola del navegador:

// Check for Enterprise grecaptcha
if (window.grecaptcha && window.grecaptcha.enterprise) {
  console.log('reCAPTCHA Enterprise detected');
}

// Find site key from rendered widgets
document.querySelectorAll('[data-sitekey]').forEach(el => {
  console.log('Site key:', el.getAttribute('data-sitekey'));
});

Si la consola imprime un 6L..., ese es el sitekey.

Método 3: pestaña Red (Network)

Filtra las solicitudes de red por enterprise.js o recaptcha/enterprise: el sitekey aparece en la URL o en el payload de la solicitud.

Enviar el sitekey a CaptchaAI

Con el sitekey, envíalo en el parámetro googlekey a la API de CaptchaAI:

POST https://ocr.captchaai.com/in.php

Parámetros obligatorios:

Parámetros opcionales de Enterprise:

Un caso habitual: una agencia que hace QA de un portal de trámites protegido con reCAPTCHA Enterprise. El equipo extrae el sitekey de la URL real del formulario y lo envía con enterprise=1; su backend sigue verificando el token como siempre. Si por descuido pega la clave AIzaSy..., cada tarea vuelve con ERROR_WRONG_CAPTCHA_ID.

Comparación rápida de las dos claves

reCAPTCHA Enterprise frente a la versión estándar

Enterprise cambia de dónde salen las claves y cómo se verifican respecto a la versión gratuita.

Errores comunes al configurar las claves

Preguntas frecuentes

¿Cómo distingo el sitekey de la clave API a simple vista?

Por el prefijo y por dónde aparece cada clave:

• El sitekey empieza por 6L... y vive en el HTML o en las llamadas a grecaptcha.
• La clave API empieza por AIzaSy... y solo debería existir en el servidor.

Si aparece en el código fuente del navegador, es el sitekey.

¿CaptchaAI necesita mi clave API de Google Cloud?

No. CaptchaAI solo trabaja con el sitekey para generar el token. La clave API AIzaSy... se queda en tu backend para la verificación con Google; compartirla no aporta nada y es un riesgo innecesario.

¿Necesito enviar el parámetro action con reCAPTCHA Enterprise v3?

Sí, cuando el sitio use v3 Enterprise con acciones:

• Usa el mismo nombre de action que dispara el widget (por ejemplo login o checkout).
• Acompáñalo de enterprise_type=v3 para que el token coincida con lo que el backend espera verificar.

¿Afecta a mi resolución que el sitio rote su clave API de Google?

No. Esa clave solo interviene en la verificación entre el backend del sitio y Google. Rotarla no cambia la generación del token ni el proceso de resolución de CaptchaAI.

Artículos relacionados

• Resolver reCAPTCHA v2 con callback vía API
• Proteger tu API key con lista blanca de IP
• Rotación de la API key de CaptchaAI

Próximos pasos

Resuelve tus desafíos de reCAPTCHA Enterprise: obtén tu API key de CaptchaAI y envía el sitekey con la marca enterprise=1.