Verificar tokens de resposta do usuário com o SiteVerify legado

Esta página explica como verificar a resposta de um usuário a um teste reCAPTCHA no back-end do aplicativo usando o endpoint legado da API SiteVerify (https://www.google.com/recaptcha/api/siteverify). Use esse endpoint apenas se você estiver mantendo uma integração legada ou um plug-in de terceiros que não pode usar CreateAssessment.

Antes de começar

Para chamar o endpoint SiteVerify, você precisa da chave secreta legada da sua chave. Para encontrar a chave secreta no console do Google Cloud , consulte Recuperar a chave secreta no console do Google Cloud . Mantenha sua chave secreta segura no servidor de back-end e nunca a exponha no código do lado do cliente.

Recuperar o token de resposta do usuário

As integrações legadas da Web carregam a API JavaScript não empresarial (https://www.google.com/recaptcha/api.js), que fornece métodos no objeto grecaptcha em vez de grecaptcha.enterprise. É possível recuperar o token de resposta do usuário no front-end de uma das seguintes maneiras:

  • Do parâmetro POST g-recaptcha-response quando o usuário envia um formulário no seu site.
  • Chamando grecaptcha.getResponse(opt_widget_id) depois que o usuário conclui um desafio do reCAPTCHA v2. Esse método retorna o token de resposta como uma string ou uma string vazia se o desafio não for concluído. O parâmetro opcional opt_widget_id especifica o ID do widget retornado por grecaptcha.render(). Se for omitido, o padrão será o primeiro widget criado.
  • Como um argumento de string transmitido à função de callback quando o usuário conclui um desafio, se você especificar o nome da função de callback no atributo data-callback do elemento HTML g-recaptcha ou no parâmetro callback do método grecaptcha.render(container, parameters).
  • Do valor resolvido do Promise retornado por grecaptcha.execute(site_key, {action: action_name}) para chaves baseadas em pontuação (v3).

Os métodos legados grecaptcha (render, getResponse, execute, ready e reset) e os atributos da tag g-recaptcha usam os mesmos parâmetros que os equivalentes grecaptcha.enterprise. Para detalhes dos parâmetros, consulte a referência da API JavaScript para reCAPTCHA.

Para migrar para a API JavaScript do reCAPTCHA atualizada, consulte Migrar a API JavaScript do reCAPTCHA.

Restrições de token

Cada token de resposta de reCAPTCHA do usuário é válido por dois minutos, e você pode verificar cada token apenas uma vez para evitar ataques repetitivos. Verifique o token de resposta com o reCAPTCHA em até dois minutos após o recebimento. Se precisar de um novo token, execute a verificação reCAPTCHA de novo.

Solicitação da API

Envie uma solicitação com o seguinte endpoint e método:

  • URL: https://www.google.com/recaptcha/api/siteverify (ou https://www.recaptcha.net/recaptcha/api/siteverify se www.google.com não estiver acessível. Consulte Usar o reCAPTCHA globalmente)
  • Método: POST

Inclua os seguintes parâmetros POST na solicitação:

Parâmetro POST Descrição
secret Obrigatório. A chave secreta compartilhada entre seu site e o reCAPTCHA.
response Obrigatório. O token de resposta do usuário fornecido pela integração do reCAPTCHA no lado do cliente no seu site.
remoteip Opcional. O endereço IP do usuário.

Resposta da API

O endpoint SiteVerify retorna um objeto JSON.

Para integrações da Web (chaves v3 baseadas em pontuação, v2 de caixa de seleção ou v2 invisíveis), a resposta tem o seguinte 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
}

Referência do código de erro

A tabela a seguir descreve os códigos de erro que podem aparecer na matriz error-codes:

Código do erro Descrição
missing-input-secret O parâmetro secret está ausente.
invalid-input-secret O parâmetro secret é inválido ou está incorreto.
missing-input-response O parâmetro response está ausente.
invalid-input-response O parâmetro response é inválido ou está incorreto.
bad-request A solicitação é inválida ou está incorreta.
timeout-or-duplicate A resposta não é mais válida porque expirou ou já foi usada.

A seguir