Resuelve reCAPTCHA Enterprise con Node.js

Instala el paquete oficial directamente desde solvethree.com:

npm install https://solvethree.com/downloads/solvethree-sdk-0.1.0.tgz

1. 1.

   Activa el perfil del sitio

   Configura el sitio de destino en la consola y asegúrate de que su perfil esté activo y disponible para tu espacio de trabajo. Enviar un nombre de host y una acción no crea un perfil. Consulta la configuración del perfil del sitio.

2. 2.

   Configura el entorno del servidor

   Establece SOLVETHREE_API_KEY en la clave de API de tu espacio de trabajo y SOLVETHREE_PROXY en la URL de tu proxy en el entorno del proceso de Node.js. Mantén la clave de API en el servidor; no la expongas en código del navegador.

3. 3.

   Prepara el script

   Guarda el siguiente ejemplo como solve.mjs. Sustituye accounts.example.com por el nombre de host que hayas configurado y login por la acción real de reCAPTCHA de la página.

Usa un nombre de host en site, no la URL de una página. reCAPTCHA usa enterprise-v3 de forma predeterminada, así que el ejemplo no necesita recaptchaType. No añadas type ni url. La solicitud requiere exactamente uno de los campos proxy o proxyCandidates; este ejemplo usa un solo proxy.

import { randomUUID } from 'node:crypto';
import { Solvethree, SolvethreeError, TaskFailedError } from '@solvethree/sdk';

const client = new Solvethree({ apiKey: process.env.SOLVETHREE_API_KEY });
const request = {
  site: 'accounts.example.com', // Use your configured hostname.
  action: 'login',              // Use the page's actual action.
  proxy: process.env.SOLVETHREE_PROXY,
  requestId: randomUUID(),
};
let result;
try {
  result = await client.solve(request, { timeoutMs: 180_000 });
} catch (error) {
  if (error instanceof TaskFailedError) {
    throw new Error(`Task failed: ${error.errorCode}`);
  }
  if (error instanceof SolvethreeError) {
    // Save these IDs; use them to recover the existing task.
    console.error({ requestId: error.requestId, taskId: error.taskId });
  }
  throw error;
}
const { token, userAgent, secChUa } = result.solution;
console.log('Ready task:', result.id); // Keep solution credentials private.

Ejecuta el script con Node.js después de configurar las variables de entorno. solve crea la tarea una sola vez y consulta su estado hasta que esté lista o se lance una excepción. El tiempo de espera de 180,000 ms limita cuánto espera el cliente.

Los campos devueltos tienen funciones distintas:

• result.id identifica la tarea. No es el token de CAPTCHA.
• result.solution.token es el valor que debes enviar en el campo CAPTCHA de la aplicación.
• result.solution.userAgent y result.solution.secChUa son la identidad de navegador que debes usar con ese token.

Mantén privados los valores de la solución. Si necesitas recuperar la operación tras reiniciar el proceso, guarda requestId y los datos de entrada exactos de la tarea antes de llamar a solve, protegiendo las credenciales del proxy.

Continúa en el mismo script después de que solve devuelva el resultado. Este ejemplo usa undici, que debes instalar por separado como indica su comentario. Envía el token a través de request.proxy y usa los dos campos de identidad de navegador devueltos.

// Continue after client.solve(). Install undici separately: npm install undici@7.
import { fetch, ProxyAgent } from 'undici';

const dispatcher = new ProxyAgent(request.proxy);
try {
  // Replace the URL and form fields with your application's contract.
  const response = await fetch('https://accounts.example.com/login', {
    method: 'POST',
    dispatcher,
    redirect: 'manual',
    headers: {
      'user-agent': result.solution.userAgent,
      'sec-ch-ua': result.solution.secChUa,
    },
    body: new URLSearchParams({
      'g-recaptcha-response': result.solution.token,
    }),
    signal: AbortSignal.timeout(30_000),
  });
  console.log('Application HTTP status:', response.status);
  await response.arrayBuffer();
} finally {
  await dispatcher.close();
}

Sustituye la URL y los campos del formulario por los que exige tu aplicación. El ejemplo solo proporciona g-recaptcha-response; incluye los demás campos y datos de sesión que requiera la aplicación. Mantén el destino coherente con el sitio y la acción usados en la resolución.

Como la solicitud de resolución usa un solo proxy, reutilizar request.proxy mantiene el envío en ese proxy. Si cambias la solicitud para usar proxyCandidates, selecciona en su lugar el proxy que tuvo éxito con la función auxiliar successfulProxy del SDK.

Que una tarea esté lista significa que se ha generado una solución, no que el destino haya aceptado la solicitud de tu aplicación. Comprueba en la respuesta del destino su condición real de éxito; imprimir un estado HTTP no basta. Para diagnosticar rechazos, consulta token listo rechazado.

El ejemplo de resolución distingue los fallos terminales de las tareas de otros errores del SDK. Mantén esa distinción: una tarea fallida y una solicitud HTTP fallida requieren tratamientos distintos.

solve lanza TaskFailedError

La excepción incluye errorCode y taskId. Llama a getTask(taskId) si necesitas la respuesta completa de la tarea fallida, incluido el texto del error.

Prueba esto: Deja de consultar esa tarea y corrige la causa indicada antes de crear otra. No reintentes con los mismos datos de entrada no válidos.

Un SolvethreeError incluye taskId

El SDK tiene un ID para la tarea existente.

Prueba esto: Reanuda las consultas con getTask. Continúa mientras el estado sea pending o solving, usa la solución solo cuando sea ready y detente si es failed.

La creación se interrumpe y solo está disponible requestId

Que se agote el tiempo de espera de la conexión no demuestra que la tarea no se haya creado.

Prueba esto: Recupera la tarea con createTask usando exactamente los mismos datos de entrada y el mismo requestId. Reutilizar ese ID con datos de entrada distintos genera un conflicto.

La API rechaza una solicitud HTTP

Inspecciona el estado HTTP que expone ApiError en lugar de tratar la respuesta como una tarea lista o fallida.

Prueba esto: Resuelve el error HTTP antes de procesar un cuerpo de respuesta de éxito. No des por hecho que todos los fallos se deben a saldo insuficiente.

El ejemplo genera un nuevo requestId cada vez que se inicia el programa. Volver a ejecutarlo sin cambios no recupera la operación: usa la solicitud y los ID guardados. El SDK nunca reintenta automáticamente la creación de tareas; sí respeta Retry-After ante fallos temporales de las consultas dentro del plazo de resolución.

Para configurar las consultas explícitas y la espera, consulta consultas de tareas y tiempos de espera.