GeeTest v4: qué cambió frente a v3 y cómo resolverlo

¿Puede CaptchaAI resolver GeeTest v4 hoy? Todavía no: el soporte de GeeTest v4 llegará próximamente. Lo que sí resuelves hoy —y con una alta tasa de éxito— es GeeTest v3, que sigue siendo la versión más extendida en producción. Aun así, la v4 aparece en cada vez más sitios, así que conviene saber en qué se diferencia de la v3, cómo detectarla y qué dejar preparado para el día en que el soporte esté disponible. Eso es lo que cubre esta guía.

GeeTest v3 frente a v4: qué cambió

En la práctica, estas diferencias tienen una consecuencia directa: el código que funcionaba con la v3 no sirve tal cual para la v4. Cambia el parámetro con el que arranca el desafío, cambian los tokens que valida el servidor y cambia incluso el dominio al que apunta el widget. Por eso el primer trabajo no es resolver, sino identificar bien la versión.

Los cuatro tipos de desafío de GeeTest v4

Rompecabezas deslizante

El desafío clásico: arrastras una pieza hasta encajarla en el hueco correcto.

Selección por clic

Haces clic sobre objetos concretos (por ejemplo, "haz clic en todas las caras"). Se apoya en reconocimiento de iconos.

Razonamiento espacial

Novedad de la v4: organizas varias formas siguiendo un patrón espacial. Es más complejo que cualquier desafío de la v3.

Coincidencia de iconos

Debes emparejar los iconos que aparecen en una secuencia. Cuesta más de automatizar a mano.

Cuando el soporte de v4 esté disponible, la API de CaptchaAI abstraerá la lógica específica de cada desafío, igual que hace hoy con la v3. Por ahora, CaptchaAI resuelve GeeTest v3; el soporte de v4 llegará próximamente.

Cómo detectar la versión en una página

El primer paso, siempre, es saber qué versión protege la página. Imagina que haces QA sobre el login de un marketplace regional o sobre un portal de cita previa: antes de integrar nada, extrae la configuración del CAPTCHA y comprueba si es v3 o v4. La v4 usa captcha_id en lugar del par gt + challenge, y carga el script gcaptcha4. Este fragmento con Selenium lo detecta:

# extract_geetest_v4.py
import re
from selenium import webdriver


def extract_geetest_v4_params(url):
    """Extract GeeTest v4 captcha_id from a page."""
    driver = webdriver.Chrome()
    driver.get(url)

    page_source = driver.page_source

    # GeeTest v4 uses captcha_id instead of gt
    match = re.search(r'captcha_id["\']?\s*[:=]\s*["\']([a-f0-9]+)', page_source)
    captcha_id = match.group(1) if match else None

    # Check for v4-specific script
    is_v4 = "gcaptcha4" in page_source or "gt4.js" in page_source

    driver.quit()

    return {
        "captcha_id": captcha_id,
        "is_v4": is_v4,
        "pageurl": url,
    }


# Usage
params = extract_geetest_v4_params("https://staging.example.com/qa-login")
print(f"Captcha ID: {params['captcha_id']}")
print(f"Is v4: {params['is_v4']}")

Resolver GeeTest v4: estado actual y flujo previsto

El soporte de GeeTest v4 está en la hoja de ruta de CaptchaAI, pero todavía no está disponible de forma general: solo puede describirse como próximamente. Mientras llega, usa GeeTest v3, que CaptchaAI resuelve hoy con una alta tasa de éxito. Como el resto de tipos, GeeTest se factura por thread y no por resolución, así que un mismo plan absorbe los picos de volumen sin coste por CAPTCHA.

El siguiente código muestra el flujo previsto para la v4 —envío de la tarea y sondeo del resultado— para que dejes tu integración lista de antemano. Antes de ponerlo en producción, confirma el estado en la página de tipos compatibles de CaptchaAI.

# solve_geetest_v4.py
import requests
import time
import os


