Resolva reCAPTCHA Enterprise com Node.js

Instale o pacote oficial diretamente de solvethree.com:

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

1. 1.

   Ative o perfil do site

   Configure o site de destino no console e verifique se o perfil está ativo e disponível para seu workspace. Enviar um nome de host e uma ação não cria um perfil. Consulte a configuração do perfil do site.

2. 2.

   Configure o ambiente do servidor

   No ambiente do processo Node.js, defina SOLVETHREE_API_KEY com a chave de API do seu workspace e SOLVETHREE_PROXY com a URL do seu proxy. Mantenha a chave de API no servidor; não a exponha no código do navegador.

3. 3.

   Prepare o script

   Salve o próximo exemplo como solve.mjs. Substitua accounts.example.com pelo nome de host configurado e login pela ação reCAPTCHA real da página.

Use um nome de host em site, não a URL de uma página. O reCAPTCHA usa enterprise-v3 por padrão, portanto o exemplo não precisa de recaptchaType. Não adicione type nem url. A solicitação exige exatamente um dos campos proxy ou proxyCandidates; este exemplo usa um único 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.

Execute o script com Node.js após definir as variáveis de ambiente. solve cria a tarefa uma única vez e consulta seu status periodicamente até ela ficar pronta ou lançar uma exceção. O tempo limite de 180,000 ms limita a espera do cliente.

Os campos retornados têm funções diferentes:

• result.id identifica a tarefa. Não é o token CAPTCHA.
• result.solution.token é o valor a ser enviado no campo CAPTCHA da aplicação.
• result.solution.userAgent e result.solution.secChUa são a identidade de navegador a ser usada com esse token.

Mantenha os valores da solução privados. Se precisar recuperar a operação após reiniciar o processo, salve o requestId e os dados de entrada exatos da tarefa antes de chamar solve, protegendo todas as credenciais de proxy.

Continue no mesmo script após o retorno de solve. Este exemplo usa undici, que você deve instalar separadamente conforme descrito no comentário. Ele envia o token por request.proxy e usa os dois campos de identidade de navegador retornados.

// 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();
}

Substitua a URL e os campos do formulário de acordo com o contrato da sua aplicação. O exemplo fornece apenas g-recaptcha-response; inclua todos os outros campos e dados de sessão exigidos pela aplicação. Mantenha o destino consistente com o site e a ação usados na resolução.

Como a solicitação de resolução usa um único proxy, reutilizar request.proxy mantém o envio nesse proxy. Se você alterar a solicitação para usar proxyCandidates, selecione o proxy bem-sucedido com a função auxiliar successfulProxy do SDK.

Uma tarefa pronta significa que uma solução foi gerada, não que o destino aceitou a solicitação da sua aplicação. Verifique a resposta do destino para confirmar a condição real de sucesso; imprimir um status HTTP não é suficiente. Para diagnosticar rejeições, consulte token pronto rejeitado.

O exemplo de resolução separa as falhas definitivas da tarefa dos outros erros do SDK. Mantenha essa distinção: uma tarefa com falha e uma solicitação HTTP com falha exigem tratamentos diferentes.

solve lança TaskFailedError

A exceção inclui errorCode e taskId. Chame getTask(taskId) se precisar da resposta completa da tarefa com falha, incluindo o texto do erro.

Experimente: Pare de consultar essa tarefa e corrija a causa informada antes de criar outra. Não tente novamente com dados de entrada inválidos que não foram alterados.

Um SolvethreeError inclui taskId

O SDK tem um ID para a tarefa existente.

Experimente: Retome as consultas de status com getTask. Continue enquanto o status for pending ou solving, use a solução apenas quando for ready e pare quando for failed.

A criação é interrompida e apenas requestId está disponível

Um tempo limite de conexão não prova que a tarefa não foi criada.

Experimente: Recupere com createTask usando os dados de entrada idênticos da tarefa e o mesmo requestId. Reutilizar esse ID com dados de entrada diferentes gera um conflito.

A API rejeita uma solicitação HTTP

Inspecione o status HTTP exposto por ApiError em vez de tratar a resposta como uma tarefa pronta ou com falha.

Experimente: Resolva o erro HTTP antes de processar um payload de sucesso. Não presuma que toda falha indica saldo insuficiente.

O exemplo gera um novo requestId sempre que o programa é iniciado. Executá-lo novamente sem alterações não recupera a operação: use a solicitação e os IDs salvos. O SDK nunca tenta criar a tarefa novamente de forma automática; ele respeita Retry-After em falhas temporárias nas consultas de status, dentro do prazo de resolução.

Para consultas de status explícitas e configurações de espera, consulte consultas de status de tarefas e tempos limite.