Quando usar reCAPTCHA v2 ou v3
Responder à pergunta reCAPTCHA v2 vs v3: qual é melhor depende inteiramente do seu contexto. Nenhuma das versões é universalmente superior.
Escolha o reCAPTCHA v2 quando:
- O formulário for de alto risco (login, pagamento, criação de conta) e a confirmação explícita do usuário agregar valor
- Você quiser uma lógica simples no backend — verificar o token, sem interpretar pontuação
- Sua base de usuários for menos sensível a atrito (ferramentas B2B, painéis administrativos)
- Você precisar de um desafio de fallback com bloqueio rígido para usuários que falham em uma verificação de pontuação do v3
Escolha o reCAPTCHA v3 quando:
- Experiência do usuário e taxa de conversão forem prioridades (e-commerce, landing pages, onboarding de SaaS)
- Você quiser proteger várias ações da página sem interromper o usuário
- Você tiver capacidade no backend para interpretar pontuações e aplicar respostas em camadas (permitir / desafiar / bloquear)
- Você quiser inteligência passiva contra bots ao longo de toda a sessão do usuário
A abordagem híbrida recomendada:
- Implante o v3 em todas as ações protegidas
- Se um usuário ficar abaixo do seu threshold (por exemplo, abaixo de 0.5), apresente um desafio invisible v2
- Se isso também falhar, bloqueie ou encaminhe para revisão manual
Isso combina a fluidez de UX do v3 com a capacidade de bloqueio rígido do v2.
Guia de implementação — reCAPTCHA v2
Etapa 1: registre sua site key
Acesse o Google Console de Administração do reCAPTCHA, selecione reCAPTCHA v2 ("I'm not a robot" Checkbox) e adicione seu domínio. Você receberá uma site key (pública) e uma secret key (privada — apenas servidor, nunca exponha no lado do cliente).
Etapa 2: frontend — widget Checkbox
<!DOCTYPE html>
<html>
<head>
<title>Demo do reCAPTCHA v2</title>
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
</head>
<body>
<form action="/submit" method="POST">
<input type="text" name="email" placeholder="Seu email" required />
<div class="g-recaptcha" data-sitekey="YOUR_SITE_KEY"></div>
<br/>
<input type="submit" value="Enviar">
</form>
</body>
</html>
Etapa 3: frontend — variante Invisible v2
<!DOCTYPE html>
<html>
<head>
<title>Demo do reCAPTCHA v2 Invisible</title>
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
<script>
function onSubmit(token) {
document.getElementById("demo-form").submit();
}
</script>
</head>
<body>
<form id="demo-form" action="/submit" method="POST">
<input type="text" name="email" placeholder="Seu email" required />
<button class="g-recaptcha"
data-sitekey="YOUR_SITE_KEY"
data-callback="onSubmit"
data-badge="bottomright">
Enviar
</button>
</form>
</body>
</html>
Etapa 4: verificação no backend (PHP)
<?php
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
http_response_code(405);
exit('Método não permitido');
}
$token = $_POST['g-recaptcha-response'] ?? '';
$secret = 'YOUR_SECRET_KEY';
if (!$token) {
exit('Token de CAPTCHA ausente.');
}
// Use POST para evitar expor a secret key em logs de servidor/proxy
$postData = http_build_query([
'secret' => $secret,
'response' => $token,
]);
$context = stream_context_create([
'http' => [
'method' => 'POST',
'header' => 'Content-Type: application/x-www-form-urlencoded',
'content' => $postData,
],
]);
$response = file_get_contents(
'https://www.google.com/recaptcha/api/siteverify',
false,
$context
);
if ($response === false) {
http_response_code(503);
exit('Não foi possível acessar o serviço de verificação do reCAPTCHA.');
}
$result = json_decode($response, true);
if (!empty($result['success'])) {
echo "<p>Formulário enviado com sucesso!</p>";
} else {
http_response_code(403);
echo "<p>Falha na verificação do CAPTCHA. Tente novamente.</p>";
}
?>
Guia de implementação — reCAPTCHA v3
Etapa 1: registre uma site key v3
No Console de Administração do reCAPTCHA, selecione reCAPTCHA v3. Você receberá chaves separadas de quaisquer chaves v2 — não as misture entre versões.
Etapa 2: frontend — execução programática do token
<!DOCTYPE html>
<html>
<head>
<title>Demo do reCAPTCHA v3</title>
<script src="https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY"></script>
</head>
<body>
<form id="login-form">
<input type="email" name="email" placeholder="Email" required />
<input type="password" name="password" placeholder="Senha" required />
<button type="button" onclick="submitWithRecaptcha()">Entrar</button>
</form>
<script>
async function submitWithRecaptcha() {
// Os tokens expiram após 2 minutos -- execute imediatamente antes do envio
const token = await new Promise((resolve) => {
grecaptcha.ready(() => {
grecaptcha.execute('YOUR_SITE_KEY', { action: 'login' }).then(resolve);
});
});
const response = await fetch('/api/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
email: document.querySelector('[name="email"]').value,
recaptchaToken: token
})
});
const data = await response.json();
if (data.ok) {
alert('Login realizado com sucesso!');
} else {
alert('Falha na verificação: ' + (data.error || 'erro desconhecido'));
}
}
</script>
</body>
</html>
Etapa 3: verificação no backend (Node.js / Express)
// Node.js 18+ com Express
import express from 'express';
const app = express();
app.use(express.json());
app.post('/api/login', async (req, res) => {
const { recaptchaToken } = req.body;
const params = new URLSearchParams();
params.set('secret', process.env.RECAPTCHA_SECRET);
params.set('response', recaptchaToken);
try {
const verifyRes = await fetch('https://www.google.com/recaptcha/api/siteverify', {
method: 'POST',
headers: { 'content-type': 'application/x-www-form-urlencoded' },
body: params
});
const data = await verifyRes.json();
if (!data.success) {
return res.status(403).json({ error: 'recaptcha_failed', codes: data['error-codes'] });
}
// Sempre valide se a action corresponde ao que você esperava
if (data.action !== 'login') {
return res.status(403).json({ error: 'recaptcha_action_mismatch' });
}
// 0.5 é o threshold inicial recomendado pelo Google -- ajuste com base no seu tráfego
if (data.score < 0.5) {
return res.status(403).json({ error: 'recaptcha_low_score', score: data.score });
}
return res.json({ ok: true });
} catch (err) {
return res.status(503).json({ error: 'recaptcha_service_unavailable' });
}
});
app.listen(3000, () => console.log('Servidor em execução na porta 3000'));
Automatizando a resolução de reCAPTCHA com CapMonster Cloud
Ao criar automação de testes, pipelines de QA ou fluxos autorizados de web scraping, você precisa de uma forma de lidar com desafios de reCAPTCHA programaticamente — sem quebrar sua suíte de testes toda vez que um CAPTCHA aparece. CapMonster Cloud é um serviço automatizado de resolução de CAPTCHA que oferece suporte a reCAPTCHA v2 e v3, fornecendo uma API baseada em tokens que se integra com facilidade a qualquer stack tecnológica.
Importante: O CapMonster Cloud destina-se ao uso em sites e plataformas aos quais você tem acesso autorizado — para testes, automação de QA e fluxos autorizados de scraping.
Resolvendo reCAPTCHA v2 via API do CapMonster Cloud
Requisição para criar tarefa:
POST https://api.capmonster.cloud/createTask
{
"clientKey": "YOUR_API_KEY",
"task": {
"type": "RecaptchaV2Task",
"websiteURL": "https://example.com/login",
"websiteKey": "YOUR_SITE_KEY"
}
}
Resposta
{
"errorId":0,
"taskId":407533072
}
Consultar resultado:
POST https://api.capmonster.cloud/getTaskResult
{
"clientKey": "YOUR_API_KEY",
"taskId": 407533072
}
Resposta (quando estiver pronta):
{
"errorId": 0,
"status": "ready",
"solution": {
"gRecaptchaResponse": "03AFcWeA66ZARdA5te7ac..."
}
}
Resolvendo reCAPTCHA v3 via API do CapMonster Cloud
POST https://api.capmonster.cloud/createTask
{
"clientKey": "YOUR_API_KEY",
"task": {
"type": "RecaptchaV3TaskProxyless",
"websiteURL": "https://example.com/login",
"websiteKey": "YOUR_SITE_KEY",
"isEnterprise": false,
"minScore": 0.7,
"pageAction": "login"
}
}
As etapas seguintes são semelhantes às do v2.
Exemplo de SDK (Python — reCAPTCHA v3)
# https://github.com/CapMonsterCloud/capmonstercloud-client-python
import asyncio
from capmonstercloudclient import CapMonsterClient, ClientOptions
from capmonstercloudclient.requests import RecaptchaV3ProxylessRequest
client_options = ClientOptions(api_key="YOUR_API_KEY") # Especifique sua chave de API do CapMonster Cloud
cap_monster_client = CapMonsterClient(options=client_options)
# Opcionalmente, você pode verificar o saldo
balance = asyncio.run(cap_monster_client.get_balance())
print("Saldo:", balance)
recaptcha_v3_request = RecaptchaV3ProxylessRequest(
websiteUrl="https://lessons.zennolab.com/captchas/recaptcha/v3.php?level=beta", # URL da sua página com captcha
websiteKey="6Le0xVgUAAAAAIt20XEB4rVhYOODgTl00d8juDob",
minScore=0.6,
pageAction="myverify"
)
async def solve_captcha():
return await cap_monster_client.solve_captcha(recaptcha_v3_request)
responses = asyncio.run(solve_captcha())
print(responses)
Exemplo de SDK (Node.js — reCAPTCHA v2)
// https://github.com/CapMonsterCloud/capmonstercloud-client-js
import { CapMonsterCloudClientFactory, ClientOptions, RecaptchaV2Request } from '@zennolab_com/capmonstercloud-client';
const API_KEY = "YOUR_API_KEY"; // Especifique sua chave de API do CapMonster Cloud
async function solveRecaptchaV2() {
const client = CapMonsterCloudClientFactory.Create(
new ClientOptions({ clientKey: API_KEY })
);
// Exemplo básico sem proxy
// O CapMonster Cloud usa automaticamente seus próprios proxies
let recaptcha2Request = new RecaptchaV2Request({
websiteURL: "https://lessons.zennolab.com/captchas/recaptcha/v2_simple.php?level=high",
websiteKey: "6Lcg7CMUAAAAANphynKgn9YAgA4tQ2KI_iqRyTwd"
});
// Exemplo de uso do seu próprio proxy
// Descomente este bloco se quiser usar seu próprio proxy
/*
const proxy = {
proxyType: "http",
proxyAddress: "123.45.67.89",
proxyPort: 8080,
proxyLogin: "username",
proxyPassword: "password"
};
recaptcha2Request = new RecaptchaV2Request({
websiteURL: "https://lessons.zennolab.com/captchas/recaptcha/v2_simple.php?level=high",
websiteKey: "6Lcg7CMUAAAAANphynKgn9YAgA4tQ2KI_iqRyTwd",
proxy,
userAgent: "userAgentPlaceholder"
});
*/
// Opcionalmente, você pode verificar o saldo
const balance = await client.getBalance();
console.log("Saldo:", balance);
const result = await client.Solve(recaptcha2Request);
console.log("Solução:", result);
}
solveRecaptchaV2().catch(console.error);
O CapMonster Cloud também oferece suporte a reCAPTCHA Enterprise, Cloudflare Turnstile e vários outros tipos de CAPTCHA — o que o torna uma ferramenta versátil para qualquer infraestrutura de testes que interaja com formulários protegidos por CAPTCHA.