def solve_geetest_v4(captcha_id, pageurl):
    """Submit GeeTest v4 to CaptchaAI and get solution."""
    api_key = os.environ["CAPTCHAAI_API_KEY"]

    # Submit task
    resp = requests.post("https://ocr.captchaai.com/in.php", data={
        "key": api_key,
        "method": "geetest",
        "gt": captcha_id,      # captcha_id maps to the gt parameter
        "pageurl": pageurl,
        "version": "4",        # Specify v4 explicitly
        "json": 1,
    }, timeout=30)

    result = resp.json()
    if result.get("status") != 1:
        raise RuntimeError(f"Submit failed: {result.get('request')}")

    task_id = result["request"]

    # Poll for result
    time.sleep(10)
    for _ in range(30):
        resp = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": api_key,
            "action": "get",
            "id": task_id,
            "json": 1,
        }, timeout=15)
        data = resp.json()

        if data.get("status") == 1:
            return data["request"]  # Contains validation tokens
        if data["request"] != "CAPCHA_NOT_READY":
            raise RuntimeError(data["request"])
        time.sleep(5)

    raise TimeoutError("GeeTest v4 solve timeout")


# Usage
solution = solve_geetest_v4(
    captcha_id="abc123def456",
    pageurl="https://staging.example.com/qa-login",
)
print(f"Solution: {solution}")

Inyectar la solución en la página

La validación de la v4 no devuelve los mismos tokens que la v3: en lugar de un único challenge, trabaja con lot_number, pass_token, gen_time y captcha_output. Cuando el soporte esté disponible, tendrás que inyectar esos cuatro valores en los campos ocultos del formulario antes de enviarlo. Este ayudante deja esa parte preparada:

# inject_geetest_v4.py
import json
from selenium import webdriver
from selenium.webdriver.common.by import By


def inject_geetest_v4_solution(driver, solution):
    """Inject GeeTest v4 solution tokens into the page."""
    # Parse solution — v4 returns different tokens than v3
    if isinstance(solution, str):
        try:
            solution = json.loads(solution)
        except json.JSONDecodeError:
            pass

    # GeeTest v4 validation uses lot_number, pass_token, gen_time, captcha_output
    driver.execute_script("""
        var solution = arguments[0];

        // Set hidden form fields
        var fields = {
            'lot_number': solution.lot_number,
            'pass_token': solution.pass_token,
            'gen_time': solution.gen_time,
            'captcha_output': solution.captcha_output,
        };

        for (var name in fields) {
            var input = document.querySelector('input[name="' + name + '"]');
            if (!input) {
                input = document.createElement('input');
                input.type = 'hidden';
                input.name = name;
                document.forms[0].appendChild(input);
            }
            input.value = fields[name];
        }

        // Trigger validation callback if available
        if (window.captchaObj && typeof window.captchaObj.appendTo === 'function') {
            window.captchaObj.appendTo('#captcha-container');
        }
    """, solution)

Errores frecuentes y cómo resolverlos

Cuando prepares o pruebes la integración, estos son los fallos que aparecen con más frecuencia:

Preguntas frecuentes

¿Está disponible el soporte de GeeTest v4 en CaptchaAI?

Todavía no. El soporte de GeeTest v4 llegará próximamente; hoy CaptchaAI resuelve GeeTest v3 con una alta tasa de éxito. Deja tu integración preparada y confirma el estado en la página de tipos compatibles antes de ponerla en producción.

¿Cómo detecto si un sitio usa GeeTest v3 o v4?

Busca gcaptcha4.geetest.com o gt4.js en el código de la página: si aparecen, es v4. Si en cambio ves api.geetest.com y un parámetro challenge, estás ante la v3.

¿Tendré que rehacer mi integración cuando llegue el soporte de v4?

No desde cero. La v4 cambia los parámetros de entrada (captcha_id) y los tokens de salida (lot_number, pass_token…), pero el patrón de enviar la tarea y sondear el resultado es el mismo que ya usas con la v3.

¿Qué tipos de desafío añade GeeTest v4 frente a v3?

Además del deslizamiento y el clic que ya existían en v3, la v4 suma el razonamiento espacial y la coincidencia de iconos, y aplica una dificultad adaptativa según la puntuación de riesgo de cada visita.

Guías relacionadas

• Parámetros del desafío deslizante de GeeTest
• GeeTest frente a Cloudflare Turnstile

Resuelve GeeTest v3 hoy con CaptchaAI; el soporte de GeeTest v4 llegará próximamente.