Cómo conectar los rastreadores de Lightpanda a una API de resolución de CAPTCHA

Resumen

• Lightpanda proporciona el navegador sin cabeza; una API de CAPTCHA independiente proporciona el resultado para un desafío compatible dentro de un flujo autorizado.
• Conecta Puppeteer al endpoint CDP de Lightpanda y comprueba la página real antes de construir una solicitud para el solver.
• Para reCAPTCHA v2, usa la URL de la página actual, la clave pública del sitio y cualquier parámetro adicional documentado que requiera ese desafío.
• Mantén la página original abierta mientras se ejecuta el solver. El token de respuesta debe llegar a la ruta correcta de callback o envío de la aplicación.
• Una prueba de conexión del navegador no demuestra compatibilidad con el script de CAPTCHA ni aceptación final del sitio web. Valida esos puntos por separado en tu página de pruebas permitida.

Lightpanda es un navegador sin cabeza creado para automatización, rastreo, pruebas y agentes de navegador. Los desarrolladores lo controlan mediante interfaces como el Protocolo de Herramientas de Chrome (CDP), normalmente usando Puppeteer. Puede ejecutar JavaScript de la página e inspeccionar el DOM, lo que lo hace útil cuando una respuesta HTTP por sí sola no contiene la información que un flujo de trabajo necesita.

Un CAPTCHA es un paso separado. Cargar una página mediante Lightpanda no significa que se haya completado su desafío de verificación. CapSolver puede proporcionar la API de resolución documentada para un CAPTCHA compatible, mientras que tu aplicación sigue siendo responsable del estado de la página y del resultado final.

Esta guía conecta esas responsabilidades sin suponer que todas las páginas de CAPTCHA se comportan como Chromium. El ejemplo ejecutable verifica la conexión del navegador. La solicitud al solver y la aceptación por parte de la aplicación requieren tus propias credenciales y un desafío autorizado.

Entiende las dos conexiones

Una integración de CAPTCHA con Lightpanda necesita una conexión al navegador y otra desde el backend de la aplicación hacia la API del solver.

El repositorio de Lightpanda muestra a Puppeteer conectándose a un endpoint CDP. La navegación del navegador, la inspección de páginas y los callbacks de la aplicación permanecen en ese lado del flujo de trabajo. La API de tareas de CapSolver recibe los datos específicos de la tarea y devuelve la respuesta de la tarea.

No apuntes una solicitud a la API del solver al puerto CDP. Tampoco envíes una URL de WebSocket de navegador como websiteURL. Una dirección controla un proceso de navegador; la otra identifica la página web que carga el CAPTCHA.

Un contrato de API también establece el límite de lo que conoce la integración. Un resultado del solver no es un comando que reanude automáticamente todos los navegadores. La aplicación debe usar los campos devueltos de la forma que espera su propia página.

Instala e inicia el navegador

Instala Lightpanda y Puppeteer en una carpeta de proyecto aislada antes de añadir solicitudes de resolución de pago.

El ejemplo de conexión usa Lightpanda 1.0.2, Puppeteer Core 25.16.0 y Node.js 24. Instala la dependencia de Node con npm install --save-exact puppeteer-core@25.16.0. Descarga el binario para tu sistema operativo y procesador desde la versión oficial 1.0.2, hazlo ejecutable y confirma la versión con ./lightpanda version.

Inicia el servidor CDP local con ./lightpanda serve --host 127.0.0.1 --port 9227. Mantén esa terminal en ejecución mientras el cliente se conecta. El puerto del ejemplo siguiente debe coincidir con el puerto del servidor. Usa un enlace local para esta configuración de desarrollo.

Prepara una página de prueba permitida antes de continuar. La comprobación inicial de conexión puede usar una página sencilla que te pertenezca; una prueba posterior de CAPTCHA necesita una página con el desafío real y una forma, del lado de la aplicación, de observar la aceptación. También prepara una clave de API válida de CapSolver y saldo antes de crear una tarea de resolución de pago.

En esta guía no se demuestra ninguna resolución de pago. Los pasos de verificación del navegador y una respuesta de autenticación de la API establecen sus respectivas superficies de conexión; no establecen la resolución correcta del CAPTCHA ni la compatibilidad con un sitio web externo concreto.

Verifica la conexión de Puppeteer con Lightpanda

Establece AUTHORIZED_TEST_URL en tu página de prueba, guarda lo siguiente como lightpanda-connect.mjs y ejecuta node lightpanda-connect.mjs.

