Como implementar a API reCAPTCHA: guia passo a passo para desenvolvedores React

Entendendo a API reCAPTCHA e os conceitos principais

Compreender os conceitos centrais e as diferentes versões da API reCAPTCHA cria uma base sólida para a implementação. O Google oferece essa tecnologia como uma camada essencial de segurança para ajudar sites a distinguir entre usuários humanos e bots automatizados.

Visão geral do Google reCAPTCHA v2 e v3

O Google oferece o reCAPTCHA em duas versões principais (v2 e v3), além de uma edição Enterprise para proteção avançada. Cada versão funciona de maneira diferente:

O reCAPTCHA v2 exige que os usuários interajam diretamente por meio da conhecida caixa de seleção “Não sou um robô”. Quando detecta atividade suspeita, o sistema pode exibir desafios visuais pedindo que os usuários identifiquem objetos específicos em imagens.
O reCAPTCHA v3 é executado silenciosamente em segundo plano, sem qualquer interação do usuário. Em vez de interromper os usuários com desafios, ele monitora o comportamento e atribui a cada interação uma pontuação de risco.

Ambas as versões exigem um par de chaves: uma chave de site (site key) para a implementação no frontend e uma chave secreta (secret key) para a verificação no backend.

Como o reCAPTCHA protege contra bots

O reCAPTCHA atua como um teste de Turing para diferenciar humanos de sistemas automatizados. O sistema de proteção usa estes componentes:

Mecanismo de análise de risco – Um sistema sofisticado e adaptável analisa o comportamento do usuário para identificar atividades potencialmente maliciosas.
Detecção baseada em pontuação – O v3 atribui pontuações de risco com base em padrões de comportamento. Os proprietários de sites podem tomar ações personalizadas com base nessas pontuações.
Inteligência global – O sistema utiliza a inteligência de fraude em escala Google, coletada a partir de bilhões de usuários em milhões de sites e trilhões de transações.

Quando detecta atividade suspeita, o reCAPTCHA pode apresentar desafios ou bloquear completamente determinadas interações. Isso protege os sites ao mesmo tempo em que minimiza a interrupção para usuários legítimos.

Como escolher entre reCAPTCHA v2 e v3 para o seu caso de uso

Suas necessidades específicas devem orientar a escolha entre v2 e v3:

Escolha o v2 quando:

Você quiser uma confirmação visível de presença humana.
Seu site precisar de pontos de verificação explícitos (como envio de formulários).
Você preferir mecanismos tradicionais de desafio-resposta.

Escolha o v3 quando:

A experiência do usuário for prioridade máxima e você quiser evitar interrupções.
Você precisar de pontuações de risco detalhadas para políticas de segurança personalizadas.
Seu site tiver vários pontos de interação que precisem ser monitorados.

Suas capacidades técnicas de implementação e seus requisitos de segurança também devem desempenhar um papel importante nessa decisão.

Configurando chaves da API reCAPTCHA e parâmetros

Você precisará obter suas credenciais junto ao Google para começar a configurar a API reCAPTCHA. Vamos percorrer o processo de registro do seu site e de obtenção das chaves necessárias.

Registrando seu site no Google reCAPTCHA Admin Console

Veja como registrar seu site no Google reCAPTCHA Admin Console:

Acesse o Google reCAPTCHA Admin Console.
Faça login com as credenciais da sua conta Google.
Clique em “+” ou no botão “Register a new site”.
Insira um rótulo descritivo para identificar seu site com facilidade.
Selecione o tipo adequado de reCAPTCHA (v2 ou v3), com base nas suas necessidades.
Adicione o(s) domínio(s) em que o reCAPTCHA será usado.
Aceite os Termos de Serviço.
Clique em “Submit” para concluir o registro.

Gerando a site key e a secret key

Depois do registro, o Google gera duas chaves:

Site Key: você a utilizará no frontend para exibir o widget do reCAPTCHA.
Secret Key: seu servidor precisa dela para verificar as respostas dos usuários.

Essas chaves funcionam em conjunto para proteger seu site. A site key informa ao serviço reCAPTCHA do Google qual site é o seu, enquanto a secret key permite que seu backend se comunique com segurança com os servidores do Google para verificar as respostas.

