Cómo implementar una API de resolución de CAPTCHA en JavaScript

TL;DR

• CapSolver expone una API REST sencilla: llama a /createTask para enviar un CAPTCHA y luego consulta /getTaskResult hasta que status === 'ready'.
• Tipos de desafíos soportados en esta guía: reCAPTCHA v2, reCAPTCHA v3 y Cloudflare Turnstile.
• Almacena tu clave de API en .env, nunca la codifiques directamente.
• Usa axios + un bucle de sondeo para una integración de Node.js limpia y lista para producción.
• Agrega lógica de reintentos con retroalimentación exponencial para resiliencia en trabajos de automatización de largo plazo.

Introducción

Los proyectos de automatización web y recopilación de datos modernos a menudo encuentran desafíos CAPTCHA que interrumpen los flujos de trabajo. Ya sea que estés construyendo un scraper web, automatizando tareas del navegador o desarrollando un agente de inteligencia artificial, integrar una solución confiable para resolver CAPTCHA se convierte en algo esencial. CapSolver proporciona una API potenciada por IA que maneja estos desafíos de forma programática, y esta guía te muestra cómo implementarla en JavaScript desde cero.

El tráfico automatizado ahora representa casi la mitad de todo el tráfico de internet, lo que hace que la detección de bots y los desafíos CAPTCHA sean cada vez más comunes en las aplicaciones web. Para los desarrolladores que construyen flujos de automatización legítimos, tener una solución programática confiable ya no es opcional, es un requisito fundamental de infraestructura.

Comprendiendo el flujo de trabajo de la API de CapSolver

Antes de sumergirte en el código, comprender cómo procesa CapSolver las solicitudes de CAPTCHA te ayudará a diseñar correctamente tu integración. El flujo sigue un patrón sencillo: enviar una tarea, consultar su finalización y recibir la solución.

Cuando envías un desafío CAPTCHA a CapSolver, el sistema le asigna un identificador de tarea único. Tu aplicación luego consulta al servicio en intervalos regulares hasta que la solución esté lista. Una vez completada, recibes una respuesta que contiene el token o los datos necesarios para continuar con tu flujo de automatización.

CapSolver soporta varios tipos de CAPTCHA, incluyendo desafíos de reCAPTCHA v2/v3, Cloudflare Turnstile y CAPTCHA de imagen a texto. El flujo de la API es consistente entre los tipos de desafíos, aunque los parámetros de tarea varían según la solución específica requerida. Para una lista completa de los tipos de tarea soportados, consulta la referencia de tipos de tarea de CapSolver. Si eres nuevo en la plataforma, la guía de inicio cubre la configuración de la cuenta y tu primera llamada a la API. Para una visión general más amplia de cómo CapSolver encaja en los pipelines de scraping, consulta cómo integrar CapSolver en tu flujo de automatización.

Configuración del Proyecto

Esta guía te muestra cómo implementar la API de resolución de CAPTCHA de CapSolver específicamente para proyectos de JavaScript y Node.js. Asegúrate de tener instalado Node.js 18+ y tener lista una clave de API de CapSolver desde tu panel de control.

Estructura del proyecto:

capsolver-integration/
├── .env                 # Variables de entorno
├── capsolver-client.js  # Cliente de API principal
├── index.js             # Ejemplo de uso
└── package.json

Inicializa tu proyecto e instala las dependencias:

mkdir capsolver-integration
cd capsolver-integration
npm init -y
npm install axios dotenv

axios es un cliente HTTP ampliamente utilizado para Node.js que proporciona una sintaxis basada en promesas limpia y manejo integrado de tiempos de espera—ambos útiles al consultar una API externa.

Crea un archivo .env para almacenar tu clave de API de forma segura:

CAPSOLVER_API_KEY=your-api-key-here

Nota de seguridad: Nunca comprometas tu archivo .env en el control de versiones. Añádelo inmediatamente a .gitignore. Las claves de API expuestas pueden llevar a un uso no autorizado y cargos inesperados. Consulta Administración de secretos de OWASP para mejores prácticas sobre el manejo de credenciales en proyectos de automatización.

Creando el Cliente de API Principal

