GeeTest CAPTCHA v4
e CapMonster Cloud

Resolução de captcha, integração no site e testes.

Preços da solução GeeTest CAPTCHA v4

CAPTCHA
Preço (USD)
$ 1.20
1000 tokens
Você herdou um site com captcha ou outra camada de proteção, mas não tem acesso ao código-fonte? Então é normal querer saber qual solução está instalada, se a configuração está correta e como testar tudo.

Neste artigo, procuramos responder a todas as principais dúvidas. Para começar a resolver o problema, o primeiro passo é identificar qual sistema de proteção está sendo utilizado. Para isso, você pode consultar a lista de captchas e sistemas de proteção antibot mais populares, onde há exemplos visuais e sinais principais que ajudam a identificar rapidamente com o que você está lidando.

Se você notar que o seu site utiliza GeeTest CAPTCHA v4, o passo seguinte é estudar com mais detalhes as suas características e o seu funcionamento. Neste mesmo artigo, você também pode conferir o guia de integração do GeeTest CAPTCHA v4, para entender por completo como o sistema opera no seu site. Isso permitirá não apenas compreender a proteção atual, mas também planejar adequadamente a sua manutenção.

O que é GeeTest CAPTCHA v4
O que é GeeTest CAPTCHA v4
GeeTest CAPTCHA v4 (Adaptive CAPTCHA/Behavior Verification) é uma versão mais moderna em comparação à v3, criada para proteger sites contra ações automatizadas que podem prejudicar o recurso. O sistema acompanha o comportamento e as características do dispositivo do visitante do site e escolhe um desafio adequado: para uma pessoa real, a verificação será o mais simples possível — geralmente basta um clique no widget da captcha; já em caso de suspeita de automação, o usuário recebe um desafio mais complexo, que precisa ser concluído com sucesso.
Background
Exemplos de GeeTest CAPTCHA v4
No CAPTCHA
No CAPTCHA
A verificação do usuário é feita principalmente com base no comportamento e na interação com o site, sem a necessidade de resolver tarefas explícitas.
Icon CAPTCHA
Icon CAPTCHA
Selecionar imagens na ordem indicada.
IconCrush CAPTCHA
IconCrush CAPTCHA
Trocar elementos de lugar para alinhar três ícones idênticos em uma linha (como em puzzles do tipo “match-3”).
Slide CAPTCHA
Slide CAPTCHA
Um slider para montar um quebra-cabeça ou alinhar elementos de uma imagem.
Gobang CAPTCHA
Gobang CAPTCHA
Um slider para montar um quebra-cabeça ou alinhar elementos de uma imagem.

Como resolver GeeTest CAPTCHA v4 com o CapMonster Cloud

Ao testar formulários com GeeTest CAPTCHA v4, é comum precisar confirmar se a captcha está funcionando e integrada corretamente.

Você pode testar manualmente a captcha incorporada no site.

  • Abra a página do formulário e veja se a captcha é exibida.
  • Tente enviar sem resolver — o servidor deve retornar erro.
  • Depois de resolver corretamente, o envio precisa ocorrer sem falhas.

Para resolver automaticamente use ferramentas como o CapMonster Cloud, que recebe os parâmetros da captcha, processa em seus servidores e devolve um token pronto. Basta inseri-lo no formulário para passar na verificação sem interação humana.

Trabalhar com o CapMonster Cloud via API normalmente envolve as etapas abaixo:

Criação da tarefaCriação da tarefa
arrow
Envio da requisição APIEnvio da requisição API
arrow
Recebimento do resultadoRecebimento do resultado
arrow
Aplicação do token na páginaAplicação do token na página
arrow
Reconhecimento do GeeTest CAPTCHA v4 usando bibliotecas prontas
O serviço CapMonster Cloud oferece bibliotecas prontas para trabalhar de forma prática em Python, JavaScript (Node.js) e C#.
Python
JavaScript
C#
Resolução, inserção do token e envio do formulário
Exemplo em Node.js para o ciclo completo de reconhecimento da captcha na sua página web. Abordagens possíveis: usar requisições HTTP para obter o HTML e os parâmetros da captcha, enviar a resposta e processar o resultado; ou, com ferramentas de automação (por exemplo, Playwright), abrir a página, aguardar a captcha, enviar os parâmetros (para testes, você pode enviar tanto dados corretos quanto propositadamente incorretos), obter a solução por meio do cliente do CapMonster Cloud, inserir o token no formulário e visualizar o resultado.
python
// npm install playwright @zennolab_com/capmonstercloud-client

