Scarnox · Blog

API para resolver captchas: cómo funciona y cómo llamarla

Una API para resolver captchas es un servicio web al que llamas por HTTP. Le envías los datos de un captcha, es decir, el tipo de tarea, la sitekey de la página y la URL de la página, y devuelve un token que el sitio de destino acepta como prueba de que el desafío se superó. El endpoint de Scarnox funciona así y es síncrono, de modo que una sola petición te da la respuesta.

Esta guía cubre la petición, la respuesta, la forma de los errores y los detalles que determinan si una integración aguanta en producción. Si quieres primero un script que puedas ejecutar, empieza por Cómo resolver PopularCaptcha en Python.

Qué hace la API y qué no hace

Tu código encuentra el captcha en una página, lee su sitekey y se la envía al solver. El solver devuelve un token. Tu código escribe ese token en el campo del formulario que espera el sitio y envía el formulario.

El solver no carga tu página, no hace clic en nada y no envía tu formulario. Solo produce el token. Tener presente ese límite hace más fácil razonar sobre el resto de la integración: todo lo relativo a tu sesión, cookies y tiempos de petición se queda en tu código.

Hoy el único tipo de tarea en vivo es PopularCaptcha, sin proxy, que es PopularCaptchaTaskProxyless. Otros tipos de captcha están en la hoja de ruta. La guía de tipos de captcha indica cuál es cuál.

El endpoint

Envía una petición POST a:

POST https://api.scarnox.com/api/tasks/create
Authorization: Bearer scarnox_YOURAPIKEY
Content-Type: application/json

El cuerpo describe la tarea:

{
  "captcha_type": "PopularCaptchaTaskProxyless",
  "site_key": "10000000-ffff-ffff-ffff-000000000001",
  "site_url": "https://example.com/signup"
}

Los tres campos obligatorios son:

captcha_type: el tipo de tarea. Para resoluciones en vivo hoy es PopularCaptchaTaskProxyless.
site_key: la sitekey leída de la página. Las sitekeys de PopularCaptcha son UUID.
site_url: la URL de la página donde aparece el captcha. Usa la página real, no la página de inicio, porque el token está vinculado a la página que mostró el widget.

Existen tres campos opcionales. proxy acepta un valor con la forma http://user:pass@host:port y se usa con los tipos de tarea con proxy. rqdata e is_invisible son para variantes concretas del widget. La lista completa de tipos de tarea y detalles de campos está en la referencia de la API.

Síncrono significa sin sondeo

La llamada se bloquea hasta que el token está listo. No haces sondeo, y en este flujo no hay una segunda petición de "obtener resultado". Configura el timeout de tu cliente HTTP en unos 185 segundos para que una resolución lenta no parezca un fallo de red.

En Python con la biblioteca requests, queda así:

import requests

r = requests.post(
    "https://api.scarnox.com/api/tasks/create",
    headers={"Authorization": "Bearer scarnox_YOURAPIKEY"},
    json={
        "captcha_type": "PopularCaptchaTaskProxyless",
        "site_key": "10000000-ffff-ffff-ffff-000000000001",
        "site_url": "https://example.com/signup",
    },
    timeout=185,
)
data = r.json()

Lee la clave de una variable de entorno en lugar de escribirla en el script. Quien pueda leer el código fuente no debería poder usar tu saldo.

Leer la respuesta

Una resolución correcta devuelve un errorId de 0, el token dentro de solution y un campo cost:

{"errorId": 0, "solution": {"token": "..."}, "cost": ...}

Una resolución fallida devuelve un errorId distinto de 0, además de un errorCode legible por máquina y un errorDescription legible por personas:

{"errorId": 1, "errorCode": "...", "errorDescription": "..."}

Comprueba errorId en el cuerpo en cada llamada. No des por hecho que una petición HTTP completada significa que tienes un token. La regla más importante es esta: solo se cobra cuando errorId es 0. Las resoluciones fallidas son gratuitas. Para las tarifas actuales, consulta la página de precios.

Vida útil del token

Los tokens de PopularCaptcha caducan en unos dos minutos. Envía el token en cuanto lo recibas. No guardes tokens para usarlos más tarde, y no resuelvas antes del envío del formulario. Si tu código da varios pasos entre obtener el token y enviar el formulario, mueve la resolución al último momento.

Poner el token en el formulario

La mayoría de los sitios leen la respuesta de PopularCaptcha de un campo de formulario llamado h-captcha-response. Muchos también aceptan g-recaptcha-response con el mismo valor, así que enviar ambos es una opción segura y habitual:

requests.post("https://example.com/signup", data={
    "email": "you@example.com",
    "h-captcha-response": token,
    "g-recaptcha-response": token,
})

Si el formulario no acepta el token, la causa suele ser una sitekey o una URL de página que no coinciden con la página donde estaba realmente el widget. Revisa los valores antes de culpar al solver.

Gestión de errores

Una integración en producción necesita una lista corta de buenas prácticas:

Comprueba errorId y registra errorCode en cada llamada. Es el código que soporte te pedirá primero.
Reintenta las resoluciones fallidas con un backoff pequeño. Como las resoluciones fallidas son gratuitas, un reintento no te cuesta una resolución, pero un bucle ajustado sigue desperdiciando tiempo y puede chocar con tus propios límites de frecuencia.
Configura un timeout de cliente de unos 185 segundos, y trata un timeout como un error que se reintenta, no como un éxito.
Mantén el token y el envío del formulario juntos en el tiempo, ya que el token caduca rápido.

La guía de reintentos y gestión de errores profundiza en cada uno de estos puntos.

Primeros pasos

Crea una cuenta y puedes empezar con crédito de prueba gratis, sin tarjeta. Después ejecuta la petición de arriba contra una página de prueba que controles, y comprueba que el formulario acepta el token antes de conectarlo a algo que importe.