La base de tu integración es un cliente reutilizable que maneja la autenticación y el formateo de solicitudes. Este cliente encapsula el punto final de la API y proporciona métodos para cada operación. Guárdalo como capsolver-client.js:

// capsolver-client.js
const axios = require('axios');

class CapSolverClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.capsolver.com';
  }

  async request(endpoint, data) {
    const response = await axios.post(`${this.baseUrl}${endpoint}`, {
      ...data,
      clientKey: this.apiKey
    }, {
      headers: { 'Content-Type': 'application/json' },
      timeout: 30000
    });
    return response.data;
  }

  delay(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

module.exports = CapSolverClient;

Nota: Los ejemplos de código en esta guía ilustran patrones de implementación basados en la estructura de API documentada de CapSolver. Siempre verifica los caminos de los puntos finales más recientes, los nombres de los tipos de tarea y los formatos de solicitud/respuesta contra la documentación oficial de la API de CapSolver, ya que estos detalles pueden cambiar.

Este cliente maneja las tareas repetitivas de comunicación con la API, incluyendo la configuración de encabezados y el formateo del cuerpo de la solicitud con tu clave de cliente.

Verificar tu Saldo de Cuenta

Antes de resolver CAPTCHAS a gran escala, verifica que tu cuenta tenga créditos suficientes. CapSolver opera bajo un modelo de pago por solución exitosa, por lo que verificar tu saldo evita fallas inesperadas durante el flujo de trabajo.

// Añade al método de CapSolverClient
async getBalance() {
  const result = await this.request('/getBalance', {});

  if (result.errorCode) {
    throw new Error(`Error al verificar el saldo: ${result.errorCode} - ${result.errorDescription}`);
  }

  return {
    balance: result.balance,
    currency: result.currency || 'USD'
  };
}

Muchos desarrolladores incluyen una verificación de saldo en su secuencia de inicialización para fallar rápidamente si los créditos se agotan antes de iniciar una automatización prolongada.

Resolver reCAPTCHA v2

reCAPTCHA v2 presenta el desafío de casilla de verificación familiar o tareas de selección de imágenes. Para resolver estos desafíos, necesitas la URL de la página objetivo y la clave del sitio integrada en el HTML de la página. El token resuelto se envía luego como parte del formulario o la solicitud.

// Añade al método de CapSolverClient
async solveReCaptchaV2(websiteUrl, websiteKey) {
  const task = {
    type: 'RecaptchaV2Task',
    websiteURL: websiteUrl,
    websiteKey: websiteKey
  };
  return await this.submitAndWait(task);
}

async submitAndWait(task) {
  // Paso 1: Enviar la tarea
  const submitResult = await this.request('/createTask', { task });

  if (submitResult.errorCode) {
    throw new Error(`Error al crear la tarea: ${submitResult.errorCode}`);
  }

  const taskId = submitResult.taskId;

  // Paso 2: Consultar el resultado
  while (true) {
    await this.delay(1500);

    const result = await this.request('/getTaskResult', { taskId });

    if (result.status === 'ready') {
      return result.solution;
    }

    if (result.status === 'failed') {
      throw new Error(`Error al resolver: ${result.errorDescription || 'Error desconocido'}`);
    }
    // status === 'processing' → continuar consultando
  }
}

El intervalo de sondeo de 1.5 segundos equilibra la respuesta con los límites de tasa de la API. El campo status será processing mientras la tarea esté en ejecución, ready cuando la solución esté disponible o failed si el desafío no se pudo resolver. Para el esquema completo de la respuesta, consulta la referencia de la API getTaskResult.

Resolver reCAPTCHA v3

reCAPTCHA v3 funciona de forma diferente: opera en segundo plano y devuelve una puntuación de riesgo en lugar de presentar un desafío visual. CapSolver puede resolver desafíos v3 permitiéndote especificar el umbral de puntuación mínimo requerido por tu sitio objetivo.

// Añade al método de CapSolverClient
async solveReCaptchaV3(websiteUrl, websiteKey, options = {}) {
  const {
    pageAction = 'verify',
    minScore = 0.9
  } = options;

  const task = {
    type: 'RecaptchaV3Task',
    websiteURL: websiteUrl,
    websiteKey: websiteKey,
    pageAction: pageAction,
    minScore: minScore
  };

  return await this.submitAndWait(task);
}

Las tareas de reCAPTCHA v3 suelen completarse más rápido que las de v2, ya que no requieren interacción con desafíos visuales. El parámetro pageAction debe coincidir con la cadena de acción definida en la página objetivo.

Resolver Cloudflare Turnstile

Los desafíos de Cloudflare Turnstile aparecen frecuentemente en los flujos de automatización, especialmente al raspar sitios protegidos por Cloudflare. CapSolver ofrece soporte dedicado para estos desafíos:

// Añade al método de CapSolverClient
async solveTurnstile(websiteUrl, websiteKey, options = {}) {
  const {
    pageAction = 'managed',
    metadata = {}
  } = options;

  const task = {
    type: 'AntiCloudflareTask',
    websiteURL: websiteUrl,
    websiteKey: websiteKey,
    pageAction: pageAction,
    metadata: metadata
  };

  return await this.submitAndWait(task);
}

Para escenarios avanzados de Cloudflare, incluyendo páginas de desafío y fingerprinting de navegador, consulta la guía sobre automatizar la resolución de CAPTCHA en navegadores headless.

Uniendo Todo

Aquí tienes un index.js completo que muestra cómo usar el cliente en un escenario de automatización real:

// index.js
const CapSolverClient = require('./capsolver-client');
require('dotenv').config();

async function main() {
  const client = new CapSolverClient(process.env.CAPSOLVER_API_KEY);

  try {
    // Verificar el saldo antes de comenzar
    const { balance, currency } = await client.getBalance();
    console.log(`Saldo de cuenta: ${balance} ${currency}`);

    if (balance < 0.01) {
      throw new Error('Saldo insuficiente. Por favor, recarga tu cuenta de CapSolver.');
    }

    // Ejemplo: Resolver reCAPTCHA v2
    const solution = await client.solveReCaptchaV2(
      'https://example.com/login',
      '6Le-wvkAAAAAATBQbZDLjMjqTLV92vP6EXjs'
    );

    console.log('CAPTCHA resuelto con éxito');
    console.log('Token:', solution.gRecaptchaResponse);

    // Inyectar el token en tu flujo de automatización
    // await page.evaluate(token => {
    //   document.getElementById('g-recaptcha-response').value = token;
    // }, solution.gRecaptchaResponse);

  } catch (error) {
    console.error('Error:', error.message);
    process.exit(1);
  }
}

main();

Manejo de Errores y Reintentos

Las integraciones de producción requieren un manejo robusto de errores. Los problemas de red, caídas temporales de la API y fallas en CAPTCHA pueden ocurrir, por lo que implementar lógica de reintentos mejora significativamente la confiabilidad:

async function withRetry(operation, maxAttempts = 3, delayMs = 2000) {
  let lastError;

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await operation();
    } catch (error) {
      lastError = error;
      console.warn(`Intento ${attempt}/${maxAttempts} fallido: ${error.message}`);

      if (attempt < maxAttempts) {
        await new Promise(resolve => setTimeout(resolve, delayMs * attempt));
      }
    }
  }

  throw lastError;
}

