CapMonster Cloud API
Extensão para navegadores
Como implementar CAPTCHA em HTML: um guia simples para desenvolvedores
Adicionar um CAPTCHA ao seu formulário HTML é uma das primeiras linhas de defesa mais eficazes contra bots, envios de spam e abuso automatizado. Seja para proteger uma página de login, um formulário de contato ou um fluxo de checkout, o CAPTCHA certo — e a implementação correta — pode fazer uma diferença significativa.
Este guia mostra, passo a passo, como adicionar código de captcha html ao seu projeto, cobrindo quatro opções populares: reCAPTCHA v2 (Checkbox e Invisible), Cloudflare Turnstile, Prosopo Procaptcha e Altcha. Para cada uma delas, você verá uma explicação completa, exemplos funcionais de código HTML e orientações sobre verificação no backend, testes locais e solução de problemas.
O que você precisa antes de começar
Toda solução de CAPTCHA normalmente funciona em torno do mesmo conceito central: você registra seu site com um provedor, recebe um par de captcha key (uma site key pública e uma secret key privada) e usa essas chaves para incorporar o widget e verificar as respostas.
Veja onde registrar cada provedor antes de escrever uma única linha de HTML:
Durante o registro, será solicitado que você informe seu nome de domínio. Para desenvolvimento local, adicione localhost à lista de domínios permitidos (mais sobre isso na seção de testes).
reCAPTCHA v2 Checkbox — passo a passo
A caixa de seleção clássica ("I'm not a robot") é o widget de captcha html mais amplamente reconhecido. Ela exibe uma caixa de seleção visível e, quando necessário, um desafio visual com imagens.
Etapa 1: registre-se e obtenha sua captcha key
Acesse google.com/recaptcha/admin e selecione reCAPTCHA v2 → "I'm not a robot" Checkbox. Adicione seu domínio (incluindo localhost para testes locais) e salve. Você receberá uma Site Key e uma Secret Key.
Etapa 2: adicione o script da API do reCAPTCHA
Coloque a seguinte tag <script> no <head> do seu HTML ou antes da tag de fechamento </body>:
<script src="https://www.google.com/recaptcha/api.js" async defer></script>Os atributos async e defer garantem que o script seja carregado sem bloquear a renderização da página.
Etapa 3: adicione a div do widget ao seu formulário
Coloque o elemento <div> dentro do seu formulário, logo antes do botão de envio. Substitua YOUR_SITE_KEY pela site key que você recebeu.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Formulário de contato</title>
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
</head>
<body>
<form action="/submit" method="POST">
<label for="email">Email:</label>
<input type="email" id="email" name="email" required>
<label for="message">Mensagem:</label>
<textarea id="message" name="message" required></textarea>
<!-- Widget Checkbox do reCAPTCHA v2 -->
<div class="g-recaptcha" data-sitekey="YOUR_SITE_KEY"></div>
<button type="submit">Enviar</button>
</form>
</body>
</html>Etapa 4: o que acontece no envio
Quando o usuário conclui o desafio e envia o formulário, o script do Google adiciona automaticamente um campo oculto chamado g-recaptcha-response aos dados do formulário. Seu backend lê esse token e o envia para a API de verificação do Google junto com sua secret key.
reCAPTCHA v2 Invisible — passo a passo
O Invisible reCAPTCHA remove totalmente a caixa de seleção visível. Em vez disso, ele executa uma análise de risco em segundo plano e só aciona um desafio visual se um comportamento suspeito for detectado — resultando em uma UX mais fluida para a maioria dos usuários.
Etapa 1: registre-se com o tipo correto
No console de administração do Google reCAPTCHA, selecione reCAPTCHA v2 → Invisible reCAPTCHA badge. Isso gera uma site key diferente da variante com checkbox — não reutilize chaves entre tipos diferentes.
Etapa 2: carregue o script da API
Use a mesma tag de script da variante com checkbox:
<script src="https://www.google.com/recaptcha/api.js" async defer></script>Etapa 3: anexe o CAPTCHA ao botão de envio
Em vez de usar uma <div> separada, você aplica os atributos do CAPTCHA diretamente ao <button> de envio, especificando um callback em JavaScript para ser executado quando o desafio for concluído.
Defina uma função de callback que envie o formulário de forma programática após a verificação ser aprovada.
Exemplo completo de formulário HTML
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Cadastro</title>
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
</head>
<body>
<form id="signup-form" action="/signup" method="POST">
<label for="username">Nome de usuário:</label>
<input type="text" id="username" name="username" required>
<!-- reCAPTCHA Invisible: anexado ao botão -->
<button
class="g-recaptcha"
data-sitekey="YOUR_SITE_KEY"
data-callback="onSubmit"
data-size="invisible"
type="submit">
Criar conta
</button>
</form>
<script>
function onSubmit(token) {
document.getElementById("signup-form").submit();
}
</script>
</body>
</html>Quando o botão é clicado, o reCAPTCHA executa sua análise em segundo plano, chama onSubmit(token) com um token de resposta, e seu callback envia o formulário. O token é incluído como g-recaptcha-response no corpo do POST.
Cloudflare Turnstile — passo a passo
O Cloudflare Turnstile é uma alternativa de CAPTCHA com foco em privacidade que não rastreia usuários, não define cookies de perfilamento e não exibe quebra-cabeças com imagens. Ele oferece três modos de widget:
- Managed: o widget decide se deve mostrar um desafio com base em sinais do navegador)
- Non-interactive: aprova sem exigir interação do usuário para a maioria dos visitantes
- Invisible: executa totalmente em segundo plano
Etapa 1: crie um widget no Painel da Cloudflare
Faça login na sua conta Cloudflare, navegue até Segurança de aplicativos → Turnstile, clique em Add widget, insira seu domínio e selecione um tipo de widget. Copie a Site Key e anote sua Secret Key.
Etapa 2: adicione o script do Turnstile
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>Etapa 3: adicione a div do widget ao seu formulário
<div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY"></div>O Turnstile injeta automaticamente um input oculto chamado cf-turnstile-response no formulário. Nenhum JavaScript extra é necessário para o envio padrão do formulário.
Exemplo completo de formulário HTML
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Login</title>
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
</head>
<body>
<form action="/login" method="POST">
<label for="password">Senha:</label>
<input type="password" id="password" name="password" required>
<!-- Widget Cloudflare Turnstile -->
<div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY"></div>
<button type="submit">Entrar</button>
</form>
</body>
</html>O modo Managed do Turnstile determinará — com base em sinais do navegador — se deve mostrar uma interação ou aprovar silenciosamente. Para testes, a Cloudflare fornece dummy site keys especiais (abordadas na seção de testes).
Prosopo Procaptcha — passo a passo
O Prosopo Procaptcha é um CAPTCHA nativo de Web3, com foco em privacidade, projetado como um substituto direto e plug-and-play para o reCAPTCHA. Ele não depende da infraestrutura do Google e foi criado tendo a privacidade do usuário como princípio central de design.
Etapa 1: obtenha sua captcha key da Prosopo
Registre-se em prosopo.io e crie um novo site para receber sua Site Key.
Etapa 2: carregue o bundle do Procaptcha
Adicione o script do Procaptcha:
<script src="https://js.prosopo.io/js/procaptcha.bundle.js" async defer></script>Etapa 3: adicione o widget ao seu formulário
Coloque uma <div> com a classe procaptcha e sua site key como atributo data-sitekey.
Exemplo completo de formulário HTML
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Cadastro</title>
<script type="module" src="https://js.prosopo.io/js/procaptcha.bundle.js" async defer></script>
</head>
<body>
<form action="/register" method="POST">
<label for="email">Email:</label>
<input type="email" id="email" name="email" required>
<!-- Widget Prosopo Procaptcha -->
<div class="procaptcha" data-sitekey="YOUR_SITE_KEY"></div>
<button type="submit">Cadastrar</button>
</form>
</body>
</html>Etapa 4: envio do token
No envio do formulário, o Procaptcha injeta um campo oculto chamado procaptcha-response no seu formulário. Envie esse token para a API de verificação da Prosopo junto com sua secret key no backend.
Altcha — passo a passo
O Altcha é um CAPTCHA totalmente open source e auto-hospedado que usa um mecanismo de proof-of-work — o navegador do usuário executa uma pequena tarefa computacional em vez de resolver um quebra-cabeça visual. Ele não coleta dados do usuário, não define cookies de rastreamento e está totalmente em conformidade com o GDPR. Como é auto-hospedado, não há dependência de terceiros.
Etapa 1: carregue o widget do Altcha
Não é necessário registro. Carregue o script do elemento personalizado:
<script async defer type="module"
src="https://cdn.jsdelivr.net/gh/altcha-org/altcha/dist/altcha.min.js">
</script>Etapa 2: configure o endpoint de challenge
O Altcha exige um endpoint no servidor que gere um challenge criptográfico (usando uma HMAC secret key definida por você). Esse endpoint é chamado pelo widget antes do envio para buscar um challenge novo. A biblioteca de servidor do Altcha no seu framework cuida disso. A URL do endpoint é passada ao widget por meio do atributo challengeurl.
Etapa 3: adicione o widget ao seu formulário HTML
Exemplo completo de formulário HTML
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Feedback</title>
<script async defer type="module"
src="https://cdn.jsdelivr.net/gh/altcha-org/altcha/dist/altcha.min.js">
</script>
</head>
<body>
<form action="/feedback" method="POST">
<label for="feedback">Seu feedback:</label>
<textarea id="feedback" name="feedback" required></textarea>
<!-- Widget Altcha -- aponta para seu próprio endpoint de challenge -->
<altcha-widget challengeurl="/api/altcha-challenge"></altcha-widget>
<button type="submit">Enviar</button>
</form>
</body>
</html>Etapa 4: envio do token
Depois que o proof-of-work é concluído, o Altcha preenche um input oculto chamado altcha com uma carga codificada em base64. Seu backend verifica essa carga com base no seu segredo HMAC — nenhuma chamada de API externa é necessária.
Verificação no backend — como funciona
Independentemente do CAPTCHA que você usar, o padrão de verificação no lado do servidor é o mesmo:
- Extraia o token do corpo da requisição POST usando o nome do campo específico de cada provedor (g-recaptcha-response, cf-turnstile-response, procaptcha-response ou altcha).
- Envie o token para o endpoint de verificação do provedor — uma requisição POST que inclui sua secret key e o token do usuário (e, opcionalmente, o endereço IP do usuário no caso do reCAPTCHA).
- Faça o parse da resposta JSON — os provedores retornam um indicador de sucesso/falha na resposta. reCAPTCHA e Turnstile usam um campo success: true/false; a Prosopo usa verified: true/false; o Altcha é verificado localmente com base no seu segredo HMAC. Alguns provedores também retornam hostname e timestamp do challenge.
- Aceite ou rejeite o envio — se a verificação falhar, retorne um erro ao usuário e não processe os dados do formulário. Se passar, prossiga normalmente.
Endpoints de verificação por provedor:
- reCAPTCHA v2: [https://www.google.com/recaptcha/api/siteverify](https://www.google.com/recaptcha/api/siteverify)
- Cloudflare Turnstile: [https://challenges.cloudflare.com/turnstile/v0/siteverify](https://challenges.cloudflare.com/turnstile/v0/siteverify)
- Prosopo: [https://api.prosopo.io/siteverify](https://api.prosopo.io/siteverify)
- Altcha: Local — verificado com base no seu próprio segredo HMAC, sem necessidade de chamada externa
⚠️ Nunca use sua site key para verificação no backend — sempre use a secret key. Confundir as duas é um dos erros de integração mais comuns.
Testando seu CAPTCHA HTML em um servidor local
Testar CAPTCHA localmente exige alguns passos extras, já que a maioria dos provedores valida nomes de domínio.
- reCAPTCHA v2: Adicione localhost à lista de domínios permitidos no console de administração do Google reCAPTCHA. O widget será renderizado e funcionará normalmente em http://localhost.
- Cloudflare Turnstile: Use as test site keys oficiais da Cloudflare. A chave 1x00000000000000000000AA sempre produz um resultado de aprovação; a 2x00000000000000000000AB sempre falha. Você também pode combinar a site key de aprovação (1x00000000000000000000AA) com a secret key 3x0000000000000000000000000000000AA no backend para simular um erro "timeout-or-duplicate". Troque todas as chaves de teste pelas suas chaves reais de produção antes de fazer o deploy.
- Prosopo Procaptcha: localhost é compatível por padrão durante o desenvolvimento — nenhuma configuração extra é necessária.
- Altcha: Como ele é auto-hospedado, localhost funciona nativamente. Apenas certifique-se de que seu endpoint de challenge também esteja rodando localmente.
Use o DevTools → aba Network do navegador para confirmar que o script da API do CAPTCHA foi carregado (HTTP 200) e que o POST do formulário inclui o campo de token esperado.
Solução de problemas comuns
O widget CAPTCHA não é renderizado
- Verifique novamente se a site key corresponde ao tipo de CAPTCHA que você registrou (chaves de checkbox não funcionam para o modo invisible, e vice-versa).
- Confirme se a tag <script> da API está presente e é carregada sem erro 404 ou CORS no DevTools.
- Garanta que o domínio no seu registro corresponda ao domínio de onde você está servindo o conteúdo, inclusive com ou sem www..
O token está ausente no POST do formulário
- O input oculto só é injetado depois que o challenge é concluído. Se o usuário enviar antes de ele estar pronto, nenhum token será enviado.
- Para o Invisible reCAPTCHA, certifique-se de que o callback onSubmit acione form.submit() depois que o token estiver disponível, e não antes.
- Para o Altcha, confirme que seu endpoint de challenge está acessível e retornando um challenge válido.
A verificação no backend retorna uma resposta de falha
- Verifique se você está enviando a secret key (e não a site key) para o endpoint de verificação.
- Os tokens normalmente são de uso único — se você estiver tentando novamente o mesmo POST nos testes, gere um token novo a cada vez.
- Verifique se há dessincronização de relógio: alguns provedores (especialmente o Altcha) rejeitam challenges antigos demais.
Erro de "Invalid domain" ou incompatibilidade de sitekey
- Em localhost, certifique-se de que localhost (e não 127.0.0.1) está na sua lista de domínios permitidos.
- Para o Turnstile, mude para a test site key durante o desenvolvimento local.
Widget oculto ou sobreposto a outros elementos
- Os widgets CAPTCHA são renderizados em iframes com z-index fixo. Se outro elemento (um modal, cabeçalho fixo etc.) tiver um z-index maior, ele poderá encobrir o widget.
- Defina um z-index explícito no contêiner pai ou verifique se há overflow: hidden em elementos ancestrais cortando o iframe.
Nota de acessibilidade: Todos os quatro provedores deste guia oferecem alternativas acessíveis. reCAPTCHA e Turnstile fornecem desafios de áudio; Prosopo e Altcha são projetados para minimizar o incômodo ao usuário por padrão, reduzindo totalmente a dependência de quebra-cabeças visuais.
Automatizando e testando a resolução de CAPTCHA com CapMonster Cloud
Quando sua implementação de CAPTCHA estiver em produção, talvez você precise testá-la programaticamente — para pipelines de QA, testes de integração ou monitoramento automatizado. Resolver CAPTCHAs manualmente toda vez que um teste roda não é viável em escala.
CapMonster Cloud é um serviço automatizado de resolução de CAPTCHA com tecnologia de IA que oferece suporte aos quatro tipos de CAPTCHA abordados neste guia: reCAPTCHA v2 (checkbox e invisible), Cloudflare Turnstile, Prosopo Procaptcha e Altcha. Ele funciona expondo uma API simples: você envia uma tarefa com a URL da página de destino e a site key, e o serviço retorna um token resolvido pronto para ser injetado no seu formulário.
Como ele se encaixa no fluxo de trabalho de um desenvolvedor:
- Testes de integração automatizados: execute testes end-to-end em formulários protegidos por CAPTCHA em pipelines de CI/CD sem interação manual.
- Verificação de QA: confirme que seu backend valida e rejeita tokens corretamente em diferentes condições.
- Pipelines de coleta de dados em que a interação com páginas protegidas por CAPTCHA faz parte de um fluxo autorizado.
O CapMonster Cloud é compatível com a interface de API amplamente usada, o que significa que ele se integra a muitos frameworks de automação existentes com configuração mínima. Você envia uma tarefa contendo a URL da página e a site key, consulta o resultado e recebe o token — que então injeta como o valor apropriado de campo oculto no formulário.
Conclusão
Implementar uma solução de captcha html não exige infraestrutura complexa — apenas uma tag de script, um elemento de widget, o par correto de captcha key e uma verificação de token no lado do servidor. Cada opção deste guia tem seus próprios pontos fortes: o reCAPTCHA v2 é testado em batalha e amplamente confiável; o Turnstile minimiza o incômodo ao usuário e é amigável à privacidade; a Prosopo oferece uma alternativa nativa de Web3 sem dependência do Google; e o Altcha oferece controle total com uma infraestrutura auto-hospedada e open source.
Pronto para começar? Escolha o CAPTCHA que melhor se adapta às suas exigências de privacidade, UX e infraestrutura, registre sua site key e use os exemplos de código acima para adicioná-lo ao seu formulário em minutos. Se você precisar automatizar testes ou QA nos seus formulários protegidos, CapMonster Cloud oferece suporte aos quatro provedores e se integra diretamente aos seus pipelines existentes.
