Métodos de autenticación de proxy para la API CaptchaAI

Cuando el sitio rechaza sin explicación un token que CaptchaAI devolvió correctamente, la causa suele ser la misma: el CAPTCHA se resolvió desde una IP y la página se cargó desde otra. El parámetro proxy de la API cierra esa brecha: le indicas por qué salida de red debe trabajar y el token nace asociado a la IP que el sitio espera ver.

Esa salida se autentica de cuatro formas — usuario y contraseña sobre HTTP, lo mismo sobre HTTPS (CONNECT), SOCKS5 y autorización por IP — y elegir la equivocada es el origen más frecuente de ERROR_PROXY_NOT_AUTHORIZED.

El formato del parámetro proxy, en una línea

La mecánica es la misma en los cuatro métodos: proxy es una cadena de campos separados por dos puntos y proxytype declara el protocolo.

Si tu proveedor te da la cadena al estilo user:pass@host:port de curl, reordénala: la API espera el host primero. Ese detalle explica buena parte de los ERROR_BAD_PARAMETERS.

Decide antes: ¿este desafío necesita proxy?

Pasar un proxy añade latencia y una dependencia externa que puede caerse. Úsalo solo cuando el token se valide contra la IP de origen.

Ante la duda, resuelve el mismo desafío con el parámetro y sin él en tu entorno de pruebas, y mira cuál acepta tu backend.

Método 1: usuario y contraseña sobre HTTP

Es el caso mayoritario y conviene montarlo primero: los demás son variaciones. Envías la tarea a in.php con proxy y proxytype, y consultas res.php hasta que deja de responder CAPCHA_NOT_READY.

import requests
import time

CAPTCHAAI_KEY = "YOUR_API_KEY"
CAPTCHAAI_URL = "https://ocr.captchaai.com"


def solve_with_http_proxy(site_url, sitekey, proxy_host, proxy_port,
                           proxy_user, proxy_pass):
    """Pass HTTP proxy to CaptchaAI for IP-matched solving."""
    proxy_param = f"{proxy_host}:{proxy_port}:{proxy_user}:{proxy_pass}"

    resp = requests.post(f"{CAPTCHAAI_URL}/in.php", data={
        "key": CAPTCHAAI_KEY,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": site_url,
        "proxy": proxy_param,
        "proxytype": "HTTP",
        "json": 1,
    })

    data = resp.json()
    if data["status"] != 1:
        raise Exception(f"Submit: {data['request']}")

    task_id = data["request"]

    for _ in range(60):
        time.sleep(5)
        resp = requests.get(f"{CAPTCHAAI_URL}/res.php", params={
            "key": CAPTCHAAI_KEY,
            "action": "get",
            "id": task_id,
            "json": 1,
        })
        data = resp.json()
        if data["request"] == "CAPCHA_NOT_READY":
            continue
        if data["status"] == 1:
            return data["request"]
        raise Exception(f"Solve: {data['request']}")

    raise TimeoutError("Timeout")


# Usage
token = solve_with_http_proxy(
    site_url="https://example.com/form",
    sitekey="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    proxy_host="proxy.example.com",
    proxy_port=8080,
    proxy_user="myuser",
    proxy_pass="mypass",
)

Método 2: usuario y contraseña sobre SOCKS5

La cadena no cambia; solo proxytype. SOCKS5 te interesa cuando tu proveedor únicamente expone ese protocolo o cuando necesitas que las resoluciones DNS salgan por la misma ruta.

def solve_with_socks5_proxy(site_url, sitekey, proxy_host, proxy_port,
                             proxy_user, proxy_pass):
    """Pass SOCKS5 proxy to CaptchaAI."""
    proxy_param = f"{proxy_host}:{proxy_port}:{proxy_user}:{proxy_pass}"

    resp = requests.post(f"{CAPTCHAAI_URL}/in.php", data={
        "key": CAPTCHAAI_KEY,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": site_url,
        "proxy": proxy_param,
        "proxytype": "SOCKS5",
        "json": 1,
    })

    data = resp.json()
    task_id = data["request"]

    for _ in range(60):
        time.sleep(5)
        resp = requests.get(f"{CAPTCHAAI_URL}/res.php", params={
            "key": CAPTCHAAI_KEY, "action": "get",
            "id": task_id, "json": 1,
        })
        data = resp.json()
        if data["request"] != "CAPCHA_NOT_READY":
            return data["request"]

    raise TimeoutError("Timeout")

Método 3: autorización por IP, sin credenciales

Muchos proveedores no usan credenciales, sino una lista de IP autorizadas. La cadena queda en dos campos:

def solve_with_whitelisted_proxy(site_url, sitekey, proxy_host, proxy_port):
    """Proxy with IP whitelist — no username/password."""
    proxy_param = f"{proxy_host}:{proxy_port}"

    resp = requests.post(f"{CAPTCHAAI_URL}/in.php", data={
        "key": CAPTCHAAI_KEY,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": site_url,
        "proxy": proxy_param,
        "proxytype": "HTTP",
        "json": 1,
    })

    data = resp.json()
    task_id = data["request"]

    for _ in range(60):
        time.sleep(5)
        resp = requests.get(f"{CAPTCHAAI_URL}/res.php", params={
            "key": CAPTCHAAI_KEY, "action": "get",
            "id": task_id, "json": 1,
        })
        data = resp.json()
        if data["request"] != "CAPCHA_NOT_READY":
            return data["request"]

    raise TimeoutError("Timeout")

Ojo con la dirección de la autorización: quien se conecta a tu proxy no eres tú, sino los servidores de CaptchaAI. Si tu lista solo incluye la IP de tu backend, la conexión se rechazará.

Método 4: proxy HTTPS (CONNECT)

