logo
bars
///
Bypass do reCAPTCHA v2: guia de resolução
Kira Pridantseva
Kira Pridantseva
Editora técnica
November 16, 2026
14 min

 

Bypass do reCAPTCHA v2: guia de resolução


Em testes automatizados, o bypass do reCAPTCHA v2 envolve duas etapas: obter um token de resposta válido e enviá-lo com o formulário. O serviço resolve o desafio e devolve o token, e o teste o entrega da mesma forma que o widget. Antes de aceitar a requisição, o backend ainda verifica o token com o Google. Este guia apresenta os dois tipos de widget, mostra onde encontrar os parâmetros e explica como usar o CapMonster Cloud com Python e JavaScript. 

robots
Comece agora e automatize sua solução reCAPTCHA v2

Pontos principais

  • Na prática, você precisa obter um token de resposta válido e enviá-lo com o formulário. O backend ainda verifica o token com o Google.
  • No widget com caixa de seleção, a verificação começa quando o usuário marca a caixa. Na versão invisível, a verificação é acionada por um botão ou pelo código da aplicação. Quando o token chega, um callback dá continuidade ao envio.
  • O token padrão do reCAPTCHA v2 expira em dois minutos e só pode ser verificado uma vez. O token do CapMonster Cloud vale por 60 segundos após a resolução do desafio. Use-o assim que receber o resultado.
  • Uma tarefa RecaptchaV2Task precisa apenas do tipo da tarefa, da URL da página e da chave do site. Proxy, User-Agent e cookies são opcionais. O CapMonster Cloud documenta requisitos adicionais para esses dados em algumas integrações.
  • Um token válido por si só não garante que a aplicação aceite o formulário. Registre separadamente o resultado do serviço, o resultado da verificação pelo Google e o desfecho do envio.

Definições

  • Chave do site (websiteKey). Chave pública que identifica a integração do reCAPTCHA e define qual widget a página vai renderizar. Na API do CapMonster Cloud, o campo se chama websiteKey.
  • g-recaptcha-response. Campo do formulário que contém o token de resposta gerado pelo reCAPTCHA. O widget guarda o token em um textarea oculto com esse nome, e o backend usa esse valor para verificar a resposta com o Google.
  • data-s. Valor adicional de uso único que algumas integrações personalizadas do reCAPTCHA v2 incluem no HTML do widget. É um valor distinto da chave pública e do token de resposta.
  • isInvisible. Campo booleano opcional da API do CapMonster Cloud. O valor true indica que a tarefa é para um widget invisível do reCAPTCHA v2.
  • Tarefa. Requisição que o CapMonster Cloud processa de forma assíncrona. Cada tarefa aceita recebe um ID que permite consultar o status ou recuperar o resultado.
  • Validade do token. Período em que o token de resposta pode ser verificado. Um token de uso único não pode ser verificado novamente, mesmo que ainda esteja dentro do prazo.

reCAPTCHA v2 com caixa de seleção e reCAPTCHA v2 invisível

A principal diferença entre os dois tipos de widget do reCAPTCHA v2 está na forma de iniciar a verificação. No widget com caixa de seleção, o usuário clica em “Não sou um robô”. O Google pode aceitar o clique de imediato ou pedir que o usuário resolva um desafio. Quando a verificação é concluída com sucesso, o widget grava o token em um campo oculto, e o formulário o envia junto com os outros dados.

Na versão invisível, não há caixa de seleção. A verificação começa quando o usuário clica em um botão da própria página, como Submit, ou quando a aplicação a aciona via JavaScript. O Google ainda pode exibir um desafio.

A configuração do widget permite identificar a versão. Para ativar o modo invisível, use data-size="invisible" no HTML ou size: "invisible" nas opções do JavaScript. Esse modo também usa um callback. Quando a verificação passa, o Google entrega o token à função indicada em data-callback ou passada como callback para grecaptcha.render(). A partir daí, o código da aplicação define o que acontece. Em uma integração típica, a função dá continuidade ao envio do formulário. O widget com caixa de seleção também pode ter callback, embora um formulário padrão consiga ser enviado sem ele.

