Exemplos no estilo de SDK para backend
Todos estes exemplos fazem a mesma coisa: seu backend recebe um token, chama o endpoint REST siteverify com seu secret e, em seguida, inspeciona a resposta JSON. Especificamente para o reCAPTCHA v3, o Google documenta que você deve validar a action e usar o score para decidir o que fazer em seguida para a solicitação.
Node.js (verificação no servidor)
// Node.js 18+
import express from "express";
const app = express();
app.use(express.json()); // Parses application/json requests
app.post("/api/login", async (req, res) => {
const token = req.body.recaptchaToken;
// Prepare parameters for Google (x-www-form-urlencoded)
const params = new URLSearchParams();
params.set("secret", process.env.RECAPTCHA_SECRET);
params.set("response", token);
const verifyResp = await fetch("https://www.google.com/recaptcha/api/siteverify", {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: params
});
const data = await verifyResp.json();
if (!data.success) {
return res.status(403).json({
error: "recaptcha_failed",
details: data["error-codes"]
});
}
if (data.action !== "login") {
return res.status(403).json({ error: "recaptcha_action_mismatch" });
}
// Choose your own thresholds based on traffic patterns
if (data.score < 0.5) {
return res.status(403).json({
error: "recaptcha_low_score",
score: data.score
});
}
return res.json({ ok: true });
});
app.listen(3000);
A URL do siteverify, o método e os parâmetros são definidos na documentação de verificação do Google. Os campos score e action vêm da documentação do reCAPTCHA v3 do Google.
Python (verificação no servidor)
import os
import requests
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.post("/api/signup")
def signup():
token = request.json.get("recaptchaToken")
r = requests.post(
"https://www.google.com/recaptcha/api/siteverify",
data={
"secret": os.environ["RECAPTCHA_SECRET"],
"response": token,
# "remoteip": request.remote_addr, # optional
},
timeout=5,
)
data = r.json()
if not data.get("success", False):
return jsonify({"error": "recaptcha_failed"}), 403
if data.get("action") != "signup":
return jsonify({"error": "recaptcha_action_mismatch"}), 403
if data.get("score", 0) < 0.5:
return jsonify({"error": "recaptcha_low_score"}), 403
return jsonify({"ok": True})
O endpoint siteverify, os parâmetros obrigatórios e o array error-codes são especificados na documentação de verificação do Google.
JavaScript no navegador (recapitulação da criação de token)
Esta é a parte do fluxo da captcha google api no lado do navegador: execute o reCAPTCHA com uma action e encaminhe o token para seu backend para verificação.
grecaptcha.ready(() => {
grecaptcha.execute("YOUR_SITE_KEY", { action: "submit" }).then(async (token) => {
await fetch("/api/contact", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ recaptchaToken: token })
});
});
});
Modelo de autenticação (o que prova que você pode verificar)
O parâmetro POST secret é a chave compartilhada entre seu site e o reCAPTCHA, e ele autentica sua chamada de verificação servidor-a-servidor para siteverify. Como o token expira rapidamente e é de uso único, você deve verificá-lo prontamente e evitar repetir a verificação com o mesmo token. Se você precisar de um novo token, a orientação do Google é executar novamente o fluxo do reCAPTCHA no lado do cliente.
Tratamento de erros e códigos de erro
No nível de API, a resposta de verificação inclui success e pode incluir error-codes que descrevem o que deu errado. A referência documentada pelo Google para códigos de erro do siteverify está abaixo:
... missing-input-secret: O parâmetro secret está ausente
invalid-input-secret: O parâmetro secret é inválido ou está malformado
missing-input-response: O parâmetro response (token) está ausente
invalid-input-response: O token é inválido ou está malformado...
bad-request: A solicitação é inválida ou está malformada
timeout-or-duplicate: O token não é mais válido (muito antigo) ou já foi usado
Trate erros missing/invalid-* como bugs de configuração ou de solicitação e trate timeout-or-duplicate como uma condição de execução esperada quando tokens expiram ou são repetidos (replay).
Interpretando o Score (0.0 a 1.0)
... Diferentemente do reCAPTCHA v2, o v3 não mostra um desafio (como "clique nos ônibus"). Em vez disso, ele retorna um score.
O Google não bloqueia solicitações automaticamente; cabe à sua lógica de backend interpretar o score. Um limiar inicial comum é 0.5.
Ações recomendadas com base no Score
Score alto (> 0.5): Conceda acesso imediatamente.
Score baixo (< 0.5): Não apenas bloqueie; em vez disso, introduza fricção:
Exigir autenticação de dois fatores (2FA)....
Enviar um e-mail de verificação.
Exibir um desafio visível (como reCAPTCHA v2) como fallback.
Enviar a transação para revisão manual.
Checklist de implementação
Registre as chaves do reCAPTCHA v3 e incorpore a site key na sua integração de frontend
Gere tokens para nomes explícitos de action e envie o token ao seu backend imediatamente
Verifique o token com POST https://www.google.com/recaptcha/api/siteverify usando sua chave secreta
Aplique as restrições do token: verifique em até dois minutos e apenas uma vez por token
Para v3, verifique action e use score para escolher o comportamento da sua resposta
Trate error-codes usando os significados documentados pelo Google (especialmente timeout-or-duplicate)
APIs de Captcha Solver (Automação e Testes)
Observação: esta seção aborda a distinção de "solver API" mencionada na introdução.
Enquanto a "Captcha API" protege seu site, APIs de Captcha Solver (como CapMonster Cloud) são serviços usados por desenvolvedores para automatizar testes ou por software que precisa contornar CAPTCHAs. Esses serviços usam IA ou trabalhadores humanos para gerar tokens válidos que imitam usuários reais.
Se você estiver criando uma suíte de testes automatizados ou um scraper e precisar contornar o reCAPTCHA v3, você usaria uma solver API para obter um token e, em seguida, enviá-lo ao site de destino como um navegador faria.
... Para mais detalhes e exemplos de integração com o CapMonster Cloud, consulte sua documentação oficial da API.
Links úteis
