Cómo agregar la resolución de CAPTCHA de Gumloop a flujos de trabajo web

TL;DR

• La resolución de CAPTCHA de Gumloop no es un conector nativo verificado; utilice los nodos HTTP y de enrutamiento documentados de Gumloop con un servicio de recuperación de navegador propiedad de la organización.
• Mantenga la detección de desafíos y la aplicación de tokens dentro de la misma sesión de navegador autorizada en lugar de pedirle a un nodo de flujo que reconstruya el estado de la página.
• Enrute estados exactos como NO_CHALLENGE, RECOVERED, REVIEW y STOP con reglas deterministas, no con decisiones de un modelo sin fin.
• Limitar el servicio de recuperación a adaptadores reCAPTCHA v2/v3 y Cloudflare Turnstile documentados, un intento de flujo por defecto y verificación de aplicación explícita.
• Envíe tipos no compatibles, sesiones perdidas, desafíos repetidos y autorización poco clara a una cola humana sin continuar con la acción web.

Introducción

La resolución de CAPTCHA de Gumloop funciona mejor como una rama de recuperación controlada alrededor de una tarea de navegador autorizada, no como una integración nativa asumida. Gumloop puede orquestar entradas, llamadas HTTP, rutas y caminos de error, mientras que un trabajador de navegador externo preserva la sesión de la página y aplica un resultado verificado. CapSolver puede proporcionar la capa de CAPTCHA documentada dentro de ese trabajador. Esta separación es importante porque un resultado de API en sí mismo no demuestra que la página original avanzara. El flujo debe verificar el estado del navegador, imponer un presupuesto de reintento y detenerse cuando haya incertidumbre sobre la autorización o la continuidad de la sesión. El patrón siguiente es para automatización legal, razonable, responsable y autorizada por el usuario en sistemas y datos que puede acceder.

Comience con la Brecha de Requisitos Previos

No se verificó ningún conector nativo oficial Gumloop-CapSolver durante la investigación de esta guía. Por lo tanto, la resolución de CAPTCHA de Gumloop requiere un requisito previo explícito: su equipo debe operar un servicio HTTPS que posea la sesión del navegador autorizada y exponga un punto final de recuperación estrecho. Esto no es una API privada de Gumloop, un nodo oculto o una afirmación de que Gumloop integra oficialmente a CapSolver.

El límite sigue las capacidades documentadas para Gumloop. Su nodo Llamar API puede enviar solicitudes GET o POST a un punto final HTTPS con encabezados y un cuerpo de solicitud. Su contrato del nodo de entrada puede recibir valores de un usuario, webhook o predeterminado. Esas capacidades son suficientes para llamar a un servicio que controle su organización, pero no crean ni preservan una sesión de navegador por sí mismas.

Qué debe existir antes de construir el flujo

Prepare estos componentes primero:

• un trabajador de navegador autorizado que posea la página, cookies, almacenamiento, agente de usuario y contexto de red;
• un punto final de recuperación HTTPS protegido por autenticación de servicio;
• una clave de API de CapSolver almacenada solo en el gestor de secretos del servicio de recuperación;
• una lista de permitidos de hosts y acciones;
• una respuesta tipada con estados terminales y sin credenciales en bruto;
• un destino de revisión manual para casos no compatibles o ambiguos.

Si falta algún componente, mantenga la resolución de CAPTCHA de Gumloop en estado de diseño o prueba. No sustituya un nodo de Gumloop no verificado ni coloque una clave de API de producción en texto de flujo ordinario.

Use un Contrato de Flujo de Cinco Etapas

Un diseño confiable de resolución de CAPTCHA de Gumloop separa la orquestación de la ejecución del navegador. La superficie de Gumloop debe modelar el camino de decisión; el trabajador de navegador debe poseer la detección de desafíos, llamadas a CapSolver, aplicación de resultados y verificación de página.

Etapa 1: recibir un evento de navegador acotado

