Use o solucionador de CAPTCHA no Express

Use Node.js 22 ou posterior e Express 5. Instale o SDK oficial de JavaScript usando a instalação via tarball descrita na documentação, em vez de presumir que ele está publicado no registro npm. O exemplo cria um único cliente Solvethree fora dos handlers.

• SOLVETHREE_API_KEY: a chave de API do seu workspace. Mantenha-a no servidor.
• INTEGRATION_KEY: um segredo separado para clientes internos confiáveis. O exemplo o exige no cabeçalho x-integration-key; não o distribua a clientes de navegador. Se você já tem um middleware de autenticação, use-o em vez da proteção por chave compartilhada do exemplo.
• CAPTCHA_SITE: o nome de host do destino, não uma URL completa. Configure um perfil de site ativo para o seu workspace antes de criar tarefas; enviar um nome de host não cria um perfil.
• SOLVETHREE_PROXY: o proxy para esse destino. O exemplo fornece um único proxy e fixa a ação em login. Altere essa ação no servidor se o destino usar outra.

Essa requisição usa a configuração padrão do reCAPTCHA Enterprise. Ela precisa de site, action e um proxy — não de type ou url. Consulte a configuração do perfil do site se o destino ainda não estiver 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);

As duas rotas são protegidas pela verificação de autenticação. O handler POST obtém o nome de host, a ação e o proxy da configuração do servidor, não do corpo da requisição. Somente o identificador opcional de criação vem de quem faz a chamada.

1. 1.

   Atribua um ID de requisição antes da criação

   Envie x-request-id com 1–64 letras ASCII, números, sublinhados ou hífens. Guarde-o junto com a requisição lógica para poder recuperar a criação se a conexão atingir o tempo limite.

2. 2.

   Faça POST em /captcha/tasks uma única vez

   O handler chama createTask com waitMs: 0 e retorna a tarefa. Guarde o ID dela. Uma resposta bem-sucedida significa que você tem uma tarefa, não necessariamente uma solução.

3. 3.

   Consulte o status com GET

   Chame /captcha/tasks/:id. Continue consultando enquanto o status for pending ou solving; não repita o POST para verificar o progresso. Pare em ready ou failed.

4. 4.

   Use apenas uma solução pronta

   Envie o token com os valores retornados de userAgent e secChUa, usando o mesmo proxy configurado e o destino pretendido. O SDK não faz o envio por você. Uma tarefa pronta significa que uma solução foi gerada, não que o destino aceitou a requisição da sua aplicação.

A chamada POST do SDK tem um limite de 20 segundos definido por AbortSignal. O GET permite uma espera de 15 segundos pela tarefa dentro de um limite de 25 segundos para a chamada do SDK. Uma resposta GET ainda pode indicar um estado não terminal; verifique seu status em vez de tratar o fim da espera como uma falha de resolução.

Um tempo limite na criação não prova que o solvethree rejeitou a requisição. Se você recebeu um ID de tarefa, consulte-a. Caso contrário, repita a criação com o mesmo ID de requisição e os mesmos dados de entrada da tarefa para recuperar a tarefa existente. Reutilizar esse ID com dados de entrada diferentes gera um conflito. Sem um ID de requisição guardado, um novo POST corre o risco de criar trabalho separado.

O Express 5 encaminha as rejeições de handlers assíncronos ao middleware de erros. O exemplo retorna HTTP 502 para SolvethreeError, expondo apenas seus identificadores de requisição e tarefa — não o erro bruto, as credenciais ou a solução. Sua resposta alternativa HTTP 400 é genérica; ela não classifica com precisão todos os erros que não são do SDK, incluindo erros de limite de tempo.

Trate os erros HTTP antes de ler um payload de sucesso. Separadamente, uma tarefa consultada pode ter o status failed: verifique seu errorCode e error e pare as consultas periódicas. Resoluções que falham são reembolsadas, mas tentar novamente com os mesmos dados de entrada inválidos não os corrigirá. Use a referência de erros da API para diagnosticar a falha informada.