Verifica los tokens de respuesta del usuario con SiteVerify heredado

En esta página, se explica cómo verificar la respuesta de un usuario a un desafío de reCAPTCHA desde el backend de tu aplicación con el extremo heredado de la API de SiteVerify (https://www.google.com/recaptcha/api/siteverify). Usa este extremo solo si mantienes una integración heredada o un complemento de terceros que no puede usar CreateAssessment.

Antes de comenzar

Para llamar al extremo SiteVerify, necesitas la clave secreta heredada de tu clave. Para encontrar la clave secreta en la consola de Google Cloud , consulta Cómo recuperar la clave secreta en la consola de Google Cloud . Mantén tu clave secreta segura en tu servidor de backend y nunca la expongas en el código del cliente.

Cómo recuperar el token de respuesta del usuario

Las integraciones web heredadas cargan la API de JavaScript no empresarial (https://www.google.com/recaptcha/api.js), que proporciona métodos en el objeto grecaptcha en lugar de grecaptcha.enterprise. Puedes recuperar el token de respuesta del usuario en tu frontend de una de las siguientes maneras:

  • Del parámetro POST g-recaptcha-response cuando el usuario envía un formulario en tu sitio.
  • Llamando a grecaptcha.getResponse(opt_widget_id) después de que el usuario completa un desafío de reCAPTCHA v2 Este método devuelve el token de respuesta como una cadena o una cadena vacía si no se completa el desafío. El parámetro opcional opt_widget_id especifica el ID del widget que devuelve grecaptcha.render(). Si se omite, se establece de forma predeterminada en el primer widget creado.
  • Como argumento de cadena que se pasa a tu función de devolución de llamada cuando el usuario completa un desafío, si especificas el nombre de la función de devolución de llamada en el atributo data-callback del elemento HTML g-recaptcha o el parámetro callback del método grecaptcha.render(container, parameters)
  • Del valor resuelto de Promise que devuelve grecaptcha.execute(site_key, {action: action_name}) para las claves basadas en la puntuación (v3).

Los métodos grecaptcha heredados (render, getResponse, execute, ready y reset) y los atributos de la etiqueta g-recaptcha usan los mismos parámetros que los equivalentes de grecaptcha.enterprise. Para obtener detalles sobre los parámetros, consulta la referencia de la API de JavaScript para reCAPTCHA.

Para migrar a la API de JavaScript de reCAPTCHA actualizada, consulta Migra la API de JavaScript de reCAPTCHA.

Restricciones de tokens

Cada token de respuesta de usuario de reCAPTCHA es válido por dos minutos y solo puedes verificar cada token una vez para evitar ataques de repetición. Verifica el token de respuesta con reCAPTCHA en un plazo de dos minutos después de recibirlo. Si necesitas un token nuevo, vuelve a ejecutar la verificación de reCAPTCHA.

Solicitud a la API

Envía una solicitud con el siguiente extremo y método:

  • URL: https://www.google.com/recaptcha/api/siteverify (o https://www.recaptcha.net/recaptcha/api/siteverify si no se puede acceder a www.google.com; consulta Cómo usar reCAPTCHA a nivel global)
  • Método: POST

Incluye los siguientes parámetros POST en la solicitud:

Parámetro POST Descripción
secret Obligatorio. Es la clave secreta compartida entre tu sitio y reCAPTCHA.
response Obligatorio. Es el token de respuesta del usuario proporcionado por la integración del cliente de reCAPTCHA en tu sitio.
remoteip Es opcional. Es la dirección IP del usuario.

Respuesta de la API

El extremo SiteVerify devuelve un objeto JSON.

En el caso de las integraciones web (claves de la versión 3 basadas en la puntuación, de la versión 2 de casilla de verificación o de la versión 2 invisible), la respuesta tiene el siguiente formato:

{
  "success": true|false,      // whether this request was a valid reCAPTCHA token for your site
  "score": number,            // the score for this request (0.0 - 1.0) for score-based (v3) keys
  "action": string,           // the action name for this request (important to verify)
  "challenge_ts": timestamp,  // timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)
  "hostname": string,         // the hostname of the site where the reCAPTCHA was solved
  "error-codes": [...]        // optional
}

Referencia de código de error

En la siguiente tabla, se describen los códigos de error que pueden aparecer en el array error-codes:

Código de error Descripción
missing-input-secret Falta el parámetro secret.
invalid-input-secret El parámetro secret no es válido o tiene un formato incorrecto.
missing-input-response Falta el parámetro response.
invalid-input-response El parámetro response no es válido o tiene un formato incorrecto.
bad-request La solicitud no es válida o tiene un formato incorrecto.
timeout-or-duplicate La respuesta ya no es válida porque venció o ya se usó.

¿Qué sigue?