El flujo comienza con un webhook o entrada manual que contiene una referencia de ejecución opaca. No envíe cookies, contraseñas, HTML en bruto o volcado de almacenamiento de navegador. Un evento mínimo puede verse así:

{
  "run_id": "run_01JX...",
  "session_ref": "browser_session_7f2a",
  "approved_host": "portal.example",
  "approved_action": "submit_owned_test_form",
  "observed_state": "CHALLENGE_DETECTED",
  "challenge_type": "recaptcha_v2",
  "attempt": 0
}

La entrada es una referencia a una ejecución ya aprobada. La salida de esta etapa es una solicitud de recuperación válida o STOP. El flujo se detiene inmediatamente si el host, la acción o la referencia de sesión faltan o están fuera de política.

Etapa 2: llamar al servicio de recuperación

Configure un nodo Llamar API para enviar una solicitud POST a un punto final propiedad de la organización, como https://automation.example.net/v1/browser/recover. Use una credencial gestionada para el encabezado de autorización del servicio. El cuerpo debe pasar los campos del evento acotado, no la clave de API de CapSolver.

{
  "run_id": "{{run_id}}",
  "session_ref": "{{session_ref}}",
  "approved_host": "{{approved_host}}",
  "approved_action": "{{approved_action}}",
  "challenge_type": "{{challenge_type}}",
  "attempt": "{{attempt}}",
  "max_attempts": 1
}

Este JSON es un contrato HTTP genérico para su servicio. No es una exportación de Gumloop ni una solicitud de API de CapSolver. Antes de la implementación, confirme las interpolaciones de variables y controles de credenciales exactos disponibles en su espacio de trabajo de Gumloop.

Etapa 3: devolver solo el estado operativo

El servicio debe devolver una respuesta pequeña que Gumloop pueda enrutar sin ver un valor de solución en bruto:

{
  "state": "RECOVERED",
  "run_id": "run_01JX...",
  "correlation_id": "recovery_91c8",
  "attempts_used": 1,
  "continuation_verified": true,
  "reason": "expected form step became visible"
}

Las respuestas terminales útiles son NO_CHALLENGE, RECOVERED, REVIEW y STOP. Un fallo temporal del servicio puede devolver RETRYABLE_ERROR, pero Gumloop debe consumir su presupuesto de reintento antes de llamar nuevamente. No trate un estado faltante, un cuerpo no parseable o un HTTP 200 con un valor desconocido como éxito.

Etapa 4: enrutar con condiciones exactas

Use el modo estándar del enrutador de Gumloop para coincidencias exactas de estado. La recuperación de desafíos es un problema de control determinista, por lo que no necesita interpretación de modelo.

Esta tabla define la salida de la resolución de CAPTCHA de Gumloop, no el estado interno de la proveedora. El estado del proveedor debe resolverse dentro del servicio de recuperación antes de que una respuesta terminal llegue al flujo.

Etapa 5: manejar fallas de transporte por separado

Envuelva el nodo Llamar API con la rama de falla del Escudo de Error de Gumloop. Habilitar solo los campos de entrada no secretos necesarios para investigar una llamada fallida. La ruta de error debe crear un registro de revisión o enviar una alerta; no debe reconectar automáticamente a la acción de navegador.

Los errores de transporte, errores del proveedor, rechazo de la aplicación y desafíos no compatibles requieren evidencia diferente. Combinar los cuatro en una sola rama de reintento hace que la resolución de CAPTCHA de Gumloop sea difícil de operar y puede generar tráfico repetido después de un fallo terminal.

Implemente el Servicio de Recuperación con Campos Oficiales de CapSolver

El servicio de recuperación es donde pertenecen los campos oficiales de CapSolver. La solicitud createTask acepta clientKey y un objeto de tarea. La respuesta getTaskResult utiliza errorId, status y solution para tareas asíncronas. La respuesta oficial indica que un resultado de processing puede consultarse nuevamente después de tres segundos.

