Fluxo de trabalho de resposta ao desafio GeeTest v3: aprofundamento técnico

O GeeTest v3 não entrega um único token como o reCAPTCHA — ele troca três valores em duas chamadas de API. Se a integração com a CaptchaAI falha, o motivo quase sempre é gt/challenge capturados no momento errado, ou a resposta incompleta ao backend.

Resumo rápido

• O GeeTest v3 troca gt e challenge no registro, depois devolve geetest_challenge, geetest_validate e geetest_seccode.
• Cada challenge vale para uma sessão só e expira em 1–2 minutos.
• A CaptchaAI recebe gt + challenge e devolve os três valores prontos para o formulário.
• GeeTest v4 ainda não é suportado — só v3.

Como funciona o protocolo em duas fases do GeeTest v3

Fase 1 — registro no lado do servidor. O backend do site entra em contato com a GeeTest para registrar um novo desafio:

Site Backend → GeeTest Server: "Give me a challenge for this user"
GeeTest Server → Site Backend: { gt, challenge, new_captcha }
Site Backend → Browser: Passes gt and challenge to the page

Fase 2 — verificação no lado do cliente e do servidor. O navegador renderiza o desafio, o usuário resolve e o resultado é verificado:

Browser: Renders slider/puzzle using gt + challenge
User: Solves the challenge
Browser → Site Backend: { geetest_challenge, geetest_validate, geetest_seccode }
Site Backend → GeeTest Server: Verifies the three values
GeeTest Server → Site Backend: { result: "success" }

O fluxo de resposta ao desafio GeeTest v3, passo a passo

Etapa 1: chamada à API de registro

O backend do site faz essa primeira chamada ao endpoint de registro da GeeTest:

GET https://api.geetest.com/register.php?gt=GT_ID&json_format=1

Resposta:

{
  "success": 1,
  "gt": "81dc9bdb52d04dc20036dbd8313ed055",
  "challenge": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "new_captcha": true
}

• gt — ID da GeeTest, identifica a conta GeeTest cadastrada no site.
• challenge — token de desafio exclusivo para esta sessão.
• new_captcha — indica se o widget deve usar o novo formato de CAPTCHA.

Atenção: challenge é de uso único e expira em 1–2 minutos. Cada carregamento de página gera um desafio novo.

Etapa 2: renderização do desafio

Com gt e challenge no navegador, o script inicializa o widget:

initGeetest({
  gt: "81dc9bdb52d04dc20036dbd8313ed055",
  challenge: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  offline: false,
  new_captcha: true,
  product: "float"
}, function(captchaObj) {
  captchaObj.appendTo('#captcha-container');
  captchaObj.onSuccess(function() {
    var result = captchaObj.getValidate();
    // result contains: geetest_challenge, geetest_validate, geetest_seccode
  });
});

Etapa 3: valores da solução

Depois que o usuário resolve o desafio, o widget devolve três valores:

{
  "geetest_challenge": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6xy",
  "geetest_validate": "abc123def456_validate",
  "geetest_seccode": "abc123def456_validate|jordan"
}

• geetest_challenge — token de desafio modificado (o valor original mais dois caracteres extras).
• geetest_validate — hash de validação da resposta.
• geetest_seccode — código de segurança: validate + sufixo literal \|jordan.

Etapa 4: verificação no lado do servidor

O backend do site envia esses três valores à GeeTest para confirmar a resposta:

POST https://api.geetest.com/validate.php

seccode=abc123def456_validate|jordan
&challenge=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6xy
&sdk=geetest-python-3.0.0

A GeeTest responde com:

{
  "seccode": "abc123def456_validate",
  "validate": "abc123def456_validate"
}

Como extrair gt e challenge da página

Para enviar a tarefa à CaptchaAI, capture gt e challenge antes que o desafio expire, de uma destas formas:

Método 1: interceptar a resposta do registro

A forma mais confiável: escutar a resposta de rede do registro e ler gt/challenge do JSON:

from playwright.sync_api import sync_playwright
import json

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()

    geetest_params = {}

    def handle_response(response):
        if "register" in response.url and "geetest" in response.url:
            data = response.json()
            geetest_params["gt"] = data.get("gt")
            geetest_params["challenge"] = data.get("challenge")

    page.on("response", handle_response)
    page.goto("https://staging.example.com/qa-login")

    # Wait for GeeTest to load
    page.wait_for_selector(".geetest_holder")
    print(f"gt: {geetest_params.get('gt')}")
    print(f"challenge: {geetest_params.get('challenge')}")

Método 2: sem interceptar rede

