Integração da API do reCAPTCHA v2: como conectar e usar
A integração da API do reCAPTCHA v2 é uma tarefa de segurança padrão para desenvolvedores web em 2026. O reCAPTCHA v2 do Google funciona em duas variantes: a familiar caixa de seleção "Não sou um robô" e um modo invisível que é acionado silenciosamente em segundo plano. Em ambos os casos, o mecanismo é o mesmo — um widget no lado do cliente gera um token de uso único, e seu servidor o verifica na API siteverify do Google antes de processar a solicitação.
Este guia cobre todo o processo de integração: registro do site, incorporação do widget em HTML, verificação do token no lado do servidor e tratamento de erros comuns. Ele também aborda o lado da automação — o que fazer quando o reCAPTCHA v2 aparece em fluxos de trabalho que não podem envolver um humano. Para uma visão mais ampla, comece pela nossa página do solver de reCAPTCHA v2.
Opinião de especialista — Vladlen Vlasov, especialista em desenvolvimento e segurança web
"Os detalhes da integração do reCAPTCHA v2 ainda importam em 2026 justamente porque o widget é amplamente utilizado. Fazer a etapa de verificação no lado do servidor de forma incorreta — ou simplesmente ignorá-la — ainda é um dos problemas de segurança mais comuns que vejo em fóruns de desenvolvedores. O widget no lado do cliente é apenas metade da história."
O que é o reCAPTCHA v2 e como ele funciona?
O reCAPTCHA v2 é um serviço de CAPTCHA do Google que distingue usuários humanos de bots automatizados. Ele funciona em duas fases: uma fase no lado do cliente, na qual o navegador renderiza o widget e gera um token de resposta após a interação do usuário, e uma fase no lado do servidor, na qual seu backend verifica esse token com a API do Google.
A variante com caixa de seleção pede que o usuário clique em "Não sou um robô". O mecanismo de análise de risco do Google é executado em segundo plano; se a pontuação estiver em uma faixa limítrofe, um desafio com imagens será apresentado. A variante invisível pula a caixa de seleção visível e é acionada automaticamente em uma ação configurada, geralmente o envio de um formulário, exibindo um desafio apenas quando a pontuação de risco exigir isso.
Entender a diferença entre o v2 e suas outras versões é importante para as decisões de integração. Veja reCAPTCHA v2 vs v3 vs Enterprise: principais diferenças para uma análise técnica detalhada.
Pré-requisitos antes de integrar o reCAPTCHA v2
Antes de começar a programar, você precisa de duas coisas do Google: uma Site Key e uma Secret Key.
Registrando seu site
- Acesse google.com/recaptcha/admin/create e faça login com uma conta do Google.
- Insira um rótulo, selecione reCAPTCHA v2 e escolha a variante com caixa de seleção ou invisível.
- Adicione seu domínio em Domains. Adicione localhost se estiver testando localmente.
- Selecione um projeto existente do Google Cloud Platform ou crie um novo. O reCAPTCHA Classic foi migrado para o GCP no início de 2026, portanto todas as chaves agora ficam vinculadas a um projeto do GCP.
- Aceite os Termos de Serviço e clique em Submit.
O Google exibirá duas chaves:
- Site Key — pública, incorporada ao seu HTML.
- Secret Key — privada, usada apenas no seu servidor. Nunca a exponha em código do lado do cliente.
Você precisa de HTTPS em produção. O reCAPTCHA pode funcionar via HTTP em localhost durante o desenvolvimento, mas implantações em produção exigem uma conexão segura e acesso HTTPS de saída para www.google.com para verificação.
Adicionando o reCAPTCHA v2 ao seu formulário HTML
Carregando o script do reCAPTCHA
Coloque a seguinte tag de script no <head> da sua página, ou logo antes da tag de fechamento </body>:
<script src="https://www.google.com/recaptcha/api.js" async defer></script>Os atributos async defer evitam que o script bloqueie a renderização da página.
Posicionando o widget com data-sitekey
Para a variante padrão com caixa de seleção, adicione uma div dentro do seu formulário com a classe g-recaptcha e sua Site Key:
<form method="POST" action="/submit">
*<!-- your form fields -->*
<div class="g-recaptcha" data-sitekey="YOUR_SITE_KEY"></div>
<button type="submit">Submit</button>
</form>Quando a página carrega, o script do Google substitui essa div pelo widget interativo. Após uma interação bem-sucedida, ele preenche um campo oculto chamado g-recaptcha-response, que é enviado com o formulário.
Configuração da variante invisível
A variante invisível é vinculada ao seu botão de envio, em vez de renderizar um widget visível:
<form method="POST" action="/submit">
*<!-- your form fields -->*
<button
class="g-recaptcha"
data-sitekey="YOUR_SITE_KEY"
data-callback="onSubmit"
data-action="submit"
type="submit">
Submit
</button>
</form>
<script>
function onSubmit(token) {
document.getElementById('your-form-id').submit();
}
</script>A função data-callback recebe o token e aciona o envio real do formulário. Sem esse callback, o formulário não será enviado após a conclusão do reCAPTCHA.
Verificação no lado do servidor com a API siteverify
Incorporar o widget é apenas a primeira metade de uma integração segura do reCAPTCHA v2. Você precisa verificar o token no seu servidor. Um token que nunca é verificado não oferece nenhuma proteção contra bots.
O fluxo é direto: o usuário interage com o widget → o Google retorna um token g-recaptcha-response ao navegador → o token é enviado ao seu servidor com o formulário → seu servidor faz um POST do token e da sua Secret Key para https://www.google.com/recaptcha/api/siteverify → o Google responde com um resultado em JSON.
Requisição POST para siteverify
O endpoint de verificação aceita uma requisição POST com dois parâmetros obrigatórios:
| Parâmetro | Descrição |
| secret | Sua Secret Key |
| response | O token g-recaptcha-response do cliente |
| remoteip (opcional) | O endereço IP do usuário |
Interpretando a resposta JSON e tratando erros
Uma verificação bem-sucedida retorna:
{
"success": true,
"challenge_ts": "2026-06-17T10:00:00Z",
"hostname": "yourdomain.com",
"error-codes": ]
}Uma verificação com falha retorna "success": false e um ou mais códigos de erro:
| Código de erro | Significado |
| missing-input-secret | O parâmetro Secret Key não foi enviado |
| invalid-input-secret | A Secret Key está incorreta ou malformada |
| missing-input-response | O token não foi enviado pelo cliente |
| invalid-input-response | O token é inválido ou malformado |
| timeout-or-duplicate | O token expirou ou já foi usado |
Sempre verifique success === true antes de prosseguir. Não confie apenas na ausência de códigos de erro.
Exemplo de verificação no lado do servidor em PHP
O exemplo a seguir mostra funções completas de verificação no lado do servidor. Substitua $YOUR_SECRET_KEY pela sua Secret Key real.
<?php
declare(strict_types=1);
function verifyRecaptchaV2(
string $token,
string $YOUR_SECRET_KEY,
?string $remoteIp = null
): array {
if ($token === "") {
return [
"ok" => false,
"message" => "O token do reCAPTCHA não foi recebido.",
"data" => null,
];
}
$postFields = [
"secret" => $YOUR_SECRET_KEY,
"response" => $token,
];
if ($remoteIp !== null && $remoteIp !== "") {
$postFields["remoteip"] = $remoteIp;
}
$ch = curl_init("https://www.google.com/recaptcha/api/siteverify");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query($postFields),
CURLOPT_TIMEOUT => 10,
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_SSL_VERIFYPEER => true,
CURLOPT_SSL_VERIFYHOST => 2,
]);
$responseBody = curl_exec($ch);
$curlError = curl_error($ch);
$httpCode = (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($responseBody === false || $curlError !== "") {
return [
"ok" => false,
"message" => "Falha ao enviar uma requisição ao Google reCAPTCHA.",
"data" => null,
];
}
if ($httpCode < 200 || $httpCode >= 300) {
return [
"ok" => false,
"message" =>
"O Google reCAPTCHA retornou um status HTTP inesperado.",
"data" => null,
];
}
$data = json_decode($responseBody, true);
if (!is_array($data)) {
return [
"ok" => false,
"message" => "Falha ao interpretar a resposta do Google reCAPTCHA.",
"data" => null,
];
}
if (!empty($data["success"])) {
return [
"ok" => true,
"message" => "A verificação do reCAPTCHA foi aprovada com sucesso.",
"data" => $data,
];
}
$errors =
isset($data["error-codes"]) && is_array($data["error-codes"])
? implode(", ", $data["error-codes"])
: "unknown_error";
return [
"ok" => false,
"message" => "A verificação do reCAPTCHA falhou: " . $errors,
"data" => $data,
];
}
Usando o reCAPTCHA v2 em JavaScript
Depois de integrar o reCAPTCHA v2, você pode interagir diretamente com o widget por meio da API JavaScript. A tabela abaixo cobre os principais métodos e callbacks.
| Método / Callback | Objetivo |
| grecaptcha.render() | Renderizar manualmente o widget em um elemento contêiner |
| grecaptcha.getResponse() | Obter o token de resposta atual (string vazia se ainda não tiver sido resolvido) |
| grecaptcha.reset() | Redefinir o desafio atual para que o usuário possa resolvê-lo novamente |
| callback | É acionado quando o usuário conclui o desafio com sucesso; recebe o token |
| expired-callback | É acionado quando um token já resolvido expira antes do envio |
Exemplos práticos em JavaScript
Obter o token gerado:
const token = grecaptcha.getResponse();Redefinir o widget após uma requisição com falha:
grecaptcha.reset();Renderizar o widget dinamicamente (útil em SPAs ou quando o contêiner é inserido após o carregamento da página):
function onSolved(token) {
document.querySelector('textarea[name="g-recaptcha-response"]').value = token;
document.getElementById('contact-form').submit();
}
grecaptcha.render('captcha-container', {
sitekey: 'YOUR_SITE_KEY',
callback: onSolved,
'expired-callback': () => grecaptcha.reset(),
});Verificar se o usuário concluiu o desafio antes de enviar:
if (!grecaptcha.getResponse()) {
alert('Complete the CAPTCHA first.');
return;
}O expired-callback é fácil de ignorar: se o usuário resolver o desafio, mas esperar mais de dois minutos antes de enviar, o token expira silenciosamente. Sem esse manipulador, seu formulário enviará um token inválido e falhará na verificação do lado do servidor com timeout-or-duplicate.
Erros comuns de integração e como corrigi-los
Mesmo uma integração simples do reCAPTCHA v2 pode falhar de maneiras previsíveis.
| Problema | Causa provável | Correção |
| O widget não renderiza | Tag de script ausente ou bloqueada por CSP | Adicione https://www.google.com ao seu CSP script-src e frame-src |
| invalid-input-secret na verificação | A Secret Key está errada ou pertence ao projeto errado | Verifique o Admin Console e confirme que você está usando a Secret Key correta |
| timeout-or-duplicate | Token com mais de ~2 minutos ou enviado duas vezes | Solicite novamente ao usuário e nunca reutilize um token |
| invalid-input-response | O token não foi encaminhado ao servidor | Registre req.body['g-recaptcha-response'] em log para confirmar que ele chega ao seu handler |
| Erro de incompatibilidade de domínio no console | Domínio não registrado no Admin Console | Adicione o domínio exato nas configurações do Admin do reCAPTCHA |
| O widget quebra após mudança de rota em SPA | O widget não é renderizado novamente após manipulação do DOM | Chame grecaptcha.render() ou redefina com grecaptcha.reset() |
| missing-input-response em formulários AJAX | O campo do token não foi incluído no payload AJAX | Leia grecaptcha.getResponse() e adicione-o ao corpo do seu fetch ou XHR |
Nunca trate a ausência de um token como uma verificação aprovada. Se g-recaptcha-response estiver ausente, rejeite a requisição imediatamente.
reCAPTCHA v2 para automação: a abordagem da API de solver
Você acabou de adicionar o reCAPTCHA v2 ao seu site — agora é hora de testar como ele se comporta na prática. Em vez de resolver o desafio manualmente a cada verificação, você pode enviar os parâmetros públicos do seu reCAPTCHA para o CapMonster Cloud, receber um token válido e usá-lo para testar diferentes cenários na sua integração.
A API de resolução de reCAPTCHA v2 do CapMonster Cloud segue um padrão de quatro etapas:
- Envie uma tarefa com a URL da página de destino e a sitekey.
- Faça polling do resultado.
- Insira o token retornado em g-recaptcha-response.
- Envie o formulário antes que o token expire.
O CapMonster Cloud oferece uma API de solver de reCAPTCHA v2 que segue esse padrão de retorno de token.
Para um passo a passo prático, veja Como resolver o reCAPTCHA v2 em 2026: métodos que funcionam. Se você estiver comparando fornecedores, o artigo "Como escolher o melhor solucionador de reCAPTCHA v2 em 2026" oferece orientações práticas.
Insight principal — Vladlen Vlasov, especialista em desenvolvimento e segurança web
"O desenvolvedor que adiciona o reCAPTCHA a um site e o engenheiro de automação que o encontra em um pipeline estão resolvendo problemas em imagem espelhada. Entender os dois lados torna você melhor em cada um deles: uma integração mais rigorosa no lado do servidor é mais difícil de contornar, e uma integração de API de solver bem estruturada é mais confiável quando os tokens expiram ou as páginas mudam."
FAQ
Conclusão
Uma integração correta da API do reCAPTCHA v2 exige duas partes: um widget funcional no lado do cliente e uma verificação siteverify no lado do servidor que realmente controle o processamento da requisição. Para a maioria dos projetos, a variante com caixa de seleção é o ponto de partida mais seguro — mais fácil de implementar, mais simples de depurar e mais clara para os usuários. A variante invisível faz sentido quando reduzir o inconveniente para o usuário é uma prioridade mensurável e seu fluxo de callback está sólido. Se seus fluxos de automação precisarem lidar com o reCAPTCHA v2 de forma programática, o modelo de injeção de token é simples — a principal limitação é o tempo de vida do token, então obtenha e envie rapidamente.
Obtenha tokens do reCAPTCHA v2 para seus pipelines de automação
Se seus fluxos de automação encontram o reCAPTCHA v2 em escala, a resolução manual não se sustenta. O CapMonster Cloud fornece uma API de solver de reCAPTCHA v2 que se encaixa no mesmo padrão de integração descrito neste guia — envie a sitekey e a URL da página, receba um token pronto para uso.
- Compatível com automação de navegador e fluxos HTTP diretos
- Padrão de API simples para criação de tarefas e recuperação de resultados
- Criado para casos de uso de automação relacionados ao reCAPTCHA
Explore o fluxo compatível com reCAPTCHA v2 na página de visão geral do reCAPTCHA v2.