El siguiente ejemplo en Python implementa solo el adaptador reCAPTCHA v2. Utiliza los campos documentados ReCaptchaV2TaskProxyLess, websiteURL y websiteKey de la definición de tarea reCAPTCHA v2. Las funciones de detección y aplicación específicas del navegador son marcadores de posición propiedad de su trabajador; no son métodos de API de Gumloop o CapSolver.

import os
import time
import requests

CAPSOLVER_KEY = os.environ["CAPSOLVER_API_KEY"]
CREATE_TASK = "https://api.capsolver.com/createTask"
GET_RESULT = "https://api.capsolver.com/getTaskResult"
APPROVED_HOSTS = {"portal.example"}


def solve_recaptcha_v2(website_url: str, website_key: str) -> dict:
    created = requests.post(
        CREATE_TASK,
        json={
            "clientKey": CAPSOLVER_KEY,
            "task": {
                "type": "ReCaptchaV2TaskProxyLess",
                "websiteURL": website_url,
                "websiteKey": website_key,
            },
        },
        timeout=15,
    ).json()

    if created.get("errorId") or not created.get("taskId"):
        return {"state": "REVIEW", "reason": "task creation failed"}

    for _ in range(4):
        time.sleep(3)
        result = requests.post(
            GET_RESULT,
            json={"clientKey": CAPSOLVER_KEY, "taskId": created["taskId"]},
            timeout=15,
        ).json()

        if result.get("errorId"):
            return {"state": "REVIEW", "reason": "provider returned an error"}
        if result.get("status") == "ready":
            return {"state": "SOLUTION_READY", "solution": result["solution"]}
        if result.get("status") != "processing":
            return {"state": "REVIEW", "reason": "unexpected task status"}

    return {"state": "STOP", "reason": "poll budget exhausted"}


def recover_authorized_session(event: dict, browser_store) -> dict:
    if event.get("approved_host") not in APPROVED_HOSTS:
        return {"state": "STOP", "reason": "host outside approved scope"}
    if event.get("attempt", 0) >= event.get("max_attempts", 1):
        return {"state": "STOP", "reason": "attempt budget exhausted"}

    page = browser_store.get(event["session_ref"])
    if page is None:
        return {"state": "REVIEW", "reason": "browser session unavailable"}

    info = detect_supported_challenge(page)  # your verified browser adapter
    if info is None:
        return {"state": "NO_CHALLENGE"}
    if info["type"] != "recaptcha_v2":
        return {"state": "REVIEW", "reason": "adapter not configured"}

    solved = solve_recaptcha_v2(info["website_url"], info["website_key"])
    if solved["state"] != "SOLUTION_READY":
        return solved

    apply_solution_in_same_session(page, solved["solution"])
    if not verify_expected_transition(page, event["approved_action"]):
        return {"state": "REVIEW", "reason": "application did not advance"}

    return {"state": "RECOVERED", "continuation_verified": True}

La entrada de la función es un evento de ejecución aprobado más una referencia de sesión de navegador opaca. Su salida es un estado terminal para Gumloop. Se detiene en un host no aprobado, presupuesto de intentos agotado, sesión de navegador no disponible, adaptador no compatible, error del proveedor, estado de tarea inesperado, agotamiento del presupuesto de encuestas o verificación de aplicación fallida.

No reutilice el objeto de tarea v2 para otros tipos de desafíos. Cree adaptadores separados desde la guía oficial tarea reCAPTCHA v3 y tarea Cloudflare Turnstile. Mantenga separados los campos requeridos de cada adaptador, la solución devuelta, la lógica de aplicación del navegador y la afirmación de validación.

Redeen su código de bono de CapSolver

Aumente su presupuesto de automatización instantáneamente!
Use el código de bono CAP26 al recargar su cuenta de CapSolver para obtener un 5% adicional en cada recarga — sin límites.
Redeenlo ahora en su Panel de CapSolver

Mantenga la continuidad del navegador fuera del lienzo

La continuidad de sesión es el límite decisivo en la resolución de CAPTCHA de Gumloop. Una solución puede ser técnicamente válida y aún fallar al regresar a una página diferente, jar de cookies, agente de usuario, identidad de proxy, ruta o acción protegida.