import { chromium } from "playwright";
import {
  CapMonsterCloudClientFactory,
  ClientOptions,
  GeeTestRequest
} from "@zennolab_com/capmonstercloud-client";

const CAPMONSTER_API_KEY = "YOUR_CAPMONSTER_API_KEY";

async function solveGeetestV4(pageUrl) {
  const browser = await chromium.launch({ headless: false });
  const context = await browser.newContext({ viewport: null });
  const page = await context.newPage();

  let detected = null;
  let solutionObj = null;

  // 1. Interceptar a resposta de /load (obter captcha_id, challenge etc.)
  page.on("response", async (response) => {
    const url = response.url();
    if (!url.startsWith("https://gcaptcha4.geetest.com/load?")) return;

    const params = new URLSearchParams(url.split("?")[1] || "");
    const captchaId = params.get("captcha_id");
    const challenge = params.get("challenge");
    const captchaType = params.get("captcha_type");

    if (captchaId && challenge) {
      detected = { captchaId, challenge, captchaType };
      console.log("Detected GeeTest v4 load:", detected);
    }
  });

  // 2. Carregar a página
  console.log("Opening page:", pageUrl);
  await page.goto(pageUrl, { waitUntil: "domcontentloaded" });

  // 3. Aguardar até interceptar /load
  console.log("Waiting for GeeTest /load...");
  while (!detected) {
    await page.waitForTimeout(500);
  }

  // 4. Enviar a tarefa para o CapMonster Cloud
  console.log("Sending task to CapMonster...");
  const cmc = CapMonsterCloudClientFactory.Create(
    new ClientOptions({ clientKey: CAPMONSTER_API_KEY })
  );

  const task = new GeeTestRequest({
    websiteURL: pageUrl,
    gt: detected.captchaId,
    challenge: detected.challenge,
    version: "4",
    initParameters: {
      riskType: detected.captchaType || "slide"
    }
  });

  const solveRes = await cmc.Solve(task);
  const sol = solveRes.solution || solveRes;

  solutionObj = {
    captcha_id: sol.captcha_id || detected.captchaId,
    captcha_output: sol.captcha_output,
    lot_number: sol.lot_number,
    pass_token: sol.pass_token
  };

  console.log("Got solution from CapMonster:", solutionObj);

  // 5. Substituir pelos seus valores em /verify para obter uma resposta de sucesso
  await page.route("https://gcaptcha4.geetest.com/verify*", async (route) => {
    console.log("Intercepted /verify, injecting fake success...");
    const body = `geetest_${Date.now()}(${JSON.stringify({
      status: "success",
      data: {
        result: "success",
        seccode: {
          captcha_id: solutionObj.captcha_id,
          captcha_output: solutionObj.captcha_output,
          lot_number: solutionObj.lot_number,
          pass_token: solutionObj.pass_token
        }
      }
    })})`;

    await route.fulfill({
      status: 200,
      contentType: "application/javascript",
      body
    });
  });

  // 6. Simular a ação do usuário (por exemplo, clicar no botão da captcha)
  console.log("Waiting for captcha interaction...");
  await page.waitForTimeout(3000);

  // Exemplo de chamada de verificação:
  try {
    await page.click('.geetest_btn'); // botão da captcha
    console.log("Clicked captcha button");
  } catch {
    console.log("Captcha button not found");
  }

  // Às vezes, é necessário chamar verify() manualmente:
  await page.evaluate(() => {
    if (window.initGeetest4 && typeof verify === "function") {
      verify();
    }
  });

  console.log("Waiting for verification request...");
  await page.waitForTimeout(3000);

  await browser.close();

  return { detected, solution: solutionObj };
}
(async () => {
  const url = "https://example.com"; // substitua por uma página que use GeeTest v4
  const res = await solveGeetestV4(url);
  console.log("FINISHED:", res);
})();
Como conectar GeeTest CAPTCHA v4 ao seu site
Para entender bem como a captcha funciona no seu site, como a validação se comporta e como reconectar ou reconfigurar a proteção, recomendamos que você leia esta seção. Nela é descrito o processo de configuração da proteção — isso vai ajudar você a cobrir rapidamente todos os detalhes.