A verificação no servidor funciona da mesma forma nas duas versões. O backend envia o token ao Google antes de aceitar a requisição protegida. Se você for adicionar o widget a um formulário, veja como integrar o reCAPTCHA v2 ao seu site. A versão Enterprise tem uma configuração de chaves própria, detalhada no guia do reCAPTCHA Enterprise.

Como funciona o bypass do reCAPTCHA v2

O serviço resolve o desafio no lugar do usuário. O restante do fluxo segue da mesma forma, do widget ao servidor.

  • Widget. O widget do reCAPTCHA inicia a verificação no navegador. O Google pode pedir que o usuário resolva um desafio.
  • Token de resposta. Quando a verificação passa, o widget devolve um token que a página envia junto com o formulário. Quando o solucionador de reCAPTCHA v2 do CapMonster Cloud resolve o desafio, o token vem no resultado da tarefa.
  • Verificação no servidor. O backend da aplicação envia o token e a chave secreta ao Google. A aplicação decide se aceita o envio com base na resposta do Google e nas regras do próprio formulário.

Validade do token

Pelas regras de verificação no servidor do Google, o token de resposta padrão do reCAPTCHA v2 expira em dois minutos e só pode ser verificado uma vez. O CapMonster Cloud informa que o token que entrega vale por 60 segundos a partir do momento em que resolve o desafio. Use o token assim que recebê-lo.

O que registrar nos testes de QA

Registre separadamente o resultado do solucionador de reCAPTCHA v2, o resultado da verificação pelo Google e o desfecho do envio do formulário. Assim fica mais fácil identificar onde a requisição falhou. Veja também os métodos para resolver o reCAPTCHA v2 em 2026.

Como encontrar os parâmetros

Você precisa da chave pública do site, do modo do widget e do valor de data-s, se a integração usar esse atributo. É possível encontrar esses dados manualmente no DevTools.

Verificação manual

Abra a página com o widget, clique com o botão direito no CAPTCHA e selecione Inspect.

Na aba Elements, localize o contêiner do widget, que costuma ser um div com a classe g-recaptcha. O atributo data-sitekey contém a chave pública que você passa em websiteKey. Se o elemento tiver data-size="invisible", a página usa a versão invisível. Algumas integrações personalizadas também incluem data-s. Quando o atributo estiver presente, passe seu valor em recaptchaDataSValue e obtenha um novo valor a cada tarefa, pois ele é de uso único. Se a aplicação renderizar o widget via JavaScript, procure as opções sitekey e size passadas para grecaptcha.render().

Na aba Network, recarregue a página e localize a requisição ao endpoint anchor do reCAPTCHA. O parâmetro k contém a chave do site. Se a página usa v2, size=invisible na mesma requisição confirma o modo invisível. Essa verificação ajuda quando a chave não aparece no HTML. O reCAPTCHA v3 também pode carregar um widget invisível, por isso esse parâmetro só indica o modo quando você já sabe que a página usa v2.

Verificação automatizada

O exemplo com Playwright abaixo parte de uma estrutura específica: o iframe anchor do Google e os atributos de dados no contêiner do widget. O script lê a chave do site e o modo do widget. Em integrações que incluem o valor opcional data-s, ele também mostra esse valor. Se a página renderizar o widget de outra forma, ajuste os seletores à estrutura dela.

import { chromium } from "playwright";

(async () => {
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();

  await page.goto("https://example.com");

  await page.waitForSelector('iframe[src^="https://www.google.com/recaptcha/api2/anchor?"]');

  const captchaData = await page.evaluate(() => {
    const iframeEl = document.querySelector('iframe[src^="https://www.google.com/recaptcha/api2/anchor?"]');
    const captchaUrl = iframeEl?.getAttribute("src");

    if (captchaUrl) {
      const urlParams = new URLSearchParams(captchaUrl.split("?")[1]);
      const sitekey = urlParams.get("k");
      const size = urlParams.get("size");
      const isInvisible = size === "invisible";

      const sitekeyEl = document.querySelector("[data-sitekey]");
      const datasEl = document.querySelector("[data-s]");
      const datas = datasEl?.getAttribute("data-s");

      return {
        sitekey: sitekey || sitekeyEl?.getAttribute("data-sitekey"),
        datas,
        isInvisible,
      };
    }
    return null;
  });

  console.log(captchaData);
  await browser.close();
})();

