GeeTest CAPTCHA v3
e CapMonster Cloud

Resolução de CAPTCHA, instalação no site e testes.

Preços da solução GeeTest CAPTCHA v3

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 v3, 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 v3, 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 v3
O que é GeeTest CAPTCHA v3

GeeTest CAPTCHA v3 é um sistema de proteção de sites contra ações automatizadas que podem prejudicar o serviço. Ele permite diferenciar usuários reais de bots, garantindo a segurança e o funcionamento estável do site.

Background
Exemplos de GeeTest CAPTCHA v3
Intelligent mode
Intelligent mode
A verificação do usuário é feita principalmente com base no comportamento e na interação com o site, sem exigir a resolução de desafios adicionais.
Slide CAPTCHA
Slide CAPTCHA
Um controle deslizante (slider) que deve ser movido para completar um quebra-cabeça ou alinhar um elemento da imagem.
Icon CAPTCHA
Icon CAPTCHA
Seleção de imagens na ordem indicada.
Space CAPTCHA
Space CAPTCHA
Mover uma figura para a posição correta na imagem.

Como resolver GeeTest CAPTCHA v3 com o CapMonster Cloud

Ao testar formulários com GeeTest CAPTCHA v3, é 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 de GeeTest CAPTCHA v3 usando bibliotecas prontas
O serviço CapMonster Cloud fornece 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 usar ferramentas de automação (por exemplo, Playwright) para abrir a página, aguardar o carregamento da CAPTCHA, enviar os parâmetros (para testes você pode enviar dados corretos e incorretos), obter a solução por meio do cliente CapMonster Cloud, inserir o token no formulário e ver o resultado.
python
// npm install playwright @zennolab_com/capmonstercloud-client
// npx playwright install chromium

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

const API_KEY = 'your_capmonster_cloud_api_key';
const DEMO_PAGE = 'https://example.com';

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

  console.log('Abrindo a página...');
  await page.goto(DEMO_PAGE, { waitUntil: 'networkidle' });

  console.log('Obtendo os parâmetros da CAPTCHA...');
  const init = await page.evaluate(async () => {
    // Enviamos uma requisição para o servidor para obter os parâmetros init-params da GeeTest — substitua pelo seu endpoint
    const r = await fetch(`/api/v1/example/gee-test/init-params?t=${Date.now()}`);  
    return r.json();
  });
  console.log('Init params:', init);

  console.log('Criando uma tarefa no CapMonster Cloud...');
  const cmc = CapMonsterCloudClientFactory.Create(new ClientOptions({ clientKey: API_KEY }));
  const solRaw = await cmc.Solve(new GeeTestRequest({ websiteURL: DEMO_PAGE, gt: init.gt, challenge: init.challenge }));
  const sol = solRaw.solution || solRaw;
  console.log('Solução da CAPTCHA:', sol);

  console.log('Inserindo a solução nos campos ocultos...');
  await page.evaluate(s => {
    ['challenge','validate','seccode'].forEach(n => {
      const el = document.querySelector(`input[name="geetest_${n}"]`);
      if(el) el.value = s[n];
    });
  }, sol);

  await page.click('button[data-action="test_action"]'); // substitua pelo seu valor
  console.log('Enviando a requisição de verificação (verify) para o servidor...');
  const result = await page.evaluate(async () => {
    const payload = {
      geetest_challenge: document.querySelector('input[name="geetest_challenge"]')?.value,
      geetest_validate: document.querySelector('input[name="geetest_validate"]')?.value,
      geetest_seccode: document.querySelector('input[name="geetest_seccode"]')?.value
    };
    // substitua pelo seu valor
    const r = await fetch('/api/v1/example/gee-test/verify', { 
      method:'POST', 
      headers:{'Content-Type':'application/json'}, 
      body: JSON.stringify(payload) 
    });
    return r.json();
  });

  console.log('Resultado da verificação da CAPTCHA:', result);

  await page.waitForTimeout(3000);
  await browser.close();
})();
Como conectar GeeTest CAPTCHA v3 ao seu site
Para entender bem como a CAPTCHA funciona no seu site, como é a lógica de validação 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 passar rapidamente por todos os detalhes.

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

2. Acesse o Captcha Dashboard e selecione CAPTCHA v3:

HowTo Connect image 1

3. Clique em +New Captcha para criar uma nova CAPTCHA. Informe o nome da CAPTCHA (por exemplo, o nome do produto ou projeto), a URL do site onde ela será integrada e escolha o contexto de uso da CAPTCHA (por exemplo, Login / Cadastro / Recuperação de senha etc.).

4. Você vai receber um CAPTCHA ID e uma KEY únicos. Eles podem ser configurados no painel de segurança.

HowTo Connect image 2

5. Configure a parte de servidor (Server SDK):

O servidor trabalha com duas APIs:

  • API1 — inicialização (criação do challenge)
  • API2 — verificação do resultado após a conclusão da CAPTCHA

php
<?php
header('Content-Type: application/json');

const CAPTCHA_ID = '07df3141a35**********19a473d7c50';
const CAPTCHA_KEY = '543b19036ef********8e07d121b81e9';

$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);

function getJson($url) {
    $res = @file_get_contents($url);
    return $res ? json_decode($res, true) : null;
}

// API1: inicialização
if ($path === '/register') {
    $data = getJson("https://api.geetest.com/register.php?gt=" . CAPTCHA_ID . "&json_format=1");
    echo json_encode($data ? [
        'gt' => CAPTCHA_ID,
        'challenge' => $data['challenge'],
        'success' => $data['success'] === 1,
        'new_captcha' => true
    ] : ['success' => 0]);
    exit;
}

