Revisão técnica: 08/09/2026. Exibir um reCAPTCHA na página não basta para proteger uma operação. O servidor precisa conferir o resultado antes de enviar e-mail, cadastrar usuário ou executar a ação protegida.
Identifique o tipo de integração
Confira se o projeto utiliza reCAPTCHA v2, v3 ou uma integração da plataforma Google Cloud. Não misture código de uma modalidade com chaves de outra. Para instalações antigas, consulte a migração de chaves e identifique quem controla o projeto, o uso e as configurações associadas.
O exemplo antigo de recaptchalib.php deste artigo foi retirado, inclusive porque suas instruções confundiam chave pública e privada. A chave destinada ao navegador e a credencial usada no servidor têm funções diferentes; segredos não devem aparecer no HTML.
Valide antes de executar a ação
Nas integrações que usam siteverify, o backend envia a resposta do navegador e a chave secreta ao endpoint de verificação. Os tokens têm uso único e validade de dois minutos. Confira sucesso e hostname esperado; para v3, verifique também a ação e trate a pontuação conforme a política definida.
Outras modalidades usam o fluxo de avaliação documentado para elas. Siga a integração correspondente em vez de reutilizar um endpoint por semelhança de nome.
Defina o tratamento de falhas
Token ausente, inválido ou expirado não deve liberar a operação. Se o serviço estiver indisponível, devolva uma resposta controlada e ofereça um caminho para tentar novamente, sem transformar a falha em aprovação automática.
Registre categoria do erro e horário, evitando armazenar segredos e dados pessoais desnecessários. Diferencie falha de configuração de rejeição da tentativa para orientar a investigação.
Teste o backend e a experiência
Em ambiente próprio de testes, confira envio válido, ausência de token, reutilização e expiração. Verifique também celular, teclado e as alternativas disponíveis para quem encontra dificuldade no desafio. A operação protegida só deve ocorrer após a decisão do servidor.
CAPTCHA não substitui validação de campos, autorização ou limites de frequência. Referências: verificação de respostas, reCAPTCHA v3 e migração de reCAPTCHA Classic.
2 comentários