El ejemplo adapta el patrón oficial de conexión de Puppeteer de Lightpanda. Crea un contexto de navegador, carga la página permitida, lee su título y URL final, y limpia el contexto y la conexión del cliente.

import puppeteer from 'puppeteer-core';

const target = process.env.AUTHORIZED_TEST_URL;
if (!target) throw new Error('Set AUTHORIZED_TEST_URL to your permitted test page');
const browser = await puppeteer.connect({
  browserWSEndpoint: 'ws://127.0.0.1:9227',
});
try {
  const context = await browser.createBrowserContext();
  try {
    const page = await context.newPage();
    await page.goto(target, { waitUntil: 'domcontentloaded' });
    console.log({ title: await page.title(), url: page.url() });
  } finally {
    await context.close();
  }
} finally {
  await browser.disconnect();
}

La salida debe identificar la página que realmente se cargó. Si informa de una página de error, una redirección o un documento no relacionado, corrige eso antes de construir una solicitud de CAPTCHA. La evaluación correcta de JavaScript en una página de prueba simple es un buen punto de partida, pero no demuestra que todas las APIs de navegador de un widget real estén soportadas.

La referencia de connect de Puppeteer describe la conexión a un navegador existente. Por eso el ejemplo usa connect en lugar de lanzar un proceso de Chromium separado: el proceso bajo prueba debe seguir siendo Lightpanda.

Prepara una tarea de CAPTCHA documentada

Construye la tarea del solver a partir del desafío real cargado por el navegador, manteniendo sus parámetros asociados a esa página.

Para reCAPTCHA v2 estándar, comienza con la referencia oficial de tareas v2. Una solicitud sin proxy usa ReCaptchaV2TaskProxyLess, websiteURL y websiteKey. Otros parámetros observados pertenecen a sus campos documentados; no los infieras solo a partir de la casilla visible.

El siguiente JSON ilustra la forma de esa solicitud. Contiene valores de relleno y no es un desafío activo ni una solicitud pagada ejecutada. Sustituye los valores con los de tu propia página permitida y usa el ejemplo oficial de API o SDK enlazado arriba para enviarla.

{
  "clientKey": "YOUR_API_KEY",
  "task": {
    "type": "ReCaptchaV2TaskProxyLess",
    "websiteURL": "https://example.com/authorized-form",
    "websiteKey": "PUBLIC_SITE_KEY_FROM_THIS_PAGE"
  }
}

Mantén clientKey en el proceso de backend. No es una clave de sitio del lado del navegador y no debe insertarse en la página. websiteURL debe describir la página web que carga el CAPTCHA, en lugar de la URL del iframe del CAPTCHA o el endpoint de control de Lightpanda.

Si no conoces la versión o los parámetros adicionales, usa el flujo de trabajo documentado de detección de parámetros de CAPTCHA mientras inspeccionas la página permitida. Eso es un paso de preparación; no significa que se pueda cargar una extensión de Chrome en Lightpanda.

Canjea tu código de bono de CapSolver

¡Impulsa tu presupuesto de automatización al instante!
Usa el código de bono CAP26 cuando recargues tu cuenta de CapSolver para obtener un 5% de bono extra en cada recarga, sin límites.
Canjéalo ahora en tu Panel de CapSolver

Recupera el resultado del solver sin reemplazar la página

Mantén la página de Lightpanda y su estado de aplicación vivos mientras se completa la API de tareas.

Para una respuesta asíncrona, conserva el ID de tarea devuelto por createTask y usa getTaskResult para esa tarea. Revisa los errores de la API y el estado de procesamiento antes de leer la solución. El campo documentado del token de respuesta de v2 es gRecaptchaResponse.

No crees un contexto de navegador nuevo solo porque se haya completado la solicitud al solver. Un contexto nuevo es un entorno de página distinto, y tu aplicación puede tener estado asociado a la operación original. Del mismo modo, no reutilices un resultado para otra página pendiente solo porque esa página muestre el mismo tipo de widget.

El script de solo conexión anterior cierra el contexto deliberadamente. Al integrar la ejecución del solver en una aplicación real, coloca la operación del solver y la continuación específica de la página dentro de la vida útil del contexto, antes de que se ejecute esa limpieza. Conserva la limpieza tanto en caso de error como de éxito.

Usa la transferencia de token propiedad de la aplicación

Aplica el resultado mediante la ruta de callback o de envío definida por tu propia aplicación. No existe un nombre de callback universal que funcione en todas las páginas. No pegues una función adivinada en una integración y supongas que el formulario ha aceptado el valor.

