Solucionador de CAPTCHA de CloakBrowser: Cómo integrar CapSolver con Automatización de Navegador Playwright

TL;DR

• CloakBrowser inicia una compilación de Chromium a través de una API de Python compatible con Playwright; CapSolver maneja la tarea de CAPTCHA y devuelve un token o resultado de reconocimiento de imágenes.
• CloakBrowser no es un servicio de resolución de CAPTCHA. La integración mantiene el estado del navegador en CloakBrowser, envía solo los parámetros necesarios del desafío a CapSolver y presenta el resultado a través de la misma página de Playwright.
• Para un script existente de Playwright, el cambio principal en el lado del navegador es reemplazar el lanzador estándar de Chromium con from cloakbrowser import launch.
• Mantén la URL de la página, la clave del sitio, el proxy, las cookies, el idioma, y el agente de usuario consistentes cuando un desafío esté vinculado a la sesión actual.
• Un token devuelto es un resultado intermedio. Trata el flujo de trabajo como exitoso solo después de que la página objetivo o la aplicación autorizada lo acepte.

Lo que hace CloakBrowser y CapSolver

CloakBrowser es un paquete de navegador basado en Chromium para automatización con Playwright y Puppeteer. Su repositorio oficial describe cambios a nivel de código en señales del navegador como canvas, WebGL, audio, fuentes, GPU, pantalla, WebRTC y comportamiento relacionado con la automatización. El lanzador de Python devuelve un Browser estándar de Playwright, por lo que métodos conocidos como new_page(), localizadores, evaluate(), clics y operaciones de formularios permanecen disponibles.

CloakBrowser no resuelve CAPTCHAS. CapSolver proporciona ese servicio separado: su aplicación crea una tarea con los parámetros del desafío, recibe una solución y utiliza la página actual para enviarla. Esta separación es importante porque la gestión del entorno del navegador y el manejo de CAPTCHA tienen entradas y modos de falla diferentes.

Las responsabilidades son las siguientes:

CloakBrowser
  -> inicia Chromium y mantiene cookies, proxy, página y contexto del navegador
  -> lee los parámetros del desafío mostrados a la sesión actual

CapSolver
  -> recibe el tipo de tarea soportado y los parámetros del desafío requeridos
  -> devuelve un token o resultado de reconocimiento de imágenes

API de Playwright
  -> coloca el resultado en la misma página
  -> invoca el callback esperado o envía el formulario
  -> verifica la respuesta de la página final o la aplicación

Si necesita un repaso de Playwright antes de integrar los dos servicios, consulte el glosario de Playwright de CapSolver y la guía de automatización de navegadores con Playwright.

Requisitos previos

Use este flujo solo en sitios web y aplicaciones que posea o esté autorizado a probar o automatizar. Necesitará:

• Python 3.9 o posterior;
• una instalación y licencia de CloakBrowser o configuración de evaluación soportada;
• una cuenta de CapSolver y clave de API;
• la URL objetivo y los parámetros del desafío desde la página que está autorizado a automatizar.

Instale los paquetes de Python:

pip install cloakbrowser capsolver

Para la licencia de CloakBrowser, el repositorio actual documenta cloakbrowser login para una configuración interactiva y la variable de entorno CLOAKBROWSER_LICENSE_KEY para CI o servidores. Mantenga ambas credenciales de proveedores fuera del control de código fuente. Las variables de entorno o un gestor de secretos son más seguras que comprometer claves literales.

Paso 1: Iniciar CloakBrowser con la API de Playwright

El siguiente ejemplo mínimo abre una página, lee su título y cierra el navegador:

from cloakbrowser import launch

browser = launch(
    headless=False,
    humanize=True,
    license_key="cb_...",
)

page = browser.new_page()
page.goto("https://example.com", wait_until="domcontentloaded")
print(page.title())
browser.close()

Las opciones del lanzador controlan el entorno del navegador:

Para desafíos vinculados a la sesión, evite cambiar el proxy, el agente de usuario, las cookies o el contexto del navegador entre leer el desafío y enviar su solución. La FAQ de CapSolver sobre fingerprinting de navegador en seguridad web explica por qué múltiples señales de navegador pueden evaluarse juntas.

Paso 2: Crear una tarea reCAPTCHA v2 de CapSolver