Armazenando secret keys com segurança usando arquivos .env

Sua secret key é fundamental para as requisições de verificação. Você nunca deve colocar essa chave no código-fonte nem expô-la em código do lado do cliente.

A melhor forma de armazenar essas chaves é como variáveis de ambiente em arquivos .env:

# .env file
GOOGLE_RECAPTCHA_KEY=your_site_key_here
GOOGLE_RECAPTCHA_SECRET=your_secret_key_here

Sua aplicação pode então acessar essas variáveis:

Em Node.js: process.env.GOOGLE_RECAPTCHA_KEY
Em PHP: $_ENV['GOOGLE_RECAPTCHA_KEY']

Certifique-se de adicionar seus arquivos .env ao .gitignore para não cometer acidentalmente informações sensíveis no seu repositório.

Você sempre pode voltar ao Admin Console para alterar depois configurações como domínios ou prioridades de segurança.

Integração de frontend com reCAPTCHA v2 em React

Depois de obter suas chaves de API, o próximo passo importante é integrar o reCAPTCHA v2 à sua aplicação React. Essa configuração de frontend faz com que seu site exiba com eficiência o desafio de verificação para os usuários.

Instalando o react-google-recaptcha via npm

Seu projeto precisa de um componente React especializado para o Google reCAPTCHA v2. Execute este comando no terminal:

npm install --save react-google-recaptcha

Esse pacote fornece um componente React projetado especificamente para integrar o reCAPTCHA v2.

Renderizando o componente ReCAPTCHA com a site key

Depois da instalação, o componente precisa ser importado no arquivo que contém seu formulário:

import ReCAPTCHA from "react-google-recaptcha";
import { useRef } from "react";

function ContactForm() {
  const captchaRef = useRef(null);

  return (
    <form>
      {/* Form fields */}
      <ReCAPTCHA
        sitekey={process.env.REACT_APP_SITE_KEY}
        ref={captchaRef}
      />
      <button type="submit">Submit</button>
    </form>
  );
}

A propriedade sitekey vincula seu componente à chave de API gerada anteriormente.

Tratando o token com o callback onChange

O reCAPTCHA cria um token de resposta que você precisa enviar para o backend quando a verificação é concluída com sucesso:

function onChange(value) {
  console.log("Captcha value:", value);
  // Store token or submit form
}

// Add to component props
<ReCAPTCHA
  sitekey={process.env.REACT_APP_SITE_KEY}
  onChange={onChange}
  ref={captchaRef}
/>

O token precisa ser obtido e redefinido durante o envio do formulário:

const handleSubmit = (e) => {
  e.preventDefault();
  const token = captchaRef.current.getValue();
  captchaRef.current.reset(); // Reset after use
  // Send token to backend
};

Usando o parâmetro “hl” para internacionalização

O idioma do widget pode ser personalizado com a propriedade hl em sites multilíngues:

<ReCAPTCHA
  sitekey={process.env.REACT_APP_SITE_KEY}
  onChange={onChange}
  hl="fr" // Idioma francês
/>

Os códigos de idioma ajudam a renderizar o widget em idiomas específicos e aprimoram a experiência dos seus usuários internacionais.

Verificação no backend com a API Google reCAPTCHA

Depois que o frontend captura o token do reCAPTCHA, o backend precisa verificar a autenticidade desse token. Essa etapa de verificação determina se os usuários podem prosseguir com as ações pretendidas.

Requisição POST para https://www.google.com/recaptcha/api/siteverify

Seu backend precisa enviar uma requisição POST ao endpoint de verificação do Google para checar o token. A requisição exige dois parâmetros principais:

Parâmetros de POST: https://www.google.com/recaptcha/api/siteverify

secret: sua secret key do reCAPTCHA.
response: o token recebido do frontend.
remoteip: (opcional) o endereço IP do usuário.

O endpoint funciona com requisições GET e POST, mas POST oferece mais segurança.

Validando o token usando a secret key

Você nunca deve expor sua secret key. A prática recomendada é armazená-la em variáveis de ambiente, e não diretamente no código da aplicação:

