API do reCAPTCHA v3: guia passo a passo
Integrar o reCAPTCHA v3 envolve três etapas sequenciais: registrar suas chaves, configurar o recaptcha v3 javascript no frontend e verificar o token no backend. Aqui está o fluxo completo.
Etapa 1 — registre suas chaves no Google Admin Console
Antes de escrever uma única linha de código, você precisa das credenciais.
- Acesse o Google reCAPTCHA Admin Console.
- Preencha o campo Label name e selecione reCAPTCHA v3 (baseado em pontuação, sem challenge).
- Adicione todos os domínios em que seu site é executado (por exemplo, example.com, www.example.com).
- Selecione seu projeto do Google Cloud Platform, se houver. Caso contrário, ele será criado automaticamente.
- Envie o formulário. O Google fornecerá duas chaves:
- Site key — pública; usada no HTML/JS do frontend.
- Secret key — privada; usada apenas no servidor backend. Nunca a exponha no código do lado do cliente.
Etapa 2 — carregue a biblioteca JavaScript do reCAPTCHA v3
Em cada página que você deseja proteger, carregue o script da recaptcha v3 api adicionando a seguinte tag ao <head> do seu HTML, substituindo YOUR_SITE_KEY pela sua chave real:
<script src="https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY"></script>
Esse único trecho inicializa o mecanismo recaptcha v3 google e começa a coletar passivamente sinais comportamentais em segundo plano — nenhum widget é mostrado ao usuário.
Etapa 3 — execute o reCAPTCHA em uma ação protegida
Ao contrário do recaptcha v2, você não renderiza um widget. Em vez disso, chama grecaptcha.execute() programaticamente no momento em que o usuário aciona uma ação protegida.
Opção A — botão com data-attributes (formulários simples):
<form id="login-form">
<!-- os campos do seu formulário -->
<button
class="g-recaptcha"
data-sitekey="YOUR_SITE_KEY"
data-callback="onSubmit"
data-action="login"
type="button">
Entrar
</button>
</form>
<script>
function onSubmit(token) {
fetch("/api/login", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ recaptchaToken: token })
});
}
</script>
Opção B — execução programática (recomendada para fluxos AJAX/API):
<script src="https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY"></script>
<script>
async function submitLogin() {
const token = await new Promise((resolve) => {
grecaptcha.ready(() => {
grecaptcha.execute("YOUR_SITE_KEY", { action: "login" }).then(resolve);
});
});
// Envie o token imediatamente -- ele expira em 2 minutos
await fetch("/api/login", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ recaptchaToken: token })
});
}
</script>
Regra principal: o nome da action (por exemplo, login, signup, checkout) deve corresponder ao que seu backend espera. Isso evita a reutilização de tokens entre diferentes endpoints.
Etapa 4 — verifique o token no backend
Seu servidor recebe o token e o encaminha para o endpoint siteverify do Google antes de processar a solicitação do usuário.
Exemplo em Node.js (com tratamento de erros):
import express from "express";
const app = express();
app.use(express.json());
app.post("/api/login", async (req, res) => {
const token = req.body.recaptchaToken;
const params = new URLSearchParams();
params.set("secret", process.env.RECAPTCHA_SECRET);
params.set("response", token);
let data;
try {
const verifyResp = await fetch("https://www.google.com/recaptcha/api/siteverify", {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: params
});
data = await verifyResp.json();
} catch (err) {
console.error("reCAPTCHA verification network error:", err);
return res.status(503).json({ error: "verification_unavailable" });
}
// → prossiga para a Etapa 5
});
Observação: o fetch nativo está disponível no Node.js 18+. Em versões mais antigas, use node-fetch ou axios.
Exemplo em Python (Flask ≥ 2.0):
import os, requests
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.post("/api/signup") # Requer Flask >= 2.0
def signup():
token = request.json.get("recaptchaToken")
resp = requests.post(
"https://www.google.com/recaptcha/api/siteverify",
data={"secret": os.environ["RECAPTCHA_SECRET"], "response": token},
timeout=5
)
data = resp.json()
# → prossiga para a Etapa 5
if not data.get("success"):
return jsonify({"error": "recaptcha_failed"}), 403
return jsonify({"ok": True})
Etapa 5 — interprete a pontuação e tome uma ação
O endpoint siteverify do Google retorna uma resposta JSON. Veja como é uma resposta bem-sucedida:
{
"success": true,
"score": 0.7,
"action": "login",
"challenge_ts": "2026-02-27T10:00:00Z",
"hostname": "example.com"
}
Seu backend deve verificar três coisas, nesta ordem:
- success é true— o token é válido e foi aceito pelo Google.
- action corresponde ao valor esperado — isso confirma que o token foi gerado para o contexto correto.
- score atinge o seu limite — 0.5 é o ponto de partida recomendado pelo Google.
Etapa 6 — trate os erros de forma adequada
A resposta de siteverify pode incluir um array error-codes. Os mais importantes para tratar são:
- timeout-or-duplicate — o token tem mais de 2 minutos ou já foi usado; execute grecaptcha.execute() novamente no cliente para obter um token novo.
- missing-input-secret / invalid-input-secret — sua secret key está ausente ou incorreta; isso é um bug de configuração, não um erro do usuário.
- missing-input-response / invalid-input-response — o token não foi enviado ou está malformado; verifique sua integração no frontend.
- bad-request — a solicitação geral para siteverify está malformada.
Nunca exponha códigos de erro brutos aos usuários finais — registre-os no servidor e mostre uma mensagem genérica como "tente novamente".
Etapa 7 — teste sua integração de ponta a ponta
Antes de ir para produção, verifique o fluxo completo:
- Abra sua página protegida, acione a ação e confirme que um token é gerado no navegador.
- Registre a resposta bruta de siteverify no backend para confirmar success: true, um score válido e a action correta.
- Para testes automatizados, o CapMonster Cloud fornece uma solver API que gera programaticamente tokens válidos de reCAPTCHA v3. Ele oferece suporte a reCAPTCHA v3, v2 e Enterprise e integra via REST API.
- Confirme que seus fluxos de tratamento de erro funcionam enviando um token expirado ou malformado e verificando se o backend retorna a resposta correta.
Considerações sobre privacidade e conformidade
O modelo de perfilamento comportamental do reCAPTCHA version 3 traz implicações relevantes de privacidade. O sistema coleta movimentos do mouse, timing de teclas, impressões digitais do navegador, endereços IP e mais — dados que vão muito além do estritamente necessário para verificar se o usuário é humano.
Para operadores europeus em particular, isso cria exposição ao GDPR. Em uma ação de fiscalização relevante em 2023, a autoridade francesa de proteção de dados (CNIL) multou a empresa de e-scooters Cityscoot em €125,000 por múltiplas violações do GDPR — incluindo tanto a coleta excessiva de dados de geolocalização (rastreamento dos scooters a cada 30 segundos) quanto a implantação do Google reCAPTCHA sem o devido consentimento do usuário. A CNIL decidiu que o acesso do reCAPTCHA aos dados do terminal do usuário exige consentimento prévio nos termos do Artigo 82 da Lei Francesa de Proteção de Dados — e não se trata apenas de um widget de segurança passivo. Se você opera sob o GDPR, implementar um Data Processing Agreement adequado com o Google e obter o consentimento apropriado dos usuários é essencial antes de implantar o google recaptcha v3.
CapMonster Cloud e reCAPTCHA v3
CapMonster Cloud é um serviço de reconhecimento e automação de CAPTCHA com IA que oferece suporte a reCAPTCHA v2, v3 e Enterprise, entre muitos outros tipos de CAPTCHA. Para equipes de desenvolvimento e testes, ele fornece uma forma de automatizar interações com formulários protegidos por reCAPTCHA sem intervenção manual — útil para testes de integração, pipelines automatizados de monitoramento ou fluxos legítimos de scraping em que o tratamento de CAPTCHA se torna um gargalo.
No contexto de using recaptcha v3, o CapMonster Cloud funciona como uma solver API: dado um URL de destino e uma site key, ele retorna um token reCAPTCHA válido que pode ser enviado ao endpoint protegido exatamente como um navegador real faria.
Exemplo de resolução de reCAPTCHA v3 usando CapMonster Cloud:
Criar tarefa:
POST
https://api.capmonster.cloud/createTask
Requisição
{
"clientKey": "API_KEY",
"task": {
"type": "RecaptchaV3TaskProxyless",
"websiteURL": "https://lessons.zennolab.com/captchas/recaptcha/v3.php?level=beta",
"websiteKey": "6Le0xVgUAAAAAIt20XEB4rVhYOODgTl00d8juDob",
"isEnterprise": false,
"minScore": 0.7,
"pageAction": "myverify"
}
}
Resposta
{
"errorId":0,
"taskId":407533072
}
Obter resultado da tarefa:
POST
https://api.capmonster.cloud/getTaskResult
Requisição
{
"clientKey":"API_KEY",
"taskId": 407533072
}
Resposta
{
"errorId":0,
"status":"ready",
"solution": {
"gRecaptchaResponse":"3AHJ_VuvYIBNBW5yyv0zRYJ75VkOKvhKj9_xGBJKnQimF72rfoq3Iy-DyGHMwLAo6a3"
}
}
A documentação detalhada da API e exemplos de integração estão disponíveis em capmonster.cloud.
Conclusão
O reCAPTCHA v3 representa um avanço relevante no equilíbrio entre proteção contra bots e experiência do usuário. Ao mover a verificação totalmente para segundo plano e substituir a lógica binária de pass/fail por uma pontuação de risco mais sofisticada, o recaptcha google v3 permite que as equipes de segurança ajam proporcionalmente — bloqueando bots evidentes, aumentando o atrito para sessões suspeitas e deixando usuários legítimos completamente sem perturbação.
Os trade-offs são reais: interpretar a pontuação exige investimento no backend, ajustar limites leva tempo, e a pegada de privacidade não é trivial sob o GDPR. Mas, para a maioria das aplicações web em produção — especialmente aquelas em que o atrito em login, cadastro ou checkout custa conversões — o upgrade da v2 vale muito a pena.
Pronto para implementar o reCAPTCHA v3 no seu site — ou automatizar seu pipeline de testes em torno dele? Visite o CapMonster Cloud para explorar a resolução de CAPTCHA com IA para reCAPTCHA v3, v2 e Enterprise — com documentação completa da API e exemplos de integração para você começar em poucos minutos.