El flujo básico de SDK de Python establece la clave de API y envía un objeto de tarea soportado. Este ejemplo usa valores públicos de Google para reCAPTCHA v2:

import capsolver

capsolver.api_key = "CAP-..."

solution = capsolver.solve(
    {
        "type": "ReCaptchaV2TaskProxyLess",
        "websiteURL": "https://www.google.com/recaptcha/api2/demo",
        "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    }
)

token = solution.get("gRecaptchaResponse")
if not isinstance(token, str) or not token:
    raise RuntimeError(f"CapSolver no devolvió un token de reCAPTCHA: {solution}")

print("Token recibido")

Los campos importantes son:

Consulte la documentación de reCAPTCHA v2 de CapSolver antes de la implementación en producción y use los valores de la página activa en lugar de copiar parámetros de demostración. La guía detallada sobre resolución de reCAPTCHA v2 cubre selección de tareas y campos de respuesta en más detalle.

Redime tu código de bonificación de CapSolver

Aumenta tu presupuesto de automatización instantáneamente!
Usa el código de bonificación CAP26 al recargar tu cuenta de CapSolver para obtener un 5% adicional en cada recarga — sin límites.
Redímelo ahora en tu Panel de CapSolver

Paso 3: Devolver el token a través de la misma página de CloakBrowser

El ejemplo completo a continuación mantiene la navegación y la presentación del token dentro de una sola página de CloakBrowser. El selector CSS y el comportamiento de presentación son específicos de la demostración pública; una aplicación real puede usar un callback, un campo gestionado por un framework, o otro flujo de formulario.

import re

import capsolver
from cloakbrowser import launch


def inject_recaptcha_token(page, token):
    if not isinstance(token, str) or not token:
        raise ValueError("Se requiere un token de reCAPTCHA no vacío")

    page.evaluate(
        """
        (token) => {
            const textarea = document.getElementById('g-recaptcha-response');
            if (!textarea) {
                throw new Error('g-recaptcha-response no se encontró');
            }
            textarea.value = token;
        }
        """,
        token,
    )

    with page.expect_navigation(
        wait_until="domcontentloaded",
        timeout=30_000,
    ):
        page.click("#recaptcha-demo-submit")

    return page.content()


def main():
    capsolver.api_key = "CAP-..."  # TU_CLAVE_DE_API_DE_CAPSOLVER

    browser = launch(
        license_key="cb_...",  # TU_CLAVE_DE_LICENCIA_DE_CLOAKBROWSER
        headless=False,
        locale="en-US",
    )

    try:
        page = browser.new_page()
        page.goto(
            "https://www.google.com/recaptcha/api2/demo",
            wait_until="domcontentloaded",
            timeout=60_000,
        )

        solution = capsolver.solve(
            {
                "type": "ReCaptchaV2TaskProxyLess",
                "websiteURL": page.url,
                "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
            }
        )

        token = solution.get("gRecaptchaResponse")
        result_page = inject_recaptcha_token(page, token)

        match = re.search(
            r'<div class="recaptcha-success">(.*?)</div>',
            result_page,
        )
        print(match.group(1) if match else "Verificación fallida")
    finally:
        browser.close()


if __name__ == "__main__":
    main()

Ejecútalo como un script de Python normal:

python cloakbrowser-capsolver.py

En producción, carga las claves desde variables de entorno, agrega reintentos limitados alrededor de fallas transitorias de API o navegación, registra los IDs de tarea de CapSolver sin registrar secretos y valida el resultado final del negocio. CapSolver también proporciona una FAQ enfocada en integrar la resolución de CAPTCHA con Playwright o Puppeteer.

Paso 4: Manejar CAPTCHAS de imagen con ImageToTextTask

Algunos flujos de prueba autorizados exponen una CAPTCHA como imagen en lugar de un widget basado en token. En ese caso, capture o extraiga la imagen, conviértala a Base64 sin el prefijo de URL de datos, y envíela a ImageToTextTask.

La captura de pantalla a continuación del flujo original muestra el elemento de imagen y el campo de entrada en la demostración de características de BotDetect:

import capsolver
from cloakbrowser import launch


TARGET_URL = "https://captcha.com/demos/features/captcha-demo.aspx"

browser = launch(headless=False, humanize=True)

try:
    page = browser.new_page()
    page.goto(TARGET_URL, wait_until="domcontentloaded")

    image_src = page.locator("#demoCaptcha_CaptchaImage").get_attribute("src")
    if not image_src or "," not in image_src:
        raise RuntimeError("La imagen de CAPTCHA no es un URL de datos")

    base64_image = image_src.split(",", 1)[1].replace("\n", "")

    solution = capsolver.solve(
        {
            "type": "ImageToTextTask",
            "websiteURL": page.url,
            "module": "common",
            "body": base64_image,
        }
    )

    text = solution.get("text")
    if not isinstance(text, str) or not text:
        raise RuntimeError(f"CapSolver no devolvió texto de OCR: {solution}")

    page.locator("#captchaCode").fill(text)
    page.locator("#validateCaptchaButton").click()
finally:
    browser.close()

Los selectores están intencionalmente vinculados a la página de demostración. Inspeccione la página objetivo autorizada y use sus selectores de imagen, entrada y envío reales.

Varias imágenes y el módulo de número

ImageToTextTask puede usar diferentes módulos para formatos de imagen soportados. El artículo original incluyó esta vista general del módulo, que se preserva aquí para referencia:

Cuando un módulo soportado acepta varias imágenes, envíe la matriz documentada para ese módulo y lea las respuestas correspondientes:

solution = capsolver.solve(
    {
        "type": "ImageToTextTask",
        "module": "number",
        "images": [base64_image],
    }
)

answers = solution["answers"]

Los nombres de módulo, campos de solicitud y formatos soportados pueden cambiar, por lo que verifíquelos contra la documentación de ImageToTextTask actual. Para un patrón de API de Python más amplio, consulte cómo integrar una API de resolución de CAPTCHA en Python.

¿Qué cambia para reCAPTCHA v3?

La arquitectura del navegador permanece igual, pero la tarea de CapSolver y los parámetros de página deben coincidir con una implementación v3. En particular:

1. Use el tipo de tarea reCAPTCHA v3 documentado por CapSolver.
2. Proporcione el valor de acción esperado por la página cuando la integración use uno.
3. Lea la URL y la clave del sitio desde la página activa en lugar de desde un ejemplo no relacionado.
4. Mantenga el token resultante en la misma sesión del navegador y envíelo antes de que expire.
5. Verifique la respuesta de la aplicación. Un puntaje o token devuelto por una API no garantiza que la aplicación objetivo haya aceptado la solicitud.

No abra una página nueva sin las cookies y estado de sesión originales solo para enviar el token. Esto rompe el contexto que la aplicación objetivo podría usar al evaluar el resultado.

Solución de problemas de CloakBrowser y CapSolver

El script inicia Chromium estándar de Playwright

Este código inicia Chromium de Playwright, no CloakBrowser:

from playwright.sync_api import sync_playwright

pw = sync_playwright().start()
browser = pw.chromium.launch()

Use en su lugar el lanzador de CloakBrowser:

from cloakbrowser import launch

browser = launch()

Según el repositorio de CloakBrowser, playwright install-deps chromium puede ser útil en Linux cuando faltan bibliotecas del sistema. Ejecutar playwright install chromium es diferente: descarga el navegador de Playwright y no arregla la ruta de inicio de CloakBrowser.

CapSolver devuelve un token, pero la página lo rechaza

Verifique cada frontera en orden:

• websiteURL es la URL completa usada por la página activa;
• websiteKey pertenece a esa página;
• el tipo de tarea seleccionado y la acción opcional coinciden con el desafío;
• el token se escribe en el campo esperado o se pasa al callback de la página;
• la página no se ha recargado o reemplazado el desafío;
• las cookies, proxy, agente de usuario y contexto del navegador permanecen consistentes;
• la respuesta de la página final o la aplicación confirma la aceptación.

La tarea de imagen no devuelve texto

Confirme que el cuerpo de la imagen es Base64 válido, que se ha eliminado el prefijo de URL de datos, que el módulo elegido soporta la imagen y que el campo de respuesta coincide con la documentación actual. Capture el código de error y el ID de tarea de CapSolver para depurar, pero no registre claves de API ni datos de página sensibles.

La navegación se queda en espera después de la presentación

No cada presentación causa una navegación completa. Algunos sitios actualizan el DOM o realizan una solicitud XHR en su lugar. Reemplace expect_navigation() por la condición que realmente representa el éxito: un localizador que se vuelve visible, un cambio de URL, un evento de respuesta o un elemento de estado específico de la aplicación. La referencia oficial de API de Browser de Playwright es la mejor fuente para el comportamiento actual de la API.

Automatización responsable y confiable

Los sistemas de CAPTCHA son mecanismos de control de acceso y prevención de abuso. Utilice CapSolver y CloakBrowser solo para automatización legal en sistemas que posea o tenga permiso explícito para probar. Respete los términos del sitio, los límites de tasa, los requisitos de privacidad y las leyes aplicables. No utilice automatización para acceder a datos privados, crear tráfico abusivo o interferir con otros usuarios.

Para pruebas de calidad (QA) y monitoreo, prefiera entornos de prueba dedicados y claves de prueba del proveedor cuando estén disponibles. Registre la URL de la página, el tipo de tarea, el ID de tarea, el tiempo transcurrido y el estado final de la aplicación para que los fallos puedan rastrearse sin almacenar credenciales o datos personales. La guía de automatización de CAPTCHA para pruebas de calidad proporciona patrones adicionales para flujos de trabajo de prueba controlados.

Construye flujos de trabajo de automatización confiables con CapSolver

CloakBrowser puede suministrar un entorno de navegador compatible con Playwright, mientras que CapSolver maneja las tareas de CAPTCHA compatibles. Mantener estos responsabilidades separadas hace que el flujo de trabajo sea más fácil de probar: lea el desafío desde la página activa, solicite la solución correspondiente, envíela en el mismo contexto y verifique el resultado de la aplicación.

Try CapSolver para un flujo de trabajo autorizado de CloakBrowser o Playwright, y consulte la documentación actual antes de mover el código de demostración a producción.

Preguntas frecuentes

P: ¿Es CloakBrowser un solucionador de CAPTCHA?

No. CloakBrowser proporciona un navegador Chromium y una interfaz de automatización compatible con Playwright. Un servicio separado como CapSolver maneja las tareas de CAPTCHA compatibles.

P: ¿Puede usar un script existente de Playwright con CloakBrowser?

Normalmente, sí. Reemplace la ruta de inicio del navegador con from cloakbrowser import launch, luego siga utilizando el Browser de Playwright devuelto, páginas, localizadores y métodos de evaluación. Pruebe las opciones y dependencias específicas del navegador en su entorno.

P: ¿Por qué debe enviar el resultado de CAPTCHA en el mismo contexto del navegador?

La aplicación de destino puede asociar un desafío con cookies, dirección de proxy, señales del navegador, URL u otros datos de sesión. Cambiar de contexto puede hacer que los parámetros de desafío válidos anteriormente sean inconsistentes.

P: ¿Dónde encuentro la clave del sitio reCAPTCHA?

Use la clave configurada en la página que está autorizado a automatizar. Puede aparecer en el marcado del widget o en los scripts de la página. No copie una clave de un tutorial o dominio no relacionado.

P: ¿Garantiza un token de CapSolver el éxito?

No. Un token es un resultado intermedio. La condición de éxito final es la respuesta de la página o aplicación objetivo después de que el token se envíe correctamente y a tiempo.

P: ¿Puede manejar la integración CAPTCHAS de imagen?

El ImageToTextTask de CapSolver admite módulos de reconocimiento de imágenes documentados. Extraiga la imagen de la página autorizada, envíe la carga útil de Base64 requerida y ingrese el texto devuelto a través de la misma página de CloakBrowser.

P: ¿Deben aparecer las claves de API y licencia en el script?

No. Los ejemplos usan marcadores de posición reconocibles. El código de producción debe leer secretos desde variables de entorno o un administrador de secretos y nunca debe comprometerlos en el control de versiones.

P: ¿Cómo debo probar esta integración de forma segura?

Comience con demostraciones del proveedor o una aplicación que controle. Use tasas de solicitud limitadas, registre los IDs de tarea y los resultados finales, y mueva a un sitio de producción solo cuando tenga autorización y una necesidad operativa clara.