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
Herdou um site com captcha ou outra proteção mas sem acesso ao código-fonte? É natural perguntar qual solução está instalada, se está configurada corretamente e como testá-la.

Neste artigo procurámos responder a todas as questões importantes. Para começar a resolver o problema, o primeiro passo é identificar que sistema de proteção está a ser utilizado. Para isso, pode consultar a lista de captchas e sistemas de proteção antibot mais populares, onde encontrará exemplos visuais e sinais principais que ajudam a perceber rapidamente com o que está a lidar.

Se verificar que o seu site utiliza GeeTest CAPTCHA v4, o passo seguinte é analisar mais detalhadamente as suas características e o seu funcionamento. Neste mesmo artigo também pode consultar o guia de integração de GeeTest CAPTCHA v4, para compreender totalmente como o sistema funciona no seu site. Isto permitirá não só entender a proteção atual, como também planear corretamente 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 com a v3, criada para proteger sites de ações automatizadas que podem causar danos ao recurso. O sistema acompanha o comportamento e as características do dispositivo do visitante e seleciona um desafio adequado: para um utilizador real, a verificação será o mais simples possível — um único clique no widget da captcha costuma bastar; já em caso de suspeita de automação, é apresentado ao utilizador um desafio mais complexo que precisa ser concluído.
Background
Exemplos de GeeTest CAPTCHA v4
No CAPTCHA
No CAPTCHA
A verificação do utilizador é feita principalmente com base no comportamento e na interação com o site, sem 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 numa linha (como nos puzzles do tipo “match-3”).
Slide CAPTCHA
Slide CAPTCHA
Um slider para montar um puzzle ou alinhar elementos da imagem.
Gobang CAPTCHA
Gobang CAPTCHA
Um slider para montar um puzzle ou alinhar elementos da imagem.

Como resolver GeeTest CAPTCHA v4 através do CapMonster Cloud

Ao testar formulários que incluem GeeTest CAPTCHA v4, é comum precisar verificar se a captcha foi integrada e funciona corretamente.

Pode testar manualmente a captcha incorporada no seu site.

  • Abra a página do formulário e confirme que a captcha é apresentada.
  • Tente enviar o formulário sem resolvê-la — o servidor deve devolver um erro.
  • Após uma resolução bem-sucedida, o formulário deve ser enviado sem problemas.

Para resolução automática recorra a ferramentas como o CapMonster Cloud, que recebe os parâmetros da captcha, processa-os nos seus servidores e devolve um token pronto. Basta inseri-lo no formulário para ultrapassar a verificação sem interação do utilizador.

Trabalhar com o CapMonster Cloud através da API normalmente envolve os passos seguintes:

Criação da tarefaCriação da tarefa
arrow
Envio do pedido APIEnvio do pedido API
arrow
Receção do resultadoReceção do resultado
arrow
Aplicação do token na páginaAplicação do token na página
arrow
Reconhecimento de GeeTest CAPTCHA v4 utilizando bibliotecas prontas
O serviço CapMonster Cloud disponibiliza bibliotecas prontas para trabalhar de forma conveniente 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 pedidos 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 pode enviar dados corretos e também incorretos), obter a solução através do cliente do CapMonster Cloud, inserir o token no formulário e ver 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. Intercetar 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é intercetar /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 bem-sucedida
  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 utilizador (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");
  }

  // Por 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 com GeeTest v4
  const res = await solveGeetestV4(url);
  console.log("FINISHED:", res);
})();
Como ligar GeeTest CAPTCHA v4 ao seu site
Para compreender bem como a captcha funciona no seu site, como se comporta a validação e como voltar a ligá-la ou reconfigurá-la, recomendamos a leitura desta secção. Aqui é descrito o processo de ativação da proteção, o que o ajudará a cobrir rapidamente todos os detalhes.

1. Registe-se ou inicie sessão na sua conta GeeTest.

2. Aceda ao Captcha Dashboard e selecione Behavior Verification v4:

HowTo Connect image 1

3. No painel, clique em + Create application.

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

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

6. Agora, no seu painel, irão aparecer o ID (utilizado no cliente e no servidor) e a Key (utilizada no servidor para verificação) da captcha criada:

HowTo Connect image 2