Como resolver o reCAPTCHA v2 com a API do CapMonster Cloud

O CapMonster Cloud resolve o reCAPTCHA v2 padrão com o tipo de tarefa RecaptchaV2Task. Crie a tarefa com createTask e consulte o resultado com getTaskResult. O serviço processa a tarefa de forma assíncrona. A verificação e as regras de negócio da aplicação continuam determinando o que acontece com a requisição do formulário. Os parâmetros abaixo seguem a documentação da RecaptchaV2Task.

ParâmetroObrigatoriedadeDescrição
typeObrigatórioTipo de tarefa. Use RecaptchaV2Task.
websiteURLObrigatórioURL da página com reCAPTCHA v2.
websiteKeyObrigatórioChave pública do site para o widget do reCAPTCHA v2.
recaptchaDataSValueOpcionalString. Valor data-s de uso único usado em algumas implementações personalizadas do reCAPTCHA v2. Obtenha um novo valor a cada tarefa.
userAgentOpcionalString. User-Agent do navegador usado na emulação. Use uma identificação de navegador moderno. O CapMonster Cloud publica o valor compatível atual. Consulte as notas de configuração abaixo.
cookiesOpcionalString. Cookies adicionais para a interação com a página de destino ou com o Google. Formato: name1=value1; name2=value2.
isInvisibleOpcionalBooleano. Use true para o reCAPTCHA v2 invisível.
proxyTypeOpcionalString. Tipo de proxy: http, https (apenas se http não funcionar), socks4 ou socks5.
proxyAddressOpcionalString. Endereço IPv4 ou IPv6 do proxy. Proxies transparentes e proxies em máquinas locais não são permitidos.
proxyPortOpcionalInteiro. Porta do proxy.
proxyLoginOpcionalString. Nome de usuário do servidor proxy.
proxyPasswordOpcionalString. Senha do servidor proxy.

Quando aceita a tarefa, o CapMonster Cloud retorna o identificador taskId. Se a tarefa for concluída com sucesso, o token de resposta do reCAPTCHA vem em solution.gRecaptchaResponse. Para alguns sites, o objeto solution também inclui userAgent. Nesse caso, envie o formulário com esse User-Agent, mesmo que seja diferente do usado pelo navegador ou pelo script.

Configuração. Por padrão, o CapMonster Cloud usa proxies próprios. Os campos de proxy só são necessários se você quiser usar o seu. Se o proxy usa autorização por IP, adicione o endereço do CapMonster Cloud à lista de permissões. Na data de publicação, a documentação informa 65.21.190.34. O User-Agent compatível pode mudar. Consulte o User-Agent atual antes de rodar os testes.

reCAPTCHA v2 em Python

Se o teste precisar de um token real em vez de uma resposta predefinida do verificador, chame a API do CapMonster Cloud diretamente. O exemplo em Python dispensa a automação de navegador. O script chama createTask e consulta getTaskResult até a tarefa ficar pronta. Você precisa da biblioteca requests e de dois dados do formulário: a URL da página e a chave do site.

import time
import requests

API_KEY = "YOUR_API_KEY"
API = "https://api.capmonster.cloud"

def solve_recaptcha_v2(website_url, website_key, timeout=120):
    task = requests.post(f"{API}/createTask", json={
        "clientKey": API_KEY,
        "task": {
            "type": "RecaptchaV2Task",
            "websiteURL": website_url,
            "websiteKey": website_key,
        },
    }, timeout=30).json()
    if task["errorId"]:
        raise RuntimeError(task.get("errorCode"))

    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        time.sleep(3)
        result = requests.post(f"{API}/getTaskResult", json={
            "clientKey": API_KEY,
            "taskId": task["taskId"],
        }, timeout=30).json()
        if result["errorId"]:
            raise RuntimeError(result.get("errorCode"))
        if result["status"] == "ready":
            return result["solution"]
    raise TimeoutError("No result from CapMonster Cloud before the deadline")