// Uso
const solution = await withRetry(() =>
  client.solveReCaptchaV2('https://example.com', 'clave-del-sitio')
);

La retroalimentación exponencial (delayMs * attempt) evita golpear la API durante fallas transitorias y da tiempo al servicio para recuperarse.

Mejores Prácticas para la Integración en JavaScript

Protege tu clave de API. Siempre carga las credenciales desde variables de entorno, nunca las codifiques directamente. Usa archivos .env localmente y un manejo adecuado de secretos en pipelines de CI/CD.

Establece tiempos de espera para las tareas. Agrega una duración máxima de sondeo para evitar que tu automatización se quede colgada si una tarea se estanca. Un tiempo de espera de 120 segundos cubre la mayoría de los escenarios de resolución.

Monitorea tu saldo de forma programática. Para trabajos de automatización prolongados, verifica tu saldo al iniciar y opcionalmente en intervalos regulares. Esto previene fallas silenciosas durante la ejecución.

Asegúrate de que el tipo de tarea coincida con el desafío. Usar el tipo de tarea incorrecto es una causa común de fallas. Siempre inspecciona el HTML de la página objetivo para confirmar el tipo de CAPTCHA y extrae la clave del sitio correcta antes de enviar una tarea.

Respetar los límites de tasa. Evita enviar tareas más rápido de lo que tu flujo puede consumir resultados. Encolar tareas y procesarlas a un ritmo controlado da como resultado un flujo más estable.