Un adaptador mínimo del lado del navegador puede probarse primero en un fixture propio con una cadena inerte: verifica que el callback previsto recibe esa cadena y que el campo relevante cambia. Eso solo valida el adaptador. No debe enviar la cadena inerte como si fuera una respuesta válida de CAPTCHA.

La guía de verificación de respuestas de reCAPTCHA de Google explica el paso de verificación separado, del lado de la aplicación. Después de devolver un resultado genuino del solver, comprueba el resultado de la aplicación para el mismo intento. Un campo rellenado o un callback completado no son por sí solos pruebas suficientes.

Diagnostica los fallos según el componente que falló

Separa la carga del navegador, la ejecución del solver y la aceptación de la aplicación para que los reintentos aborden el problema real.

Puppeteer no puede conectarse

Confirma que el proceso de Lightpanda sigue en ejecución y que el host y el puerto coinciden. Revisa las versiones fijadas del cliente y el navegador antes de suponer que un script de Chromium que funcionaba es compatible con la build actual de Lightpanda.

La página carga pero el widget de CAPTCHA no

Inspecciona los errores de script de la página y las solicitudes de red del widget. Una API de solver no puede reparar una característica del motor del navegador que la página requiera. Demuestra que la página autorizada carga el desafío esperado antes de continuar con una tarea de pago.

La API de tareas rechaza la solicitud

Lee la respuesta de error documentada y revisa la clave, el tipo de tarea, la URL, la clave del sitio y los campos condicionales. Un error de autenticación prueba que la API respondió; no prueba una integración de solver correcta. No envíes repetidamente la misma entrada no válida.

El solver devuelve un token pero la aplicación lo rechaza

Comprueba la propiedad de la página, la transferencia del token, el comportamiento del callback y la verificación del lado del servidor. Registra el ID de tarea y el motivo de fallo redactado. Evita registrar claves de API o tokens de respuesta sin procesar en salidas de compilación compartidas.

El flujo de trabajo solo funciona en el fixture

Trata el fixture como una prueba del adaptador. Ejecuta el flujo real de CAPTCHA permitido antes de confiar en la integración. El comportamiento del navegador, los scripts del widget y la validación de la aplicación son condiciones adicionales, y ninguna se deriva automáticamente de un handshake CDP correcto.

Decide si esta integración encaja en tu crawler

Lightpanda más una API externa de solver es relevante cuando un crawler ya usa Lightpanda, se encuentra con un CAPTCHA compatible durante una tarea autorizada y tiene una forma verificada de continuar con la misma página. No es un motivo para añadir un solver a páginas sin CAPTCHA ni para afirmar compatibilidad universal con navegadores.

Empieza con la conexión real del navegador, verifica el esquema de tarea y prueba un flujo de aplicación permitido antes de añadir concurrencia. Mantén cada resultado asociado a su página solicitante y mide el resultado real de la aplicación.

Crea flujos de automatización fiables con CapSolver

Usa el solver en un punto de control de CAPTCHA verificado y luego confirma el resultado de la aplicación. CapSolver proporciona la interfaz de resolución documentada para ese paso. Prueba CapSolver con un flujo de trabajo de prueba permitido antes de ampliar la integración.

Preguntas frecuentes

P: ¿Esto instala un solver de CAPTCHA dentro de Lightpanda?

No. La aplicación se comunica con Lightpanda mediante CDP y llama a la API externa del solver por separado. Luego debe aplicar el resultado mediante el flujo esperado de la aplicación autorizada.

P: ¿Puedo cargar la extensión de Chrome de CapSolver en este navegador?

Este tutorial no establece compatibilidad con extensiones de Chrome en Lightpanda. Usa la API externa de tareas. La inspección de parámetros en un entorno de Chrome compatible es un paso de preparación separado.

P: ¿La conexión de Puppeteer demuestra que reCAPTCHA funciona en Lightpanda?

No. Demuestra que el cliente puede conectarse y ejecutar las operaciones de navegador mostradas. Los scripts reales de CAPTCHA y la aceptación por parte de la aplicación necesitan sus propias pruebas.

P: ¿Qué tipo de reCAPTCHA usa el ejemplo de JSON?

Ilustra reCAPTCHA v2 estándar con ReCaptchaV2TaskProxyLess. Enterprise, v3 y otras familias de desafíos necesitan sus propios tipos de tarea e inputs documentados.

P: ¿El código de ejemplo ha completado una resolución de CAPTCHA de pago?

No. El ejemplo ejecutable comprueba la conexión del navegador, mientras que el JSON explica la forma de la tarea con valores de relleno. Se requiere una cuenta de solver válida y un desafío activo autorizado para probar la resolución y la aceptación final.