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
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 v3, 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 v3, 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 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 distinguir utilizadores 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 utilizador é feita principalmente com base no comportamento e na interação com o site, sem necessidade de resolver desafios adicionais.
Slide CAPTCHA
Slide CAPTCHA
Um controlo deslizante (slider) que deve ser movido para completar um puzzle 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 o local correto na imagem.

Como resolver GeeTest CAPTCHA v3 com o CapMonster Cloud

Ao testar formulários que incluem GeeTest CAPTCHA v3, é 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 v3 com recurso a bibliotecas prontas
O serviço CapMonster Cloud fornece 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: utilizar pedidos HTTP para obter o HTML e os parâmetros da CAPTCHA, enviar a resposta e tratar o resultado; ou, com ferramentas de automatização (por exemplo, Playwright), abrir a página, aguardar o carregamento da CAPTCHA, enviar os parâmetros (para testes pode enviar tanto dados corretos como incorretos), obter a solução através 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('A abrir a página...');
  await page.goto(DEMO_PAGE, { waitUntil: 'networkidle' });

  console.log('A obter os parâmetros da CAPTCHA...');
  const init = await page.evaluate(async () => {
    // Enviamos um pedido 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('A criar uma tarefa para o 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('A inserir 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('A enviar o pedido 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 ligar GeeTest CAPTCHA v3 ao seu site
Para compreender bem o funcionamento da CAPTCHA no seu site, a lógica de validação e a forma de a voltar a ligar ou reconfigurar, recomendamos que leia esta secção. Nela é descrito o processo de configuração da proteção — isto ajudará a percorrer rapidamente todos os pormenores.

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

2. Aceda ao Captcha Dashboard e selecione CAPTCHA v3:

HowTo Connect image 1

3. Clique em +New Captcha para criar uma nova CAPTCHA. Indique o nome da CAPTCHA (por exemplo, o produto ou projeto), o URL do site onde será integrada e escolha o contexto de utilização da CAPTCHA (por exemplo, Login / Registo / Recuperação de palavra-passe, etc.).

4. Irá receber um CAPTCHA ID e um KEY únicos. Estes podem ser configurados no painel de segurança.

HowTo Connect image 2

5. Configure a parte do 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. Ligue a parte do cliente (Client SDK):

No cliente, carrega-se gt.js e chama-se initGeetest, passando os parâmetros vindos do servidor (API1). Exemplo com 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');
                    }
                });
            });
        });
    }
});

Verificação do funcionamento

Certifique-se de que:

  • /register devolve um challenge
  • A CAPTCHA é exibida corretamente
  • Após a conclusão da CAPTCHA é visível, na consola do navegador, um pedido para /validate
  • O servidor devolve "success": true

Failback (modo de reserva)

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

  • O cliente recebe success: false
  • A CAPTCHA muda para o modo local (funciona sem ligação ao GeeTest Cloud). Para testar, basta introduzir 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 devolve o erro invalid-gt / invalid-challenge. Verifique se está a utilizar 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 quando utilizar 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 são corretamente inseridos nos campos ocultos do formulário.
Bug Icon
Resposta success=false
o token expirou, foi reutilizado ou é falso. Para diagnóstico, ative o registo (logging) dos pedidos e verifique os campos devolvidos pelo servidor (por exemplo, os error-codes ao trabalhar com o CapMonster ou com o seu servidor de validação).
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 não a envie para a parte cliente.
Registe (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 compreender as causas das validações falhadas.
Adicione no final do formulário ligações para a <span class="font-bold">Política de Privacidade</span> e para os <span class="font-bold">Termos de Utilização da GeeTest</span>, se tal for exigido pela licença ou pelas suas 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 v3, 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 v3 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 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 respetivamente para os campos ocultos geetest_challenge, geetest_validate e geetest_seccode antes de enviar o formulário. Pode injetá-los com Playwright, Puppeteer, Selenium ou um cliente HTTP simples.

Nota: consulte em intervalos regulares e não exceda 120 pedidos por tarefa para evitar bloqueio da conta. Conforme a carga do sistema, a resposta costuma chegar em 10 a 30 segundos.

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

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

Para automação com Playwright ou outro browser headless, intercete a resposta init-params ao nível da rede — é mais rápido e fiá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. Neste modo, o widget continua a ser renderizado e o utilizador 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 precisa de 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 monitorize taxas de rejeição no ambiente alvo. Consulte as tarifas atuais na página de preços.