// API2: verificação
if ($path === '/validate' && $_SERVER['REQUEST_METHOD'] === 'POST') {
    $req = json_decode(file_get_contents('php://input'), true);
    $data = getJson("https://api.geetest.com/validate.php?" . http_build_query([
        'seccode' => $req['geetest_seccode'] ?? '',
        'challenge' => $req['geetest_challenge'] ?? '',
        'gt' => CAPTCHA_ID,
        'json_format' => 1
    ]));
    echo json_encode(['success' => !empty($data['seccode'])]);
    exit;
}

http_response_code(404);
echo json_encode(['error' => 'Not found']);

6. Conecte a parte de cliente (Client SDK):

No front-end, você carrega o gt.js e chama initGeetest, passando os parâmetros recebidos do servidor (API1). Exemplo usando ajax:

javascript
ajax({
    url: "https://example.com/register",
    type: "get",
    dataType: "json",
    success: function (data) {
        initGeetest({
            gt: data.gt,
            challenge: data.challenge,
            offline: !data.success,
            new_captcha: true
        }, function (captchaObj) {
            captchaObj.appendTo("#captcha");

            captchaObj.onSuccess(function () {
                const result = captchaObj.getValidate();
                ajax({
                    url: "https://example.com/validate",
                    type: "post",
                    contentType: "application/json",
                    data: JSON.stringify(result),
                    success: function(res) {
                        if (res.success) alert('CAPTCHA passed');
                        else alert('CAPTCHA failed');
                    }
                });
            });
        });
    }
});

Verificando o funcionamento

Certifique-se de que:

  • /register retorna um challenge
  • A CAPTCHA é exibida corretamente
  • Após concluir a CAPTCHA, você vê no console do navegador uma requisição para /validate
  • O servidor retorna "success": true

Failback (modo de contingência)

Se o servidor GeeTest não estiver disponível:

  • O cliente recebe success: false
  • A CAPTCHA muda para o modo local (funciona sem conexão com o GeeTest Cloud). Para testar, basta informar um CAPTCHA_ID inválido (por exemplo, 123456789).

Background
Possíveis erros e depuração
Bug Icon
Parâmetros inválidos
A CAPTCHA não é exibida ou retorna o erro invalid-gt / invalid-challenge. Verifique se você está usando valores atualizados de gt e challenge para a sua página.
Bug Icon
Tempo limite de resolução
a solução da CAPTCHA não foi recebida a tempo. Aumente o tempo de espera (timeout) ao usar serviços de resolução automática (por exemplo, CapMonster).
Bug Icon
Campos vazios
challenge, validate ou seccode não foram enviados para a página. Certifique-se de que eles estão sendo inseridos corretamente nos campos ocultos do formulário.
Bug Icon
Resposta success=false
o token expirou, foi reutilizado ou é falso. Para diagnóstico, ative o logging das requisições e verifique os campos retornados pelo servidor (por exemplo, os error-codes ao usar o CapMonster ou o seu servidor de validação).
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> e não a envie para o front-end.
Registre (faça logging) dos códigos de erro durante a validação (os <span class="font-bold">error-codes</span> ou campos da resposta do servidor) para entender as causas das validações malsucedidas.
Adicione no final do formulário links para a <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 suas 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 v3, 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 v3 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 v3

Os valores challenge têm vida útil curta — normalmente menos de dois minutos. Passar um challenge obsoleto para createTask é a causa mais comum de ERROR_TOKEN_EXPIRED. Obtenha um challenge novo do endpoint init-params do site o mais perto possível de cada chamada createTask — sem cache, sem reutilização.

Vale notar: tarefas que retornam ERROR_TOKEN_EXPIRED ainda são contabilizadas como faturadas.

Consultar https://api.capmonster.cloud/getTaskResult retorna um objeto solution com três campos (os valores serão sempre diferentes):

json
{
  "solution": {
    "challenge": "0f759dd1ea6c4wc76cedc2991039ca4f23",
    "validate": "6275e26419211d1f526e674d97110e15",
    "seccode": "510cd9735583edcb158601067195a5eb|jordan"
  }
}

Mapeie-os respectivamente para os campos ocultos geetest_challenge, geetest_validate e geetest_seccode antes de enviar o formulário. Você pode injetá-los com Playwright, Puppeteer, Selenium ou um cliente HTTP simples.

Nota: consulte em intervalos regulares e não exceda 120 requisições por tarefa para evitar bloqueio da conta. Dependendo da carga do sistema, a resposta geralmente chega em 10 a 30 segundos.

Para entender a lógica de automação, ajuda encontrar esses parâmetros manualmente:

  1. Abra DevTools → aba Network.
  2. Filtre por init-params e recarregue a página.
  3. A resposta JSON conterá gt e challenge. Este é o endpoint que sua automação precisa interceptar.

Para automação com Playwright ou outro navegador headless, intercepte a resposta init-params no nível de rede — é mais rápido e confiável do que parsing do DOM. Depois analise o payload JSON para gt e challenge.

Scripts de extração prontos estão disponíveis na documentação CapMonster Cloud.

O GeeTest v3 ativa o modo offline/bypass quando os servidores de verificação ficam inacessíveis. Nesse modo, o widget continua sendo renderizado e o usuário pode interagir com ele, mas a verificação do site no cliente e no servidor é tratada localmente.

Não afeta fluxos de resolução automatizada.

Sim. O CapMonster Cloud pode ser usado em fluxos automatizados GeeTest CAPTCHA v3 quando você precisa validar envio de formulários, cenários de QA ou comportamento sob carga sem interação manual.

Use valores gt e challenge novos para cada tarefa, injete challenge, validate e seccode nos campos correspondentes e monitore taxas de rejeição no ambiente alvo. Consulte as tarifas atuais na página de preços.