7. Ligue a parte do cliente

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 num elemento da página
  }
);

Importante:

  • A CAPTCHA deve ser inicializada durante o carregamento da página; caso contrário, não conseguirá acompanhar o comportamento do utilizador.
  • Se utilizar várias CAPTCHAs na mesma página, chame initGeetest4 separadamente para cada uma.
  • Se utilizar a CAPTCHA dentro de um iframe, adicione sandbox="allow-scripts allow-popups".

Exemplo de códigoExemplo de código
arrow

8. Configure a parte do servidor.

Quando o utilizador passa a CAPTCHA no frontend, é gerado um conjunto de parâmetros. Esses parâmetros devem ser enviados para o backend e depois verificados através da API secundária do 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

Parâmetros principais do pedido

  • 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 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 devolve erros como invalid-captcha-id / invalid-challenge. Verifique se está a usar valores atualizados de captcha_id e challenge, correspondentes à sua página. Estes parâmetros são gerados dinamicamente em cada pedido /load.
Bug Icon
Timeout de resolução
O resultado da resolução da captcha não foi recebido a tempo. Aumente o tempo de espera ao utilizar serviços de resolução automática (por exemplo, CapMonster Cloud) e certifique-se de que a ligação à API é estável.
Bug Icon
Campos vazios
captcha_output, pass_token ou lot_number não foram enviados para a página ou para o pedido de verificação. Verifique se esses valores são inseridos corretamente em campos escondidos do formulário ou no corpo do pedido enviado ao seu servidor.
Bug Icon
Resposta success=false
O token expirou, foi reutilizado ou é falso. Ative o registo (logging) de todos os pedidos e respostas do servidor de verificação para poder acompanhar campos como error_code ou error_msg.
Verificações de robustez
Depois da integração, certifique-se de que o sistema protege efetivamente o site contra ações automatizadas.
Recomendações de segurança e otimização
Guarde a <span class="font-bold">chave da captcha (KEY secreta) apenas no servidor</span> e nunca a exponha no lado do cliente.
Registe os códigos de erro durante a verificação (<span class="font-bold">error-codes</span> ou campos da resposta do servidor), para compreender as causas das falhas nas validações.
Adicione no final 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 Utilização do GeeTest</span>, caso isso seja exigido pela licença ou por políticas internas.
Conclusão

Se 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 há problema! É bastante fácil identificar qual a tecnologia que está a ser utilizada. Para verificar se tudo está a funcionar corretamente, pode usar o serviço de reconhecimento CapMonster Cloud num ambiente de teste isolado, para garantir que o mecanismo de processamento de tokens e a lógica de verificação estão a funcionar corretamente.

No caso de GeeTest CAPTCHA v4, basta identificar o sistema, analisar o seu comportamento e confirmar que a proteção está a funcionar corretamente. No artigo, mostramos como identificar GeeTest CAPTCHA v4 e onde encontrar instruções para a sua integração ou reconfiguração, para que possa manter a proteção com confiança e controlar o seu funcionamento.

Conclusion

Perguntas frequentes sobre GeeTest CAPTCHA v4

O CapMonster Cloud usa por defeito os endpoints GeeTest padrão. Inclua o parâmetro geetestApiServerSubdomain no corpo do pedido GeeTestTask apenas se o site de destino usar um endpoint API específico para carregar o widget. Para detetar, inspecione o tráfego de rede do site: se os pedidos 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 indica ao solver que tipo de interação esperar — slide, icon, gobang e outros modos específicos do challenge. Para um challenge slider padrão, defina "riskType": "slide" na carga útil do pedido 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 isto, o solver pode tentar o tipo de interação errado e devolver um token inválido.

O CapMonster Cloud fornece SDK oficiais para Python, Node.js e C#. Cada SDK trata internamente da criação de tarefas, polling da solução CAPTCHA, lógica de retry e gestão de timeouts. Usar estes SDK é a forma mais rápida de passar da chave API a um solver funcional.

Após a resolução, o CapMonster Cloud devolve quatro valores a reencaminhar 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 carimbo temporal da solução gerada

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

Extraia os parâmetros de inicialização 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 do 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, juntamente com riskType e version diretamente na carga útil GeeTestTask. Para o esquema API completo, consulte a documentação.