solution = solve_recaptcha_v2("https://staging.example.com/signup", "YOUR_SITE_KEY")
token = solution["gRecaptchaResponse"]

A função retorna o objeto solution completo, incluindo o token. Para alguns sites, solution também inclui userAgent. Nesse caso, envie o formulário com o User-Agent informado. O intervalo de três segundos entre as consultas e a janela de cerca de dois minutos são pontos de partida. Ajuste os dois valores à sua suíte de testes. Se algum dos métodos retornar um errorId diferente de zero, a execução é interrompida com o código de erro da API. Assim, uma falha no CapMonster Cloud não é confundida com um erro do formulário.

Use o token assim que recebê-lo. O CapMonster Cloud informa que ele vale por 60 segundos após a resolução do desafio, e o Google só verifica cada token uma vez. Envie-o ao endpoint do formulário no campo g-recaptcha-response e confira a resposta da aplicação. Receber um token por si só não confirma que o formulário funcionou.

O guia passo a passo de Python com Selenium mostra como inserir o token na página pelo navegador.

Exemplo em JavaScript

Em um teste com Playwright, você pode obter um token pelo SDK do CapMonster Cloud e passá-lo à página. O teste lê a chave do site no widget, resolve a tarefa, grava o token no campo g-recaptcha-response e, na versão invisível, chama a função indicada em data-callback. Essa chamada é importante porque, no widget invisível, o callback dá continuidade ao envio. Preencher o campo por si só não envia o formulário.

import { test, expect } from "@playwright/test";
import {
  CapMonsterCloudClientFactory, ClientOptions, RecaptchaV2Request,
} from "@zennolab_com/capmonstercloud-client";

const client = CapMonsterCloudClientFactory.Create(
  new ClientOptions({ clientKey: process.env.CAPMONSTER_API_KEY })
);

test("signup with invisible reCAPTCHA v2", async ({ page }) => {
  test.setTimeout(120_000);
  await page.goto("/signup");
  await page.getByLabel("Email").fill("qa-run@example.com");

  const widget = page.locator("[data-sitekey]");
  const result = await client.Solve(new RecaptchaV2Request({
    websiteURL: page.url(),
    websiteKey: await widget.getAttribute("data-sitekey"),
    isInvisible: true,
  }));
  if (!result.solution) throw new Error(`CapMonster Cloud error: ${result.error}`);
  const token = result.solution.gRecaptchaResponse;

  await page.evaluate((token) => {
    document.querySelector("#g-recaptcha-response").value = token;
    const name = document.querySelector("[data-sitekey]").dataset.callback;
    window[name](token);
  }, token);

  await expect(page.getByText("Check your inbox")).toBeVisible();
});

O exemplo pressupõe que o widget esteja declarado no HTML com data-sitekey e data-callback. O Google exige que data-callback indique o nome de uma função global, por isso o teste pode chamá-la por window. Se a aplicação renderizar o widget com grecaptcha.render(), chame o callback passado pelo seu código. Na versão com caixa de seleção, retire isInvisible e envie o formulário como a aplicação faria normalmente. Substitua a rota, o rótulo do campo e o texto de confirmação pelos valores usados no seu formulário. O caminho relativo /signup pressupõe que baseURL esteja definida na configuração do Playwright.

Envie o formulário logo após a resolução do desafio, pois o token do CapMonster Cloud vale por 60 segundos. A última asserção verifica o que o usuário vê. Confira também no backend se o registro do cadastro foi criado.

O guia de JavaScript com Selenium mostra o mesmo fluxo com Selenium WebDriver.

Três formas de inserir o token

Depois de obter o token, falta enviá-lo à aplicação. Em um teste de bypass do reCAPTCHA v2, há três formas de fazer isso. A escolha depende de como o formulário foi implementado e de qual parte do fluxo o teste deve cobrir.

Gravação do token em g-recaptcha-response

O widget guarda a resposta em um textarea oculto com o ID g-recaptcha-response. Um formulário padrão envia esse campo junto com os demais dados. O teste pode definir o valor do textarea em um script da página e enviar o formulário normalmente. Isso funciona na versão com caixa de seleção quando o formulário é enviado sem depender de um callback.