// Exemplo em Node.js
const verifyRecaptcha = async (token) => {
  const response = await fetch("https://www.google.com/recaptcha/api/siteverify", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      secret: process.env.RECAPTCHA_SECRET,
      response: token,
    }).toString(),
  });
  return await response.json();
};

O uso de URLSearchParams garante que todos os parâmetros sejam codificados corretamente na URL, evitando erros ao lidar com caracteres especiais no token.

Tratando respostas de sucesso e falha

A API retorna um objeto JSON, cuja estrutura difere para o v2 e o v3.

Para o reCAPTCHA v2:

success: valor booleano que indica o status da verificação.
challenge_ts: carimbo de data/hora da verificação.
hostname: site em que o reCAPTCHA foi resolvido.
error-codes: array de mensagens de erro (se houver).

Para o reCAPTCHA v3 (além dos campos do v2):

score: valor de 0,0 a 1,0 indicando a legitimidade da interação (em que 1,0 significa alta probabilidade de um usuário legítimo).
action: nome da ação especificada ao gerar o token.

Exemplo de processamento de resposta para v2:

const result = await verifyRecaptcha(token);
if (result.success) {
  // Prosseguir com o processamento do formulário
} else {
  // Tratar falha de verificação
  console.error("Verification failed:", result["error-codes"]);
}

Exemplo de processamento de resposta para v3, com verificação de pontuação:

const result = await verifyRecaptcha(token);
if (result.success && result.score > 0.5 && result.action === "login") {
  // Prosseguir com o processamento do formulário
} else if (result.success && result.score <= 0.5) {
  // Pontuação baixa – possível bot
  console.warn("Low score detected:", result.score);
} else {
  // Falha na verificação
  console.error("Verification failed:", result["error-codes"]);
}

Tratamento de códigos de erro:

O array error-codes pode conter os seguintes valores:

missing-input-secret: o parâmetro secret está ausente.
invalid-input-secret: o parâmetro secret é inválido ou está incorreto.
missing-input-response: o parâmetro de resposta (token) está ausente.
invalid-input-response: o parâmetro de resposta é inválido ou expirou.
bad-request: a requisição é inválida ou está malformada.
timeout-or-duplicate: o token já foi usado ou expirou.

Exemplo de processamento completo com error-codes:

const result = await verifyRecaptcha(token);
if (result.success) {
  // Sucesso – prosseguir com o processamento do formulário
  return { verified: true };
} else {
  // Tratar códigos de erro específicos
  const errors = result["error-codes"] || [];
  if (errors.includes("timeout-or-duplicate")) {
    return { verified: false, message: "Token expirado. Tente novamente." };
  } else if (errors.includes("invalid-input-response")) {
    return { verified: false, message: "Token de verificação inválido." };
  } else if (errors.includes("missing-input-secret") || errors.includes("invalid-input-secret")) {
    console.error("Server configuration error:", errors);
    return { verified: false, message: "Erro no servidor. Entre em contato com o suporte." };
  } else {
    return { verified: false, message: "Falha na verificação. Tente novamente." };
  }
}

Expiração do token e restrição de uso único

Cada token do reCAPTCHA dura dois minutos e só pode ser usado uma vez. A experiência do usuário melhora com estas estratégias de renovação de token:

Criar novos tokens imediatamente antes do envio do formulário.
Configurar renovação automática de token para formulários longos.
Exibir mensagens de erro amigáveis quando os tokens expirarem.

Testando o reCAPTCHA com o CapMonster Cloud

CapMonster Cloud fornece resolução automatizada de reCAPTCHA para testes, QA e ambientes de desenvolvimento. O serviço resolve programaticamente reCAPTCHA v2, v3 e Enterprise via REST API, retornando tokens que sua aplicação aceita como se fossem tokens de usuários reais.

Isso possibilita testes abrangentes de formulários protegidos, pipelines de CI/CD e testes de carga sem resolução manual. Equipes de QA podem validar implementações em diferentes cenários e faixas de pontuação, enquanto desenvolvedores testam lógica de verificação, tratamento de erros e comportamento de expiração de tokens.

