Depuración de llamadas API CAPTCHA con Charles Proxy

¿La API de CaptchaAI te devuelve un token que el sitio de destino rechaza, o errores que no cuadran con tu código? La respuesta suele estar en el cable: ver qué solicitud sale y qué respuesta llega. Charles Proxy se coloca entre tu script y la API, y te deja inspeccionar cada solicitud, respuesta y detalle de timing. Aquí lo configuras y diagnosticas los fallos más comunes sin adivinar. Todo gira en torno a dos endpoints: /in.php (envío) y /res.php (sondeo).

Configurar Charles Proxy para inspeccionar la API

1. Instalar Charles Proxy

Descarga Charles desde charlesproxy.com. Funciona en Windows, macOS y Linux.

2. Activar el proxy SSL para el tráfico HTTPS

La API de CaptchaAI usa HTTPS; sin proxy SSL solo verás bytes cifrados. Para descifrar el tráfico:

1. Proxy → SSL Proxying Settings → Add
2. Host: ocr.captchaai.com, puerto: 443
3. Help → SSL Proxying → Install Charles Root Certificate
4. Marca el certificado como de confianza en tu sistema operativo

3. Apuntar tu código al proxy

Charles escucha en localhost:8888 de forma predeterminada. Configura tu cliente HTTP para que salga por ahí:

Python:

import requests

proxies = {
    "http": "http://localhost:8888",
    "https": "http://localhost:8888",
}

# Disable SSL verification for Charles (development only)
resp = requests.post(
    "https://ocr.captchaai.com/in.php",
    data={"key": "YOUR_API_KEY", "method": "userrecaptcha", "json": "1"},
    proxies=proxies,
    verify=False,
)

Node.js:

const axios = require('axios');
const HttpsProxyAgent = require('https-proxy-agent');

const agent = new HttpsProxyAgent('http://localhost:8888');

const resp = await axios.post('https://ocr.captchaai.com/in.php', null, {
  params: { key: 'YOUR_API_KEY', method: 'userrecaptcha', json: 1 },
  httpsAgent: agent,
});

Descartar los fallos del propio proxy

Antes de culpar a la API, confirma que Charles captura y descifra el tráfico. Los tropiezos de configuración más habituales:

Diagnosticar los fallos más frecuentes

ERROR_WRONG_GOOGLEKEY: el sitekey llega vacío

En el cuerpo de la solicitud de envío, busca el campo googlekey:

# What Charles shows:
key=YOUR_API_KEY&method=userrecaptcha&googlekey=&pageurl=https://example.com&json=1
                                      ^^^^^^^^ empty!

La causa está aguas arriba: la extracción del sitekey falló y enviaste un valor vacío. Revisa el código que lo obtiene de la página.

Es un caso habitual en QA de portales de cita previa —visados BLS, trámites del SAT o de AFIP—: funciona en local, pero en el servidor el token se rechaza porque el selector del sitekey cambió, y Charles lo revela al instante.

Las solicitudes nunca se resuelven

Usa la vista Sequence para ver el ritmo de las consultas:

POST /in.php     → 234ms ✓
GET  /res.php    → 189ms (CAPCHA_NOT_READY)
GET  /res.php    → 201ms (CAPCHA_NOT_READY)
GET  /res.php    → 195ms (CAPCHA_NOT_READY)
... 23 more ...
GET  /res.php    → 188ms (CAPCHA_NOT_READY)  ← never resolves

Si nunca llega el status: 1, revisa que el sitekey y la URL de la página sean los correctos.

El sitio de destino rechaza el token

Compara lo que devolvió CaptchaAI con lo que estás inyectando:

1. En Charles, localiza la respuesta de /res.php con status: 1
2. Copia el token completo del campo request
3. Busca la solicitud posterior al sitio de destino
4. Comprueba que el token viaje en el cuerpo del formulario como g-recaptcha-response

Referencia: qué debe contener cada solicitud

Cuando un fallo no encaje con los anteriores, contrasta la solicitud campo por campo contra esta referencia.

La solicitud de envío (POST /in.php)

La solicitud de sondeo (GET /res.php)

Funciones de Charles útiles para depurar CAPTCHA

Estas tres funciones aceleran la depuración:

Mapa local: simular respuestas sin gastar créditos

Sustituye las respuestas de la API por archivos locales para tus pruebas:

1. Tools → Map Local → Add
2. Asigna https://ocr.captchaai.com/res.php a un archivo JSON local
3. Crea mock_response.json:

{"status": 1, "request": "mock_token_for_testing"}

Así pruebas la inyección de token sin consumir créditos de la API.

Alternativas a Charles Proxy

Charles es de pago (con prueba gratuita). Otras opciones cumplen la misma función:

Configuración rápida de mitmproxy

# Install
pip install mitmproxy

# Run
mitmproxy --listen-port 8080

# Configure Python
proxies = {"https": "http://localhost:8080"}

Preguntas frecuentes

¿Por qué necesito activar el proxy SSL para ver el tráfico?

Porque la API usa HTTPS. Sin proxy SSL, Charles solo muestra datos cifrados; con el certificado raíz instalado y ocr.captchaai.com en SSL Proxying Settings, ves cada solicitud en claro.

¿Puedo inspeccionar el tráfico de Selenium o Puppeteer, no solo de la API?

Sí. Cualquier cliente que acepte un proxy explícito —requests, axios, Selenium, Puppeteer— se enruta por Charles apuntándolo a localhost:8888.

¿Es seguro dejar verify=False en el código?

No. verify=False desactiva la verificación del certificado TLS; solo tiene sentido mientras depuras en local. En producción, quítalo.

¿Qué alternativa gratuita a Charles me sirve para lo mismo?

mitmproxy y Fiddler. Ambas descifran HTTPS tras instalar su certificado raíz; mitmproxy además corre en Windows, macOS y Linux desde la terminal, ideal para servidores sin interfaz gráfica.

Guías relacionadas

• Registro estructurado para operaciones de CAPTCHA
• Referencia de códigos de error de CaptchaAI
• Colección Postman para probar la API de CaptchaAI