El flujo de Gumloop debe pasar una session_ref opaca; no debe reconstruir el estado del navegador a partir de campos copiados. El trabajador de recuperación resuelve esa referencia, confirma la URL actual y el desafío, aplica el resultado en el mismo contexto de navegador y verifica una afirmación de aplicación específica. Ejemplos incluyen un paso de formulario que se vuelve visible, una ruta QA propiedad completada o un elemento de página pública esperado que aparece.

La verificación de la aplicación debe ser más fuerte que "la llamada HTTP tuvo éxito". El diagnóstico de recuperación de n8n adyacente ilustra por qué las plataformas de flujo necesitan una verificación posterior a la recuperación. En Gumloop, modele esa verificación como parte de la respuesta del trabajador y requiera continuation_verified=true antes de que se ejecute la rama de éxito.

Establezca un presupuesto de reintento que no se repita

Un flujo de resolución de CAPTCHA de Gumloop bueno tiene dos presupuestos: un presupuesto de encuesta del proveedor dentro del servicio de recuperación y un presupuesto de reintento del flujo en Gumloop. Resuelven problemas diferentes.

El presupuesto de encuesta del proveedor controla cuánto tiempo el servicio espera por una tarea que aún está procesando. El presupuesto de reintento del flujo controla si Gumloop puede llamar al servicio de recuperación nuevamente después de un error de transporte temporal. Una política inicial sensata es un intento de recuperación del flujo y un bucle de encuesta del proveedor pequeño y cronometrado. Ajuste esos valores solo a partir de cargas de trabajo autorizadas observadas.

Deténgase sin reintento cuando:

• el host de la página o la acción deseada difiera del evento aprobado;
• no se pueda restaurar la sesión del navegador;
• el tipo de desafío no se pueda clasificar o no tenga un adaptador configurado;
• el objetivo alcance un límite de inicio de sesión, pago, privado, restringido o datos sensibles fuera de la autorización;
• el proveedor devuelva un error terminal;
• el mismo desafío reaparezca después de aplicar el resultado;
• no ocurra la transición de aplicación esperada;
• la respuesta del servicio esté vacía, malformada o use un estado desconocido.

El flujo debe registrar el motivo de detención, el ID de correlación, el recuento de intentos y el identificador de destino redactado. No debe almacenar claves de API, cookies, valores de solución en bruto o contenido de página innecesario en registros ordinarios.

Agregue retroalimentación humana sin inventar un nodo de pausa

La retroalimentación humana depende de la superficie de Gumloop en la que esté operando. Para un flujo de trabajo estándar, dirija REVIEW a una notificación, boleto, hoja u otra cola manual, luego finalice la acción del navegador autónomo. No afirme que cada flujo de trabajo puede pausarse indefinidamente a menos que su propio plan y configuración de Gumloop lo demuestren.

Gumloop documenta por separado aprobación humana para llamadas de herramientas de agente. Si la acción de recuperación se expone a un agente de Gumloop como una herramienta aprobada, puede requerir aprobación antes de la llamada a la herramienta y permitir que el agente reanude la ejecución después de una decisión. Esa es una opción de control del agente, no una prueba de un conector de CapSolver ni un sustituto de las verificaciones de autorización del servicio de recuperación.

Un operador que revise la evidencia de resolución de CAPTCHA de Gumloop debe ver:

• el host y la acción aprobados;
• la categoría de desafío, sin el valor de solución en bruto;
• el estado de la sesión del navegador;
• los intentos utilizados y restantes;
• la última afirmación de la aplicación;
• la razón exacta por la que se detuvo la ejecución autónoma.

La aprobación debe permitir solo una acción designada, no expandir la ejecución a un nuevo host o ámbito de datos.

Pruebe las ramas de error antes de la producción

Valide la resolución de CAPTCHA de Gumloop con fixtures en un sistema que posea o esté autorizado a probar. El conjunto de aceptación debe cubrir tanto el lienzo de Gumloop como el trabajador del navegador.