await page.evaluate((token) => {
  document.querySelector("#g-recaptcha-response").value = token;
}, token);

Chamada da função indicada em data-callback

Na versão invisível, preencher o campo é insuficiente porque o formulário depende do callback do widget. Leia o nome da função no atributo data-callback e chame-a com o token. O Google exige que esse atributo indique uma função global, que o teste pode acessar por window. Se a aplicação renderizar o widget com grecaptcha.render(), chame o callback usado no seu código. Caso o formulário também leia o textarea, preencha o campo primeiro.

await page.evaluate((token) => {
  const name = document.querySelector("[data-sitekey]").dataset.callback;
  window[name](token);
}, token);

Envio de g-recaptcha-response em uma requisição HTTP

Você pode enviar os dados do formulário diretamente ao endpoint da aplicação, sem navegador, incluindo o token no campo g-recaptcha-response. É a forma mais rápida de testar o backend, mas a requisição precisa corresponder à que a página enviaria. Isso inclui os mesmos cookies de sessão, o token CSRF se o formulário exigir um e o cabeçalho User-Agent se o CapMonster Cloud retornar userAgent. O backend continua verificando o token com o Google. Esse método cobre a verificação no servidor e deixa de fora o widget e o JavaScript da página.

Por que o token é rejeitado

Se o envio falhar, identifique primeiro em que etapa ocorreu o erro. O Google pode ter rejeitado o token ou a aplicação pode ter recusado o formulário pelas próprias regras de validação ou autorização. Em geral, os logs da requisição no servidor ajudam a encontrar a causa mais rápido. No navegador, um mesmo alerta pode indicar vários erros diferentes.

Token expirado ou reutilizado. O Google aceita o token padrão do reCAPTCHA v2 por dois minutos e só o verifica uma vez. No CapMonster Cloud, os 60 segundos contam a partir da resolução da tarefa. O Google retorna timeout-or-duplicate tanto para um token expirado quanto para um já usado. Para distinguir os casos, veja quanto tempo passou entre a resolução e o envio e quantas requisições incluíram o mesmo token. Novas tentativas automáticas, cliques duplos e envios simultâneos podem fazer com que o mesmo token seja enviado duas vezes.

User-Agent desatualizado. Esse problema ocorre no cliente, antes da emissão do token. Se o userAgent enviado ao CapMonster Cloud não corresponder a uma identificação de navegador compatível, o Google pode exibir a mensagem “update your browser” e interromper a verificação. O CapMonster Cloud publica o valor atual em sua referência de User-Agent.

Proxy, User-Agent ou cookies diferentes. A requisição SiteVerify do Google recebe a chave secreta, o token de resposta e, opcionalmente, remoteip. User-Agent e cookies ficam fora dos parâmetros documentados dessa requisição. Para algumas integrações, o CapMonster Cloud descreve requisitos adicionais. Se você resolver a tarefa com seu próprio proxy, use o mesmo proxy ao enviar o token. Se solution incluir um userAgent, envie o formulário com esse valor, mesmo que o navegador ou o script use outro. Para os cookies, a documentação recomenda enviar os valores que a sua automação usa na página de destino.

websiteKey incorreta. O valor de websiteKey na tarefa deve corresponder ao atributo data-sitekey do widget na página que você testa. Um token emitido para outra chave não passa na verificação com a chave secreta do seu backend. Isso pode acontecer quando o ambiente de testes e o de produção têm chaves diferentes e o teste lê a chave errada da configuração. Se a integração confere o campo hostname da resposta, verifique se ela também aceita o hostname do ambiente de testes.

Para outras causas comuns, veja os erros de validação do reCAPTCHA e como corrigi-los.

O que não funciona

O backend exige um token válido. Ocultar o widget com CSS, removê-lo da página ou desativar o JavaScript deixa o formulário sem um g-recaptcha-response válido, e o servidor rejeita a requisição. Reutilizar um token também falha, pois o Google só verifica cada token uma vez. Um token copiado de outra página ou ambiente não passa na verificação se tiver sido emitido para outra chave de site.

