Migra una integración de reCAPTCHA de CapSolver a solvethree

solvethree usa reCAPTCHA v3 Enterprise de forma predeterminada y también admite v3 estándar. Sus otros productos públicos son Kasada y Ticketmaster TMPT. No admite reCAPTCHA v2, hCaptcha, Turnstile ni la resolución mediante extensiones del navegador, por lo que no es un sustituto universal para todas las integraciones de CapSolver.

Antes de enviar una tarea de reCAPTCHA, configura el sitio de destino en la consola y comprueba que tu espacio de trabajo tenga disponible un perfil activo. Enviar un nombre de host y una acción no crea ese perfil. No elimines el campo websiteKey de CapSolver suponiendo que el resto de la solicitud es suficiente.

La solicitud inicial usa clientKey de CapSolver y una estructura de tarea específica del proveedor:

{
  "clientKey": "CAPSOLVER_API_KEY",
  "task": {
    "type": "ReCaptchaV3Task",
    "websiteURL": "https://accounts.example.com/login",
    "websiteKey": "PUBLIC_SITE_KEY",
    "pageAction": "login",
    "isEnterprise": true,
    "proxy": "http://user:[email protected]:8080"
  }
}

Para solvethree, envía el cuerpo plano siguiente a POST https://api.solvethree.com/v1/tasks. Establece la cabecera Authorization en Bearer seguido de la clave de API de tu espacio de trabajo. Mantén esa clave en el servidor; no incluyas clientKey en el nuevo cuerpo JSON.

{
  "site": "accounts.example.com",
  "action": "login",
  "proxy": "http://user:[email protected]:8080",
  "requestId": "example_login_001"
}

El ejemplo es una solicitud Enterprise porque deja recaptchaType en su valor predeterminado. Selecciona explícitamente v3 estándar cuando sea lo que use tu destino; no conviertas todos los tipos de tarea de CapSolver al valor Enterprise predeterminado.

Una tarea ProxyLess de CapSolver no tiene aquí un equivalente directo sin proxy: solvethree requiere que quien realiza la llamada proporcione un proxy. Si tu integración actual no gestiona un proxy, eso supone un cambio en la integración, no un cambio de nombre de campo. Tampoco copies una configuración de proxy SOCKS en la nueva solicitud; solvethree admite URL de proxy HTTP y HTTPS.

Empieza con un solo proxy para que no haya dudas sobre la ruta usada para la resolución y el envío. Si usas proxyCandidates en su lugar, proporciona como máximo doce URL de proxy HTTP o HTTPS distintas, sin rutas, cadenas de consulta ni fragmentos. Los candidatos permiten que el servicio pruebe salidas alternativas; no garantizan que un proxy o un destino vaya a funcionar.

CapSolver recupera los resultados asíncronos mediante getTaskResult con clientKey y taskId. solvethree los recupera mediante GET /v1/tasks/:id con autenticación Bearer. Actualiza tanto el analizador de resultados como la llamada HTTP; los campos de estado y error de CapSolver pertenecen a un contrato diferente.

1. 1.

   Comprueba primero la respuesta HTTP

   Gestiona las respuestas HTTP no satisfactorias antes de leer el contenido de una respuesta satisfactoria. Un error de solicitud HTTP y una tarea de resolución fallida requieren una gestión independiente.

2. 2.

   Inspeccionar la tarea devuelta al crearla

   La creación de reCAPTCHA espera hasta 15 segundos de forma predeterminada, por lo que la respuesta puede estar ya en un estado final. Solo ready contiene una solución utilizable. Si la tarea está en pending o solving, recupérala usando el ID de tarea de solvethree devuelto.

3. 3.

   Dejar de consultar al llegar a ready o failed

   Para ready, pasa la solución a tu código de envío. Para failed, inspecciona errorCode y error y deja de consultar esa tarea. Las resoluciones fallidas se reembolsan. No reintentes a ciegas con los mismos datos de entrada no válidos ni asumas que cada fallo significa que no hay crédito suficiente.

Durante una migración por etapas, mantén cada ID de tarea etiquetado con su proveedor. Finaliza las tareas existentes de CapSolver a través de CapSolver y dirige las nuevas tareas de solvethree a través de solvethree. Normaliza sus resultados en tu adaptador en lugar de enviar el ID de tarea de un proveedor anterior a la nueva API.

Usa solution.token al enviar el resultado de reCAPTCHA al destino previsto. Conserva también los valores devueltos de userAgent y secChUa, y usa el proxy que funcionó para el envío. Si tu adaptador actual devuelve solo una cadena de token, modifícalo para que transmita esa información hasta el cliente que realiza el envío.

Si se rechaza un token listo, inspecciona la solicitud saliente de la aplicación antes de pagar por otra resolución. Comprueba que contenga el nuevo token —no un ID de tarea ni un token antiguo— y que el envío use la identidad de navegador devuelta, el proxy que funcionó y la URL de destino prevista. Una tarea en ready significa que se generó una solución, no que el destino aceptara tu solicitud posterior.

El ejemplo posterior al cambio incluye requestId para la recuperación. Genera uno para cada nueva tarea lógica y guárdalo junto con los datos de entrada exactos de la solicitud. Debe contener entre 1 y 64 letras ASCII, números, guiones bajos o guiones. Reutilizarlo con la misma solicitud de tarea devuelve la tarea existente; usarlo con datos de entrada diferentes provoca un conflicto.

Si se agota el tiempo de espera de la creación, recupera la tarea si tienes su ID o vuelve a enviar el mismo cuerpo con el mismo requestId. Perder una respuesta no demuestra que la creación haya fallado. No generes un ID nuevo solo porque tu cliente dejó de esperar.

Al configurar el tiempo de espera de tu cliente, deja margen para la espera predeterminada de creación de reCAPTCHA de hasta 15 segundos, más la sobrecarga de red. Las consultas GET devuelven una respuesta sin esperar de forma predeterminada y admiten waitMs de hasta 15000. Incluye waitMs en la cadena de consulta de la URL, no en el JSON de la tarea, y ten en cuenta esa espera también en el tiempo de espera de las consultas.