O CapMonster Cloud se integra por meio de chamadas de API simples, com suporte a frameworks populares como Selenium, Puppeteer e Playwright. Ele elimina o atrito constante de CAPTCHA durante o desenvolvimento, ao mesmo tempo em que valida sua integração com o Google reCAPTCHA, acelerando os ciclos de desenvolvimento antes da implantação em produção.

Exemplo de resolução do reCAPTCHA v3 com Playwright e a biblioteca oficial Node.js da CapMonster Cloud

▶ Mostrar código


const { chromium } = require('playwright');
const { 
  CapMonsterCloudClientFactory, 
  ClientOptions, 
  RecaptchaV3ProxylessRequest 
} = require('@zennolab_com/capmonstercloud-client');

(async () => {
  const TARGET_URL = 'https://lessons.zennolab.com/captchas/recaptcha/v3.php?level=beta';
  const SITE_KEY = '6Le0xVgUAAAAAIt20XEB4rVhYOODgTl00d8juDob';
  const API_KEY = 'your_capmonster_cloud_api_key';

  const cmcClient = CapMonsterCloudClientFactory.Create(
    new ClientOptions({ clientKey: API_KEY })
  );

  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();
  await page.goto(TARGET_URL, { waitUntil: 'domcontentloaded' });

  const recaptchaRequest = new RecaptchaV3ProxylessRequest({
    websiteURL: TARGET_URL,
    websiteKey: SITE_KEY,
    minScore: 0.6,
    pageAction: 'myverify',
  });

  const solution = await cmcClient.Solve(recaptchaRequest);
  const token = solution.solution?.gRecaptchaResponse;

  if (!token) {
    console.error('O token está vazio, verifique o sitekey e a URL');
    await browser.close();
    return;
  }

  console.log('Token recebido:', token);

  await page.evaluate((t) => {
    const input = document.querySelector('#v3_token');
    if (input) input.value = t;

    const form = document.querySelector('#v3_form');
    if (form) {
      form.submit();
      return;
    }

    if (typeof window.onSubmit === 'function') {
      window.onSubmit(t);
      return;
    }

    if (window.___grecaptcha_cfg) {
      const clients = window.___grecaptcha_cfg.clients;
      for (const clientKey in clients) {
        const client = clients[clientKey];
        for (const prop in client) {
          const cb = client[prop]?.callback;
          if (typeof cb === 'function') {
            cb(t);
            return;
          }
        }
      }
    }

    console.warn('Formulário e callback não encontrados');
  }, token);

  console.log('Token inserido e callback executado (se disponível)');

  await page.waitForTimeout(5000);
  await browser.close();
})();

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

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

Conclusão

A API Google reCAPTCHA protege seus sites contra ataques automatizados e melhora a experiência do usuário. Este artigo mostrou como configurar e integrar essa ferramenta de segurança de ponta a ponta.

As principais diferenças entre reCAPTCHA v2 e v3 ajudam você a escolher a versão adequada. O v2 usa uma interface visível de caixa de seleção para verificação, enquanto o v3 atribui silenciosamente pontuações de risco sem interromper os usuários.

A base da sua implementação depende da configuração correta das chaves de API. A experiência demonstra que variáveis de ambiente mantêm suas secret keys seguras e preservam a integridade do sistema de verificação. Essas chaves nunca devem aparecer no código-fonte nem em repositórios.

Aplicações React precisam de componentes específicos para adicionar o reCAPTCHA. O processo de verificação no backend então fecha o ciclo de segurança comprovando os tokens por meio do endpoint de verificação do Google.

Os tokens do reCAPTCHA têm limites bem definidos – expiram após dois minutos e funcionam apenas uma vez. Você precisa de estratégias adequadas de gerenciamento de tokens para garantir uma experiência fluida.

Agora você tem tudo de que precisa para construir uma solução de reCAPTCHA robusta. Essa abordagem reduz significativamente o tráfego de bots e o abuso automatizado em seus sites, mantendo a interação simples para usuários legítimos. Esse equilíbrio entre segurança e usabilidade representa a forma ideal de implementar a tecnologia reCAPTCHA no mundo digital atual, repleto de bots.