Chame o solucionador a partir de um Route Handler do Next.js

• Use Node.js 22+ e o SDK oficial de JavaScript. Siga a instalação pela URL do pacote na documentação; não presuma que há um pacote disponível no registro npm.
• Defina SOLVETHREE_API_KEY, CAPTCHA_SITE, SOLVETHREE_PROXY e INTEGRATION_KEY no ambiente do servidor. Não use o prefixo NEXT_PUBLIC_ em nenhum dos dois segredos.
• Ative um perfil para o hostname de destino no seu workspace antes de chamar a rota. Definir CAPTCHA_SITE não cria um perfil; veja a configuração do perfil do site.
• Substitua a ação login do exemplo pela ação exigida pela sua integração. A requisição usa um proxy e adota reCAPTCHA Enterprise v3 por padrão; ela não precisa dos campos type ou url.

Coloque o exemplo em app/api/captcha/route.js. Ele exporta handlers HTTP do App Router e seleciona explicitamente o runtime Node.js para o SDK. Mantenha-o como uma rota de servidor executada a cada requisição, não como um recurso gerado estaticamente.

import { Solvethree, SolvethreeError } from '@solvethree/sdk';
export const runtime = 'nodejs';
const client = new Solvethree({ apiKey: process.env.SOLVETHREE_API_KEY });
function authorized(request) {
  const key = process.env.INTEGRATION_KEY;
  return Boolean(key) && request.headers.get('x-integration-key') === key;
}
function failure(error) {
  return error instanceof SolvethreeError
    ? Response.json({ requestId: error.requestId, taskId: error.taskId }, { status: 502 })
    : Response.json({ error: 'Invalid task input or ID' }, { status: 400 });
}
export async function POST(request) {
  if (!authorized(request)) return new Response('Unauthorized', { status: 401 });
  try {
    return Response.json(await client.createTask({
      site: process.env.CAPTCHA_SITE, action: 'login', proxy: process.env.SOLVETHREE_PROXY,
      requestId: request.headers.get('x-request-id') ?? undefined,
    }, { waitMs: 0, signal: AbortSignal.timeout(20000) }));
  } catch (error) { return failure(error); }
}
export async function GET(request) {
  if (!authorized(request)) return new Response('Unauthorized', { status: 401 });
  const id = new URL(request.url).searchParams.get('id');
  if (!id) return Response.json({ error: 'Provide id' }, { status: 400 });
  try {
    return Response.json(await client.getTask(id, { waitMs: 15000, signal: AbortSignal.timeout(25000) }));
  } catch (error) { return failure(error); }
}

POST chama createTask com waitMs: 0, retornando a resposta da tarefa sem esperar por uma solução. Salve o ID da tarefa retornado. GET exige esse ID existente e chama getTask; ele nunca cria uma tarefa.

GET solicita uma espera de até 15 segundos, com um cancelamento separado da requisição após 25 segundos. POST cancela a requisição após 20 segundos. Esses limites se aplicam a cada requisição, não ao tempo de vida da tarefa.

Para acesso pelo navegador, use a autenticação real da sua aplicação no servidor em vez de distribuir INTEGRATION_KEY. A autenticação sozinha não basta: aceitar qualquer ID de tarefa de um usuário autenticado ainda permitiria que ele solicitasse o resultado de outra pessoa.

1. 1.

   Associe a criação ao solicitante

   Depois que um POST autenticado criar uma tarefa, armazene seu ID associado ao usuário ou tenant autenticado antes de retorná-lo. Associe também o requestId lógico a esse proprietário, para que a recuperação não perca o registro de propriedade.

2. 2.

   Verifique a propriedade antes da consulta

   No GET, autentique o solicitante e verifique o ID fornecido no registro de propriedade antes de chamar getTask. Rejeite IDs que não pertençam ao solicitante e retorne os resultados somente após essa verificação ser bem-sucedida.

Mantenha o site, a ação e o proxy sob controle do servidor, a menos que sua aplicação autorize explicitamente os solicitantes a escolhê-los. Os valores fixos de ambiente deste exemplo impedem que o cliente altere essas entradas.

1. 1.

   Continue consultando tarefas em estados não terminais

   Para pending ou solving, consulte o mesmo ID novamente, respeitando o prazo total da sua aplicação. O término de uma espera GET não é motivo para criar outra tarefa.

2. 2.

   Pare em ready ou failed

   Somente ready contém uma solução utilizável. Para failed, pare as consultas e examine errorCode e error; resoluções que falham são reembolsadas. Trate respostas HTTP sem sucesso antes de interpretar uma resposta como uma tarefa. O handler catch da rota não substitui a verificação do status da tarefa retornada.

3. 3.

   Recupere a criação após um timeout de conexão

   Escolha e guarde um x-request-id antes do POST. Se você recebeu um ID de tarefa, consulte-o. Se a resposta de criação foi perdida, repita o POST com o mesmo ID de requisição e as entradas da tarefa inalteradas para recuperar a tarefa existente. IDs de requisição aceitam de 1–64 letras ASCII, números, sublinhados ou hífens; reutilizar um deles com entradas diferentes causa conflito.

Uma tarefa em ready significa que o solvethree gerou uma solução, não que o destino a aceitou. O SDK não a envia por você. Ao enviá-la, use os valores retornados de userAgent e secChUa com o proxy que teve sucesso — o proxy configurado neste exemplo de proxy único. Não troque para uma identidade de navegador ou um IP sem relação com a resolução.

Para erros de requisição ou falhas terminais, consulte a referência de erros da API antes de pagar por outra resolução. Repetir entradas inválidas sem alterá-las não vai corrigi-las.