1. Cadastre-se ou faça login na sua conta GeeTest.

2. Acesse o Captcha Dashboard e selecione Behavior Verification v4:

HowTo Connect image 1

3. No painel, clique em + Create application.

4. Informe APP/website name (nome do site ou aplicativo onde a captcha será usada), Address (domínio principal do site em que a captcha será instalada, por exemplo https://example.com), Industry (categoria do site, como “E-commerce”, “Social Media” etc.) e clique em Confirm.

5. Clique em Add events ao lado da aplicação recém-criada. Defina Event — o nome do cenário específico em que a captcha será usada, por exemplo login, register etc.; Device — a plataforma (por exemplo, Web/Wap); Business types — o tipo de cenário de uso da captcha (por exemplo, Sign-up / Sign-in — cadastro / login). Em seguida, clique em Add.

6. Agora, no painel, serão exibidos o ID (usado tanto no cliente quanto no servidor) e a Key (usada no servidor para verificação) da captcha criada:

HowTo Connect image 2

7. Conecte a parte de frontend

Inclua o script:

markup
<script src="https://static.geetest.com/v4/gt4.js"></script>

Inicialize a CAPTCHA:

javascript
initGeetest4(
  { captchaId: "Your CaptchaId" },
  function (captcha) {
    captcha.appendTo("#captcha"); // inserimos em um elemento da página
  }
);

Importante:

  • A CAPTCHA precisa ser inicializada durante o carregamento da página, caso contrário ela não conseguirá acompanhar o comportamento do usuário.
  • Se você usar várias CAPTCHAs na mesma página, chame initGeetest4 separadamente para cada uma.
  • Se a CAPTCHA estiver em um iframe, adicione sandbox="allow-scripts allow-popups".

Exemplo de códigoExemplo de código
arrow

8. Configure a parte de backend.

Quando o usuário passa pela CAPTCHA no frontend, é gerado um conjunto de parâmetros. Esses parâmetros devem ser enviados para o backend e, em seguida, verificados pela API secundária da GeeTest para confirmar que a verificação foi bem-sucedida.

API secundária de verificação:

javascript
url
http://gcaptcha4.geetest.com/validate

  • Método: GET/POST
  • Content-Type: application/x-www-form-urlencoded
  • Resposta: JSON

Principais parâmetros da requisição

  • lot_number – número de série da verificação
  • captcha_output – dados da verificação
  • pass_token – token de verificação
  • gen_time – hora de geração da verificação
  • captcha_id – ID da CAPTCHA
  • sign_token – assinatura usada para verificação

Exemplo de resposta bem-sucedidaExemplo de resposta bem-sucedida
arrow

Exemplo de verificação de CAPTCHA em PHPExemplo de verificação de CAPTCHA em PHP
arrow

Background
Possíveis erros e depuração
Bug Icon
Parâmetros inválidos
A captcha não é exibida ou retorna erros como invalid-captcha-id / invalid-challenge. Verifique se você está usando valores atualizados de captcha_id e challenge, correspondentes à sua página. Esses parâmetros são gerados dinamicamente a cada requisição /load.
Bug Icon
Tempo limite de resolução
O resultado da resolução da captcha não foi recebido a tempo. Aumente o timeout quando utilizar serviços de resolução automática (por exemplo, CapMonster Cloud) e verifique se a conexão com a API está estável.
Bug Icon
Campos vazios
captcha_output, pass_token ou lot_number não foram enviados para a página ou para a requisição de verificação. Verifique se esses valores estão sendo inseridos corretamente em campos ocultos do formulário ou no corpo da requisição enviada ao seu servidor.
Bug Icon
Resposta success=false
O token expirou, foi reutilizado ou é inválido/falso. Ative o log de todas as requisições e respostas do servidor de verificação para poder acompanhar campos como error_code ou error_msg.
Verificação da robustez
Depois da integração, confirme que o sistema de fato protege o site contra ações automatizadas.
Recomendações de segurança e otimização
Mantenha a <span class="font-bold">chave da captcha (KEY secreta) apenas no servidor</span> — nunca exponha essa chave no frontend.
Registre (log) os códigos de erro durante a verificação (<span class="font-bold">error-codes</span> ou campos da resposta do servidor), para entender as causas das validações que falharam.
Adicione no rodapé do formulário links para a sua <span class="font-bold">Política de Privacidade</span> e para os <span class="font-bold">Termos de Uso da GeeTest</span>, caso isso seja exigido pela licença ou pelas políticas internas.
Conclusão

Se você herdou um site que já tem um captcha ou outro sistema de proteção instalado e não tem acesso ao código, não tem problema! É bem fácil identificar qual tecnologia está sendo usada. Para verificar se tudo está funcionando corretamente, você pode usar o serviço de reconhecimento CapMonster Cloud em um ambiente de testes isolado, para garantir que o mecanismo de processamento de tokens e a lógica de verificação estejam funcionando corretamente.

No caso de GeeTest CAPTCHA v4, basta identificar o sistema, analisar o comportamento dele e se certificar de que a proteção está funcionando corretamente. No artigo, mostramos como identificar GeeTest CAPTCHA v4 e onde encontrar instruções para a integração ou reconfiguração, para que você consiga manter a proteção com segurança e controlar o funcionamento dela.

Conclusion

Perguntas frequentes sobre GeeTest CAPTCHA v4

O CapMonster Cloud usa por padrão os endpoints GeeTest padrão. Inclua o parâmetro geetestApiServerSubdomain no corpo da requisição GeeTestTask apenas se o site de destino usar um endpoint de API específico para carregar o widget. Para detectar, inspecione o tráfego de rede do site: se as requisições de inicialização forem para um host não padrão diferente de api.geetest.com, passe esse valor de subdomínio no parâmetro.

riskType informa ao solver qual tipo de interação esperar — slide, icon, gobang e outros modos específicos do challenge. Para um challenge slider padrão, defina "riskType": "slide" no payload da requisição createTask. Por exemplo:

POST https://api.capmonster.cloud/createTask

json
{
  "clientKey": "YOUR_CAPMONSTER_CLOUD_API_KEY",
  "task": {
    "type": "GeeTestTask",
    "websiteURL": "https://gt4.geetest.com/",
    "gt": "54088bb07d2df3c46b79f80300b0abbe",
    "version": 4,
    "initParameters": {
      "riskType": "slide"
    }
  }
}

Sem isso, o solver pode tentar o tipo de interação errado e retornar um token inválido.

O CapMonster Cloud oferece SDKs oficiais para Python, Node.js e C#. Cada SDK cuida internamente da criação de tarefas, polling da solução CAPTCHA, lógica de retry e gerenciamento de timeout. Usar esses SDKs é o caminho mais rápido da chave de API a um solver funcional.

Após a resolução, o CapMonster Cloud retorna quatro valores a encaminhar para o endpoint /verify do site:

  • captcha_output — os dados de solução codificados
  • pass_token — o token de verificação
  • lot_number — o número de série de verificação
  • gen_time — o timestamp da solução gerada

Combine-os com o captcha_id usado ao criar a tarefa de resolução e substitua esses valores em /verify para obter uma resposta bem-sucedida.

Extraia os parâmetros de inicialização do GeeTest interceptando o tráfego de rede durante o carregamento da página. No Playwright, escute as respostas da página e filtre o endpoint /load em gcaptcha4.geetest.com. Analise a query string da URL para extrair captcha_id e risk_type. Um exemplo mínimo de Playwright em Python:

python
async def on_request(request):
    url = request.url
    if "https://gcaptcha4.geetest.com/load?" in url:
        query = parse_qs(urlparse(url).query)
        captcha_id = query.get("captcha_id", [None])[0]
        risk_type = query.get("risk_type", [None])[0]

        if captcha_id and not result["version"]:
            result["version"] = "v4"
            result["data"] = {
                "captchaId": captcha_id,
                "riskType": risk_type
            }

            print("GeeTest v4 detected:")
            print(result["data"])

Passe o captcha_id extraído como parâmetro gt, junto com riskType e version diretamente no payload GeeTestTask. Para o esquema completo da API, consulte a documentação.