Usa el servicio de resolución de CAPTCHA en Express

Utiliza Node.js 22 o posterior y Express 5. Instala el SDK oficial de JavaScript mediante la instalación desde tarball descrita en la documentación, en lugar de asumir que está publicado en el registro de npm. El ejemplo crea un único cliente Solvethree fuera de los controladores.

• SOLVETHREE_API_KEY: la clave de API de tu espacio de trabajo. Mantenla en el servidor.
• INTEGRATION_KEY: un secreto independiente para los clientes internos de confianza. El ejemplo lo exige en la cabecera x-integration-key; no lo distribuyas a clientes de navegador. Si ya tienes middleware de autenticación, úsalo en lugar de la protección con clave compartida del ejemplo.
• CAPTCHA_SITE: el nombre de host del destino, no una URL completa. Configura un perfil de sitio activo para tu espacio de trabajo antes de crear tareas; enviar un nombre de host no crea uno.
• SOLVETHREE_PROXY: el proxy para este destino. El ejemplo proporciona un único proxy y fija la acción en login. Cambia esa acción en el servidor si tu destino utiliza otra.

Esta solicitud utiliza la configuración predeterminada de reCAPTCHA Enterprise. Necesita site, action y un proxy, no type ni url. Consulta la configuración del perfil del sitio si el destino aún no está configurado.

// npm install express and the official solvethree SDK tarball.
import express from 'express';
import { Solvethree, SolvethreeError } from '@solvethree/sdk';
const app = express();
const client = new Solvethree({ apiKey: process.env.SOLVETHREE_API_KEY });
const secret = process.env.INTEGRATION_KEY;
if (!secret) throw new Error('Set INTEGRATION_KEY');
app.use((request, response, next) => {
  if (request.get('x-integration-key') !== secret) return response.sendStatus(401);
  next();
});
app.post('/captcha/tasks', async (request, response) => {
  const task = await client.createTask({
    site: process.env.CAPTCHA_SITE, action: 'login', proxy: process.env.SOLVETHREE_PROXY,
    requestId: request.get('x-request-id'),
  }, { waitMs: 0, signal: AbortSignal.timeout(20000) });
  response.json(task);
});
app.get('/captcha/tasks/:id', async (request, response) => {
  response.json(await client.getTask(request.params.id, { waitMs: 15000, signal: AbortSignal.timeout(25000) }));
});
app.use((error, request, response, next) => {
  if (error instanceof SolvethreeError) return response.status(502).json({ requestId: error.requestId, taskId: error.taskId });
  response.status(400).json({ error: 'Invalid task input or ID' });
});
app.listen(3000);

Ambas rutas están protegidas por el mecanismo de autenticación. El controlador POST obtiene el nombre de host, la acción y el proxy de la configuración del servidor, no del cuerpo de la solicitud. Solo el identificador opcional de creación procede de quien realiza la llamada.

1. 1.

   Asigna un ID de solicitud antes de la creación

   Envía x-request-id con entre 1 y 64 letras ASCII, números, guiones bajos o guiones. Consérvalo junto con la solicitud lógica para poder recuperar la creación si la conexión agota el tiempo de espera.

2. 2.

   Envía un POST a /captcha/tasks una sola vez

   El controlador llama a createTask con waitMs: 0 y devuelve la tarea. Guarda su ID. Una respuesta correcta significa que tienes una tarea, no necesariamente una solución.

3. 3.

   Consulta el estado con GET

   Llama a /captcha/tasks/:id. Sigue consultando mientras el estado sea pending o solving; no repitas el POST para comprobar el progreso. Detente cuando sea ready o failed.

4. 4.

   Utiliza solo una solución lista

   Envía el token con los valores devueltos de userAgent y secChUa, utilizando el mismo proxy configurado y el destino previsto. El SDK no lo envía por ti. Una tarea lista significa que se ha generado una solución, no que el destino haya aceptado la solicitud de tu aplicación.

La llamada POST al SDK tiene un límite de 20 segundos mediante AbortSignal. GET permite esperar 15 segundos por la tarea dentro de un límite de 25 segundos para la llamada al SDK. Una respuesta GET aún puede no ser definitiva; comprueba su estado en lugar de interpretar el fin de la espera como una resolución fallida.

Que se agote el tiempo de espera de la creación no demuestra que solvethree haya rechazado la solicitud. Si recibiste un ID de tarea, recupérala. De lo contrario, repite la creación con el mismo ID de solicitud y sin cambiar los datos de entrada de la tarea para recuperar la tarea existente. Reutilizar ese ID con datos de entrada diferentes genera un conflicto. Si no has conservado un ID de solicitud, un nuevo POST corre el riesgo de crear trabajo independiente.

Express 5 reenvía los rechazos de los controladores asíncronos al middleware de errores. El ejemplo devuelve HTTP 502 para SolvethreeError y expone solo sus identificadores de solicitud y tarea, no el error sin procesar, las credenciales ni la solución. Su respuesta alternativa HTTP 400 es genérica; no clasifica con precisión todos los errores ajenos al SDK, incluidos los errores por superar el límite de tiempo.

Gestiona los errores HTTP antes de leer los datos de una respuesta correcta. Por separado, una tarea recuperada puede tener el estado failed: revisa su errorCode y su error y deja de consultar. Las resoluciones fallidas se reembolsan, pero reintentar con los mismos datos de entrada no válidos no los corregirá. Utiliza la referencia de errores de la API para diagnosticar el fallo indicado.