Sem acesso ao tráfego de rede, dá para ler os valores direto do DOM, se o site os expõe como atributos data-*:

gt = page.evaluate("() => document.querySelector('[data-gt]')?.dataset.gt")
challenge = page.evaluate("() => document.querySelector('[data-challenge]')?.dataset.challenge")

Se nem isso funcionar, procure a chamada initGeetest na origem da página com regex:

import re
source = page.content()
gt_match = re.search(r"gt['\"]?\s*[:=]\s*['\"]([a-f0-9]{32})['\"]", source)
challenge_match = re.search(r"challenge['\"]?\s*[:=]\s*['\"]([a-f0-9]{32})['\"]", source)

Como resolver o desafio GeeTest v3 com a CaptchaAI

Com gt e challenge em mãos, envie a tarefa para a API:

POST https://ocr.captchaai.com/in.php

key=YOUR_API_KEY
&method=geetest
&gt=81dc9bdb52d04dc20036dbd8313ed055
&challenge=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
&pageurl=https://staging.example.com/qa-login
&json=1

Consulte o resultado com uma chamada GET:

GET https://ocr.captchaai.com/res.php?key=YOUR_API_KEY&action=get&id=TASK_ID&json=1

A CaptchaAI retorna os três valores prontos para injetar no formulário:

{
  "status": 1,
  "request": {
    "geetest_challenge": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6xy",
    "geetest_validate": "abc123def456_validate",
    "geetest_seccode": "abc123def456_validate|jordan"
  }
}

Basta preencher os campos do formulário com geetest_challenge, geetest_validate e geetest_seccode e enviar — nenhuma etapa extra é necessária do seu lado.

Cenário comum: um checkout de e-commerce brasileiro usa o GeeTest v3 no login antes de uma campanha promocional. No pipeline de QA em staging.example.com, não registre tokens de sessões reais — dados vinculados a um usuário entram no escopo da LGPD, então use só dados fictícios.

Tipos de desafio do GeeTest v3

O GeeTest v3 decide o tipo de desafio em tempo real — mas o payload enviado à CaptchaAI (gt + challenge) é sempre o mesmo, então a integração trata qualquer tipo igual:

• Controle deslizante (slider): arrastar a peça do quebra-cabeça até a posição correta da imagem.
• Clique em ícones: clicar nos ícones específicos na sequência mostrada.
• Clique em palavras: clicar nos caracteres chineses na ordem correta.
• Espacial: desafio de raciocínio espacial, resolvido por clique ou seleção.

Modo online x offline

Modo de contingência para quando os servidores da GeeTest ficam inacessíveis: success: 1 é a resposta normal; success: 0 cai para verificação local simplificada. A maioria dos sites usa o modo online — o offline só entra quando a GeeTest está fora do ar.

Solução de problemas comuns

• challenge vazio — o registro falhou; confira se o site está carregando o GeeTest corretamente.
• Solução rejeitada — o desafio expirou; extraia um challenge novo e resolva imediatamente.
• gt incorreto — há várias instâncias do GeeTest na página; extraia o gt do widget certo.
• Os três valores voltam, mas o formulário não envia — faltam campos; injete os três valores nas entradas corretas.
• Registro lento para responder — latência alta até o servidor da GeeTest; rode o worker mais perto (ex.: sa-east-1 na AWS).

Perguntas frequentes

O CaptchaAI resolve todos os tipos de desafio do GeeTest v3?

Sim. Slider, ícones, palavras e desafios espaciais usam a mesma chamada de API — você envia gt e challenge, e a CaptchaAI identifica o tipo automaticamente.

Posso reutilizar o mesmo challenge em duas tentativas?

Não. Cada challenge vale para uma única resposta. Depois de resolvido — ou expirado — busque um novo na chamada de registro.

O GeeTest v4 já é suportado pela CaptchaAI?

Ainda não. A CaptchaAI resolve o GeeTest v3 de forma nativa; o suporte ao v4 está em preparação e será anunciado quando estiver disponível.

Preciso rodar o navegador em modo headless para capturar gt e challenge?

Não. A interceptação de rede (Método 1) funciona igual em headless — o que importa é escutar a resposta do registro antes do widget renderizar.

Artigos relacionados

• Como resolver GeeTest v3 em Node.js
• Resolvendo GeeTest v3 em Node.js com a CaptchaAI
• Aprofundamento na API de avaliação do reCAPTCHA Enterprise

Próximas etapas

Resolva desafios do GeeTest v3 na prática — obtenha sua chave de API da CaptchaAI e integre a resposta de três valores ao seu fluxo de trabalho.