Cuando la salida de red cifra el túnel, declara HTTPS y deja el resto igual. El bucle de sondeo no cambia en ningún método:

def solve_with_https_proxy(site_url, sitekey, proxy_host, proxy_port,
                            proxy_user, proxy_pass):
    proxy_param = f"{proxy_host}:{proxy_port}:{proxy_user}:{proxy_pass}"

    resp = requests.post(f"{CAPTCHAAI_URL}/in.php", data={
        "key": CAPTCHAAI_KEY,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": site_url,
        "proxy": proxy_param,
        "proxytype": "HTTPS",
        "json": 1,
    })

    # ... same polling logic ...

El mismo flujo en Node.js

En Node.js la estructura se repite: un objeto con host, puerto, credenciales y tipo, y un bucle que consulta hasta obtener el token o agotar el tiempo de espera.

const axios = require("axios");

const CAPTCHAAI_KEY = "YOUR_API_KEY";
const API = "https://ocr.captchaai.com";

async function solveWithProxy(siteUrl, sitekey, proxyConfig) {
  const params = {
    key: CAPTCHAAI_KEY,
    method: "userrecaptcha",
    googlekey: sitekey,
    pageurl: siteUrl,
    proxy: `${proxyConfig.host}:${proxyConfig.port}:${proxyConfig.user}:${proxyConfig.pass}`,
    proxytype: proxyConfig.type || "HTTP",
    json: 1,
  };

  const submit = await axios.post(`${API}/in.php`, null, { params });
  const taskId = submit.data.request;

  for (let i = 0; i < 60; i++) {
    await new Promise((r) => setTimeout(r, 5000));

    const result = await axios.get(`${API}/res.php`, {
      params: { key: CAPTCHAAI_KEY, action: "get", id: taskId, json: 1 },
    });

    if (result.data.request === "CAPCHA_NOT_READY") continue;
    if (result.data.status === 1) return result.data.request;
  }

  throw new Error("Timeout");
}

// Usage
const token = await solveWithProxy(
  "https://example.com/form",
  "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
  {
    host: "proxy.example.com",
    port: 8080,
    user: "myuser",
    pass: "mypass",
    type: "HTTP", // HTTP, HTTPS, SOCKS4, or SOCKS5
  }
);

Formatos de los proveedores más habituales

Cada proveedor codifica la sesión y la zona dentro del usuario, así que la cadena cambia de aspecto aunque el formato sea el mismo:

# Bright Data
proxy = "brd.superproxy.io:22225:brd-customer-ID-zone-residential:PASSWORD"
proxytype = "HTTP"

# Smartproxy
proxy = "gate.smartproxy.com:10001:spuser:sppassword"
proxytype = "HTTP"

# Oxylabs
proxy = "pr.oxylabs.io:7777:customer-USERNAME:PASSWORD"
proxytype = "HTTP"

Un caso concreto: QA repartido entre Madrid y Ciudad de México

Una agencia con el equipo técnico en Madrid mantiene el checkout de un cliente mexicano, protegido con Cloudflare Turnstile. Sus pruebas nocturnas, lanzadas desde un servidor europeo, fallaban al validar el token aunque CaptchaAI lo devolviera sin errores.

Arreglarlo fue cuestión de alinear las dos IP: la suite carga staging.example.com por la salida de red autorizada del cliente y pasa esa misma salida a CaptchaAI en proxy, con sesión fija para que la IP no cambie entre la carga y la resolución.

El costo encaja con cómo factura una agencia: CaptchaAI cobra por threads concurrentes, no por resolución, así que el gasto mensual en USD es predecible. Con BASIC ($15/mes, 5 threads) sobra para una suite nocturna; STANDARD ($30/mes, 15 threads) es el escalón habitual cuando varios proyectos comparten cuenta. Y como en toda automatización sobre sitios de terceros, respeta los términos de servicio y la normativa de protección de datos aplicable.

Errores frecuentes y cómo salir de ellos

Reintenta con una salida de red alternativa: un proxy caído no se arregla repitiendo la solicitud. Revisa también cómo influye la calidad de la salida en la tasa de resolución de tus CAPTCHA.

Preguntas frecuentes

¿Qué diferencia hay entre HTTP y HTTPS en proxytype?

Se refiere al canal entre CaptchaAI y tu proxy, no al sitio objetivo. Si tu proveedor te da un puerto TLS para el túnel CONNECT, declara HTTPS; si no, HTTP es correcto aunque la página sea https://.

¿Tengo que autorizar las IP de CaptchaAI en mi proveedor?

Sí, si usas autorización por IP en lugar de credenciales. La conexión sale de los servidores de CaptchaAI: si tu lista solo contiene la IP de tu aplicación, el proxy cortará el intento.

¿Pasar un proxy consume más threads de mi plan?

No. Un thread es un CAPTCHA en curso, con proxy o sin él. Lo que sí ocurre es que cada tarea ocupa su thread más tiempo, porque el enrutamiento añade segundos.

¿Cuánta latencia añade en la práctica?

Entre 2 y 5 segundos sobre tu tiempo habitual, y algo más si la salida está en otro continente. Ajusta el tiempo de espera del bucle de sondeo antes de dar la tarea por perdida.

¿Puedo usar proxies con rotación por solicitud?

Mejor evitarlo. Si la IP cambia entre solicitudes, CaptchaAI puede resolver desde una dirección distinta a la que cargó la página y el token pierde validez; usa sesión fija en todo el flujo.

Guías relacionadas

• SOCKS5 en pruebas autorizadas con CaptchaAI
• Cómo afecta la calidad del proxy a la tasa de resolución
• Checklist de QA antes de automatizar un formulario

Alinea la IP que carga la página con la IP que resuelve el CAPTCHA: obtén tu clave API y prueba el parámetro proxy en tu entorno de staging.