1. Envíe un evento NO_CHALLENGE válido y confirme que el flujo de trabajo continúa sin llamar al punto final de recuperación.
2. Envíe un fixture aprobado de reCAPTCHA v2 y confirme que el trabajador del navegador preserva la sesión y devuelve RECOVERED solo después de que la afirmación de la aplicación pase.
3. Devuelva processing hasta que expire el presupuesto de sondeo del proveedor y confirme que el servicio devuelve STOP.
4. Simule un tiempo de espera del punto final de recuperación y confirme que Error Shield utiliza la ruta de revisión en lugar de la ruta de éxito.
5. Devuelva un estado desconocido y confirme que el Router selecciona la rama de captura general.
6. Elimine la sesión del navegador y confirme que el flujo no crea un nuevo contexto en silencio.
7. Presente un fixture de reCAPTCHA v3 o Turnstile antes de que se configure su adaptador y confirme que el resultado es REVIEW.
8. Repita el desafío después de la aplicación y confirme que el flujo no consume un bucle de reintentos ilimitado.

La evidencia final de las pruebas debe responder cuatro preguntas: ¿La ejecución fue autorizada? ¿El adaptador de desafío está documentado? ¿La misma sesión del navegador continuó? ¿Avanzó el estado de la aplicación deseado? Una respuesta "sí" solo de la llamada a la API no es suficiente.

Conclusión

La resolución de CAPTCHA de Gumloop es confiable cuando Gumloop sigue siendo el orquestador y un servicio de navegador autorizado posee la recuperación sensible a la sesión. Utilice el comportamiento documentado de Entrada, Llamar a API, Router y Error Shield; exponga un contrato HTTP pequeño; mantenga los reintentos limitados; verifique la transición original de la página y dirija la incertidumbre a la revisión. No afirme un conector nativo ni copie el estado del navegador en el flujo. Para automatización web aprobada que necesite manejo documentado de reCAPTCHA v2/v3 o Cloudflare Turnstile detrás de estos controles, evalúe CapSolver como el componente de recuperación dentro de los límites de su servicio.

Preguntas frecuentes

¿Gumloop tiene una integración oficial con CapSolver?

No se verificó un conector nativo oficial de Gumloop-CapSolver para esta guía. La implementación utiliza las capacidades documentadas de HTTP y enrutamiento de Gumloop para llamar a un servicio de recuperación propiedad de la organización que integra CapSolver.

¿Puedo llamar directamente a la API de CapSolver desde un nodo Call API de Gumloop?

El nodo Call API puede enviar solicitudes POST, pero las llamadas directas pueden exponer credenciales del proveedor y aún no preservarán ni reanudarán una sesión del navegador. Un servicio de recuperación de lado del servidor estrecho es el límite operativo más seguro, ya que almacena la clave, posee la sesión, aplica el resultado y devuelve solo un estado verificado.

¿Qué tipos de CAPTCHA debe soportar el flujo de trabajo?

Para este patrón orientado a agentes, configure adaptadores documentados separados para reCAPTCHA v2, reCAPTCHA v3 incluyendo Enterprise donde sea aplicable y Cloudflare Turnstile. No reutilice campos entre tipos de tarea o trate un tipo no admitido como un error recuperable.

¿Cuántos reintentos debe permitir un flujo de trabajo de Gumloop?

Comience con un intento de recuperación de flujo de trabajo. Mantenga la búsqueda del proveedor dentro del servicio de recuperación con su propio tiempo y presupuesto de consulta. Deténgase cuando el desafío se repita, se pierda la continuidad de la sesión, el proveedor devuelva un error o falle la verificación de la aplicación.

¿Cuándo debe Gumloop enviar una ejecución a revisión humana?

Use la revisión humana cuando la autorización sea incierta, falte la sesión del navegador, el tipo de desafío no sea admitido, la respuesta esté malformada, se agote el presupuesto de intentos o no ocurra la transición esperada de la página. La revisión no debe expandir el host, acción o ámbito de datos aprobados.