Para verificações manuais, o CapMonster Cloud também oferece uma extensão para Chrome e Firefox. Ela funciona na própria sessão do navegador, o que facilita testar o formulário manualmente. Em testes automatizados do backend, continue verificando tanto a resposta da aplicação quanto os efeitos do envio.

robots
Comece agora e automatize sua solução reCAPTCHA v2

Perguntas frequentes

Obtenha um token de resposta válido e envie-o com o formulário. Um solucionador como o CapMonster Cloud devolve um token para a URL e a chave do site que você informou. O teste grava esse token em g-recaptcha-response, chama a função de data-callback na versão invisível ou envia o token diretamente ao endpoint. Use o token em até 60 segundos, apenas em recursos próprios ou que você tem autorização para testar.


 

Um solucionador de reCAPTCHA do Google resolve os desafios compatíveis e devolve um token de resposta. O CapMonster Cloud faz isso automaticamente. O backend do site ainda verifica o token antes de decidir se aceita o envio. Um cadastro pode passar na verificação do CAPTCHA e falhar mesmo assim, por exemplo, se o e-mail já estiver cadastrado. Se você estiver comparando fornecedores, veja como escolher um serviço de resolução de reCAPTCHA v2.


 

Sim. O CapMonster Cloud usa o mesmo tipo de tarefa RecaptchaV2Task, com isInvisible definido como true. No widget invisível, o envio continua por meio de um callback. Passe o token à função indicada em data-callback. Se você só gravar o token no campo oculto, em geral o formulário não será enviado.


 

O token padrão do reCAPTCHA v2 expira em dois minutos, e o Google só o verifica uma vez. O CapMonster Cloud informa que seu token vale por 60 segundos após a resolução do desafio. Esse prazo pode começar a contar antes que você receba o resultado. Insira o token assim que recebê-lo e solicite um novo a cada envio.


 

Uma tarefa padrão exige três campos: type (RecaptchaV2Task), websiteURL e websiteKey. Os demais são opcionais: recaptchaDataSValue para integrações com data-s, isInvisible para a versão invisível, userAgent, cookies e os campos de proxy. No seu backend, a API de verificação do Google precisa da chave secreta e do token de resposta. Mantenha a chave secreta no servidor.


 

Envie uma requisição createTask com o tipo RecaptchaV2Task, a URL da página e a chave do site. Em seguida, consulte getTaskResult até o status mudar para ready. A biblioteca requests é suficiente, sem precisar de um navegador. O token vem em solution.gRecaptchaResponse. A seção sobre Python traz o código completo, e o guia de Selenium indicado ali mostra como inserir o token na página.


 

O CapMonster Cloud documenta um tipo de tarefa específico para o reCAPTCHA v2 Enterprise. As duas versões podem mostrar uma caixa de seleção, então confira como a página carrega o widget. Na integração Enterprise do Google com caixa de seleção, o código usa enterprise.js e o namespace grecaptcha.enterprise. A chamada do backend, por si só, não identifica a versão. Migrar uma chave para o Google Cloud e passar a verificar com CreateAssessment são etapas distintas. Uma chave migrada ainda pode ser verificada pelo SiteVerify.


 

CapMonster Cloud

O CapMonster Cloud é um serviço em nuvem que resolve CAPTCHAs automaticamente. No reCAPTCHA v2, a tarefa RecaptchaV2Task atende tanto ao widget com caixa de seleção quanto ao invisível e devolve um token que você pode enviar com o formulário. A integração pode usar a API ou os SDKs oficiais. Em um fluxo de QA, o token é parte de um teste mais amplo que abrange a verificação no servidor, o processamento do formulário e o resultado esperado na aplicação.


NB: Por favor, observe que o produto é destinado à automação de testes exclusivamente em seus próprios sites e em recursos para os quais você possui autorização legal de acesso.

ItGuy
geear
Programa de afiliados para desenvolvedores de software
Ganhe até 30% dos gastos dos seus usuários com a evasão de captcha
✅ Solicitação enviada
Obrigado pelo seu interesse em nosso programa de parcerias! Entraremos em contato com você dentro de 7 dias úteis.
Solicitação para participar
Preencha o formulário para enviar uma solicitação para o programa de afiliados.
Mais artigos