Para una visión más amplia sobre integrar la resolución de CAPTCHA en pipelines de scraping, consulta cómo integrar CapSolver en tu flujo de automatización o scraping, que cubre patrones adicionales incluyendo Puppeteer y Playwright. Si tu proyecto involucra navegadores headless específicamente, automatizar la resolución de CAPTCHA en navegadores headless muestra el proceso completo de configuración.

Preguntas Frecuentes

P: ¿Necesito un proxy para usar la API de CapSolver?
R: No. Para la mayoría de los tipos de tarea, CapSolver maneja la resolución en su propia infraestructura y solo necesitas pasar la URL objetivo y la clave del sitio. La configuración de proxy es opcional y solo es requerida para ciertos tipos de tarea que necesitan simular una sesión del navegador desde una IP específica. Consulta la guía de uso de proxy para más detalles.

P: ¿Cuánto tiempo tarda en resolver un CAPTCHA?
R: Los tiempos de resolución varían según el tipo de desafío. reCAPTCHA v3 normalmente se resuelve en menos de 5 segundos. reCAPTCHA v2 y Cloudflare Turnstile pueden tardar entre 10 y 30 segundos dependiendo de la dificultad del desafío y la carga de la cola actual. El bucle de sondeo en esta guía maneja los tiempos de resolución variables automáticamente.

P: ¿Qué pasa si se agota mi saldo durante la ejecución?
R: La API devolverá un código de error en la siguiente llamada a /createTask. El cliente de esta guía lanzará un error en ese caso, el cual puedes capturar y manejar—por ejemplo, enviando una alerta o pausando el trabajo. Verificar el saldo al iniciar (como se muestra en la guía) es la forma más sencilla de prevenir esto.

P: ¿Puedo usar este cliente en un navegador (JavaScript del frontend)?
R: No. Tu clave de API debe permanecer del lado del servidor. Exponerla en código del frontend permitiría a cualquiera usar tus créditos. Siempre llama a la API de CapSolver desde un backend de Node.js, una función sin servidor o un entorno del lado del servidor.

P: ¿Qué debo hacer si una tarea devuelve failed?
A: Un estado de failed generalmente significa que los parámetros del desafío eran incorrectos (clave de sitio incorrecta, tipo de tarea no coincidente o una configuración de página no compatible). Verifique el campo errorDescription en la respuesta, valide sus parámetros de tarea según la documentación del tipo de tarea y vuelva a intentarlo con valores corregidos. También puede consultar la FAQ de CapSolver para patrones comunes de errores.

P: ¿Existe un SDK oficial para JavaScript/Node.js?
A: CapSolver proporciona SDK oficiales para múltiples lenguajes. Para proyectos de JavaScript, puede usar los patrones en esta guía directamente, o consultar el GitHub de CapSolver en busca de paquetes npm publicados y ejemplos de código.

Pasos siguientes

Con esta implementación, tiene una base sólida para agregar capacidades de resolución de CAPTCHA a sus proyectos de automatización de JavaScript. Puede extender este cliente con tipos de tarea adicionales, integrarlo con herramientas de automatización de navegadores como Puppeteer o Playwright, o combinarlo con un flujo de trabajo de scraping con IA para crear pipelines más avanzados de extracción de datos.

Para otros tipos de desafíos y sus parámetros específicos, consulte la documentación oficial del tipo de tarea.

Comience a resolver CAPTCHAs en sus proyectos de JavaScript hoy mismo con CapSolver—cree su cuenta, obtenga su clave de API y coloque el código del cliente anterior en su próximo proyecto de automatización.