Captcha API (Google reCAPTCHA v3): Documentação e Guia de Integração para Desenvolvedores

Como o reCAPTCHA funciona

Quando o reCAPTCHA é implantado no seu ambiente, ele interage com seu backend e seu cliente (páginas da web ou aplicativos móveis).

Quando um usuário final visita uma página da web ou usa um aplicativo móvel, os seguintes eventos são acionados em sequência:

1. O cliente carrega a página da web a partir do backend ou inicia o aplicativo móvel.
2. A página da web ou o aplicativo móvel inicializa a API JavaScript do reCAPTCHA ou o SDK móvel, que começa a coletar sinais.
3. Quando o usuário final aciona uma ação protegida pelo reCAPTCHA, como login, a API JavaScript do reCAPTCHA ou o SDK móvel no cliente solicita um veredito ao reCAPTCHA.
4. O reCAPTCHA retorna um token do reCAPTCHA criptografado ao cliente para uso posterior.
5. O cliente envia o token do reCAPTCHA criptografado ao backend para avaliação.
6. O backend envia o token para o endpoint REST siteverify.
7. O reCAPTCHA retorna um veredito ao backend com base no risco avaliado para esta solicitação. Esse veredito consiste em pontuações de 0.0 a 1.0 e códigos de motivo.
8. Dependendo do veredito, você (como desenvolvedor) pode determinar as próximas etapas a serem tomadas para aquela solicitação ou ação específica do usuário.

O diagrama de sequência a seguir mostra a representação gráfica do fluxo de trabalho do reCAPTCHA:

Veja também os diagramas do fluxo de implementação: https://docs.cloud.google.com/recaptcha/docs/implementation-workflow

Chaves da API de CAPTCHA (site key + secret)

Para o reCAPTCHA v3, você registra as chaves no Google reCAPTCHA Admin Console e obtém uma site key (pública) e uma secret key (chave compartilhada usada pelo seu backend). Trate o secret como a credencial do seu servidor: ele é enviado no parâmetro secret para o endpoint de verificação, portanto ele nunca deve ser exposto em código do lado do cliente. Se você vir frases como "captcha api key" ou "api key captcha" na documentação da sua equipe, mapeie-as para a site key do reCAPTCHA (identificador de frontend) e a secret key (credencial de verificação no backend).

Integração do cliente (JavaScript)

O reCAPTCHA v3 é executado sem interromper os usuários e retorna uma pontuação para cada solicitação, em que 1.0 indica maior probabilidade de uma interação legítima e 0.0 indica maior probabilidade de ser um bot. Você executa o reCAPTCHA para ações específicas (por exemplo, login ou signup), e você deve verificar no backend se a action retornada corresponde ao que você esperava. O Google recomenda enviar o token imediatamente ao seu backend junto com a solicitação que você deseja proteger.

Opção A: Vincular a um botão (Modificado para backend JSON)

Carregue a API JavaScript e anexe atributos do reCAPTCHA a um botão. O callback recebe o token. Observação: Para funcionar com os exemplos de backend baseado em JSON abaixo, este script intercepta o envio do formulário e envia uma solicitação JSON em vez de um post padrão de formulário.

<script src="https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY"></script>
    <script>
     function onSubmit(token) {
       // Prevent default form submission and send JSON to backend
       const form = document.getElementById("demo-form");
       const formData = new FormData(form);
       const data = Object.fromEntries(formData.entries());
       data.recaptchaToken = token; // Add token to JSON payload
       fetch("/api/submit", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(data)
       }).then(response => {
         if (response.ok) console.log("Success");
       });
     }
    </script>
    <form id="demo-form">
     <!-- Form fields -->
     <button 
       class="g-recaptcha" 
       data-sitekey="YOUR_SITE_KEY" 
       data-callback="onSubmit" 
       data-action="submit" 
       type="button">
       Submit
     </button>
    </form>

Opção B: Execução programática (Recomendado para APIs/AJAX)

Carregue api.js com ?render=YOUR_SITE_KEY, depois chame grecaptcha.execute() para cada ação que você quer proteger.

<script src="https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY"></script>
    <script>
     async function getTokenAndCallBackend() {
       const token = await new Promise((resolve) => {
         grecaptcha.ready(() => {
           grecaptcha.execute("YOUR_SITE_KEY", { action: "login" }).then(resolve);
         });
       });
       // POST token to your backend, which will call siteverify
       await fetch("/api/login", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ recaptchaToken: token })
       });
     }
    </script>

Verificação da API de CAPTCHA (REST: siteverify)

O endpoint REST de verificação do Google é https://www.google.com/recaptcha/api/siteverify e o método é POST. Você envia secret (obrigatório), response (token obrigatório vindo do cliente) e, opcionalmente, remoteip (o IP do usuário). Os tokens têm restrições de tempo e de replay: cada token é válido por dois minutos e pode ser verificado apenas uma vez.

Exemplo de solicitação REST (curl)

curl -X POST \\
 -d "secret=YOUR_SECRET_KEY" \\
 -d "response=USER_TOKEN" \\
 -d "remoteip=USER_IP_OPTIONAL" \\
 https://www.google.com/recaptcha/api/siteverify

Campos da resposta REST (v3)

Uma resposta bem-sucedida é um objeto JSON que inclui success, além de campos do v3 como score e action, e pode incluir error-codes. Você também verá challenge_ts (timestamp ISO) e hostname (onde o token foi resolvido).

Estrutura de exemplo (os campos variam conforme o cenário):

{
     "success": true,
     "score": 0.7,
     "action": "login",
     "challenge_ts": "2026-02-18T10:00:00Z",
     "hostname": "example.com"
    }

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.

• 1.0: Muito provavelmente uma boa interação (humano).
• 0.0: Muito provavelmente um bot.

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

1. Score alto (> 0.5): Conceda acesso imediatamente.
2. 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.

Você também pode consultar instruções detalhadas para resolver, integrar e testar captchas no nosso site:

• reCAPTCHA v2
• reCAPTCHA v3
• reCAPTCHA Enterprise
• e outros tipos de captcha suportados pelo nosso serviço.

Links úteis

• https://docs.cloud.google.com/recaptcha/docs
• https://docs.cloud.google.com/recaptcha/docs/overview
• https://developers.google.com/recaptcha/docs/v3
• https://developers.google.com/recaptcha/docs/verify

... NB: Observe que o produto é destinado à automação de testes nos seus próprios sites e em sites aos quais você tem acesso legal.