Como Implementar uma API de Resolução de CAPTCHA em JavaScript

TL;DR

• O CapSolver oferece uma API REST simples: chame /createTask para enviar um CAPTCHA e, em seguida, faça polling em /getTaskResult até que status === 'ready'.
• Tipos de desafios suportados neste guia: reCAPTCHA v2, reCAPTCHA v3 e Cloudflare Turnstile.
• Armazene sua chave de API no .env — nunca a codifique diretamente.
• Use axios + um loop de polling para uma integração limpa e pronta para produção em Node.js.
• Adicione lógica de repetição com backoff exponencial para resiliência em tarefas de automação de longa duração.

Introdução

Projetos modernos de automação web e coleta de dados frequentemente encontram desafios de CAPTCHA que interrompem fluxos de trabalho. Seja você construindo um scraper de web, automatizando tarefas no navegador ou desenvolvendo um agente de IA, integrar uma solução confiável para resolver CAPTCHA torna-se essencial. CapSolver fornece uma API alimentada por inteligência artificial que lida com esses desafios de forma programática, e este guia o orienta passo a passo na implementação dessa API em JavaScript.

O tráfego automatizado agora representa quase metade de todo o tráfego da internet, tornando a detecção de bots e desafios de CAPTCHA cada vez mais comuns em aplicações web. Para desenvolvedores que construem fluxos de automação legítimos, ter uma solução programática confiável deixou de ser opcional — é uma exigência de infraestrutura fundamental.

Entendendo o Fluxo de Trabalho da API do CapSolver

Antes de mergulhar no código, entender como o CapSolver processa solicitações de CAPTCHA ajuda a arquitetar sua integração corretamente. O fluxo segue um padrão simples: enviar uma tarefa, fazer polling para conclusão e receber a solução.

Quando você envia um desafio de CAPTCHA ao CapSolver, o sistema atribui uma identificação única para a tarefa. Sua aplicação, em seguida, faz polling no serviço em intervalos regulares até que a solução esteja pronta. Ao concluir, você recebe uma resposta contendo o token ou os dados necessários para prosseguir com seu fluxo de automação.

O CapSolver suporta diversos tipos de CAPTCHA, incluindo reCAPTCHA v2/v3, Cloudflare Turnstile e desafios de imagem para texto. O fluxo da API permanece consistente entre os tipos de desafio, embora os parâmetros da tarefa variem conforme a solução específica necessária. Para uma lista completa dos tipos de tarefa suportados, consulte a referência de tipos de tarefa do CapSolver. Se você for novo na plataforma, o guia de início aborda a configuração da conta e sua primeira chamada à API. Para uma visão mais ampla de como o CapSolver se encaixa em pipelines de raspagem de web, veja como integrar o CapSolver ao seu fluxo de automação.

Configuração do Projeto

Este guia o orienta na implementação da API de resolução de CAPTCHA do CapSolver especificamente para projetos JavaScript e Node.js. Certifique-se de ter Node.js 18+ instalado e uma chave de API do CapSolver pronta em seu painel de conta.

Estrutura do projeto:

capsolver-integration/
├── .env                 # Variáveis de ambiente
├── capsolver-client.js  # Cliente da API principal
├── index.js             # Exemplo de uso
└── package.json

Inicialize seu projeto e instale as dependências:

mkdir capsolver-integration
cd capsolver-integration
npm init -y
npm install axios dotenv

axios é um cliente HTTP amplamente utilizado para Node.js que fornece sintaxe baseada em promessas limpa e tratamento integrado de timeout — ambos úteis ao fazer polling em uma API externa.

Crie um arquivo .env para armazenar sua chave de API de forma segura:

CAPSOLVER_API_KEY=your-api-key-here

Nota de segurança: Nunca comite seu arquivo .env no controle de versão. Adicione-o imediatamente ao .gitignore. Chaves de API expostas podem levar ao uso não autorizado e cobranças inesperadas. Veja Gerenciamento de Segredos da OWASP para melhores práticas no manejo de credenciais em projetos de automação.

Criando o Cliente da API Principal

A base da sua integração é um cliente reutilizável que lida com autenticação e formatação de solicitações. Este cliente encapsula o endpoint da API e fornece métodos para cada operação. Salve isso como capsolver-client.js:

// capsolver-client.js
const axios = require('axios');

class CapSolverClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.capsolver.com';
  }

  async request(endpoint, data) {
    const response = await axios.post(`${this.baseUrl}${endpoint}`, {
      ...data,
      clientKey: this.apiKey
    }, {
      headers: { 'Content-Type': 'application/json' },
      timeout: 30000
    });
    return response.data;
  }

  delay(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

module.exports = CapSolverClient;

Nota: Os exemplos de código neste guia ilustram padrões de implementação com base na estrutura da API documentada do CapSolver. Sempre verifique os caminhos de endpoint mais recentes, nomes de tipos de tarefa e formatos de solicitação/resposta contra a documentação oficial da API do CapSolver, pois esses detalhes podem mudar.

Este cliente lida com as partes repetitivas da comunicação com a API, incluindo a definição de cabeçalhos e a formatação do corpo da solicitação com sua chave de cliente.

Verificando o Saldo da Conta

Antes de resolver CAPTCHAs em larga escala, verifique se sua conta tem créditos suficientes. O CapSolver opera com um modelo de pagamento por solução bem-sucedida, então verificar seu saldo evita falhas inesperadas durante o fluxo de trabalho.

// Adicione à classe CapSolverClient
async getBalance() {
  const result = await this.request('/getBalance', {});

  if (result.errorCode) {
    throw new Error(`Falha na verificação do saldo: ${result.errorCode} - ${result.errorDescription}`);
  }

  return {
    balance: result.balance,
    currency: result.currency || 'USD'
  };
}

Muitos desenvolvedores incluem a verificação do saldo em sua sequência de inicialização para falhar rapidamente se os créditos estiverem esgotados antes de iniciar uma automação longa.

Resolvendo reCAPTCHA v2

reCAPTCHA v2 apresenta o desafio de caixa de seleção familiar ou tarefas de seleção de imagem. Para resolvê-los, você precisa da URL da página de destino e da chave do site embutida no HTML da página. O token resolvido é então enviado como parte do formulário ou da solicitação.

// Adicione à classe CapSolverClient
async solveReCaptchaV2(websiteUrl, websiteKey) {
  const task = {
    type: 'RecaptchaV2Task',
    websiteURL: websiteUrl,
    websiteKey: websiteKey
  };
  return await this.submitAndWait(task);
}

async submitAndWait(task) {
  // Etapa 1: Enviar a tarefa
  const submitResult = await this.request('/createTask', { task });

  if (submitResult.errorCode) {
    throw new Error(`Falha na criação da tarefa: ${submitResult.errorCode}`);
  }

  const taskId = submitResult.taskId;

  // Etapa 2: Fazer polling para o resultado
  while (true) {
    await this.delay(1500);

    const result = await this.request('/getTaskResult', { taskId });

    if (result.status === 'ready') {
      return result.solution;
    }

    if (result.status === 'failed') {
      throw new Error(`Falha na resolução: ${result.errorDescription || 'Erro desconhecido'}`);
    }
    // status === 'processing' → continuar fazendo polling
  }
}

O intervalo de polling de 1,5 segundos equilibra responsividade com os limites de taxa da API. O campo status será processing enquanto a tarefa estiver em execução, ready quando a solução estiver disponível ou failed se o desafio não puder ser resolvido. Para o esquema de resposta completo, consulte a referência da API getTaskResult.

Resolvendo reCAPTCHA v3

A reCAPTCHA v3 funciona de forma diferente — ela roda em segundo plano e retorna uma pontuação de risco em vez de apresentar um desafio visual. O CapSolver pode resolver desafios v3, permitindo que você especifique o limite mínimo de pontuação exigido por seu site de destino.

// Adicione à classe CapSolverClient
async solveReCaptchaV3(websiteUrl, websiteKey, options = {}) {
  const {
    pageAction = 'verify',
    minScore = 0.9
  } = options;

  const task = {
    type: 'RecaptchaV3Task',
    websiteURL: websiteUrl,
    websiteKey: websiteKey,
    pageAction: pageAction,
    minScore: minScore
  };

  return await this.submitAndWait(task);
}

Tarefas de reCAPTCHA v3 normalmente são concluídas mais rapidamente do que as tarefas v2, pois não exigem interação com desafios visuais. O parâmetro pageAction deve corresponder à string de ação definida na página de destino.

Resolvendo Cloudflare Turnstile

Desafios de Cloudflare Turnstile frequentemente aparecem em fluxos de automação, especialmente ao raspar sites protegidos pelo Cloudflare. O CapSolver fornece suporte dedicado a esses desafios:

// Adicione à classe CapSolverClient
async solveTurnstile(websiteUrl, websiteKey, options = {}) {
  const {
    pageAction = 'managed',
    metadata = {}
  } = options;

  const task = {
    type: 'AntiCloudflareTask',
    websiteURL: websiteUrl,
    websiteKey: websiteKey,
    pageAction: pageAction,
    metadata: metadata
  };

  return await this.submitAndWait(task);
}

Para cenários avançados de Cloudflare — incluindo páginas de desafio e fingerprinting de navegador — consulte o guia sobre automatização da resolução de CAPTCHA em navegadores headless.

Juntando Tudo

Aqui está um index.js completo demonstrando como usar o cliente em um cenário de automação real:

// index.js
const CapSolverClient = require('./capsolver-client');
require('dotenv').config();

async function main() {
  const client = new CapSolverClient(process.env.CAPSOLVER_API_KEY);

  try {
    // Verifique o saldo antes de iniciar
    const { balance, currency } = await client.getBalance();
    console.log(`Saldo da conta: ${balance} ${currency}`);

    if (balance < 0.01) {
      throw new Error('Saldo insuficiente. Por favor, faça um recarregamento em sua conta do CapSolver.');
    }

    // Exemplo: Resolver reCAPTCHA v2
    const solution = await client.solveReCaptchaV2(
      'https://example.com/login',
      '6Le-wvkAAAAAATBQbZDLjMjqTLV92vP6EXjs'
    );

    console.log('CAPTCHA resolvido com sucesso');
    console.log('Token:', solution.gRecaptchaResponse);

    // Injete o token em seu fluxo de automação
    // await page.evaluate(token => {
    //   document.getElementById('g-recaptcha-response').value = token;
    // }, solution.gRecaptchaResponse);

  } catch (error) {
    console.error('Erro:', error.message);
    process.exit(1);
  }
}

main();

Tratamento de Erros e Retentativas

Integrações de produção precisam de tratamento robusto de erros. Problemas de rede, interrupções temporárias da API e falhas no CAPTCHA podem ocorrer, então implementar lógica de retentativa melhora significativamente a confiabilidade:

async function withRetry(operation, maxAttempts = 3, delayMs = 2000) {
  let lastError;

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await operation();
    } catch (error) {
      lastError = error;
      console.warn(`Tentativa ${attempt}/${maxAttempts} falhou: ${error.message}`);

      if (attempt < maxAttempts) {
        await new Promise(resolve => setTimeout(resolve, delayMs * attempt));
      }
    }
  }

  throw lastError;
}

// Uso
const solution = await withRetry(() =>
  client.solveReCaptchaV2('https://example.com', 'sua-chave-de-site')
);

O backoff exponencial (delayMs * attempt) evita sobrecarregar a API durante falhas temporárias e dá tempo ao serviço se recuperar.

Melhores Práticas para Integração em JavaScript

Proteja sua chave de API. Sempre carregue credenciais a partir de variáveis de ambiente, nunca as codifique diretamente. Use arquivos .env localmente e gerenciamento adequado de segredos em pipelines CI/CD.

Defina timeouts para tarefas. Adicione uma duração máxima de polling para evitar que sua automação fique travada indefinidamente se uma tarefa estiver travada. Um timeout de 120 segundos cobre a maioria das situações de resolução.

Monitore seu saldo programaticamente. Para tarefas de automação de longa duração, verifique seu saldo ao iniciar e, opcionalmente, em intervalos regulares. Isso evita falhas silenciosas durante a execução.

Corresponda o tipo de tarefa ao desafio. Usar o tipo de tarefa errado é uma fonte comum de falhas. Sempre inspecione o HTML da página de destino para confirmar o tipo de CAPTCHA e extraia a chave de site correta antes de enviar uma tarefa.

Respeite os limites de taxa. Evite enviar tarefas mais rápido do que seu fluxo pode consumir resultados. Fila de tarefas e processamento a uma taxa controlada levam a uma taxa de throughput mais estável.

Para uma visão mais abrangente sobre a integração da resolução de CAPTCHA em pipelines de raspagem, veja como integrar o CapSolver ao seu fluxo de automação ou raspagem, que aborda padrões adicionais incluindo Puppeteer e Playwright. Se seu projeto envolver navegadores headless especificamente, automatizando a resolução de CAPTCHA em navegadores headless explica a configuração completa de ponta a ponta.

Perguntas Frequentes

Q: Eu preciso de um proxy para usar a API do CapSolver?
A: Não. Para a maioria dos tipos de tarefa, o CapSolver resolve o desafio em sua própria infraestrutura e você precisa apenas passar a URL de destino e a chave do site. A configuração de proxy é opcional e é necessária apenas para certos tipos de tarefa que precisam simular uma sessão de navegador a partir de um IP específico. Veja o guia de uso de proxy para detalhes.

Q: Quanto tempo leva para resolver um CAPTCHA?
A: O tempo de resolução varia conforme o tipo de desafio. A reCAPTCHA v3 normalmente é resolvida em menos de 5 segundos. A reCAPTCHA v2 e o Cloudflare Turnstile podem levar 10–30 segundos, dependendo da dificuldade do desafio e da carga da fila atual. O loop de polling neste guia lida automaticamente com tempos de resolução variáveis.

Q: O que acontece se meu saldo se esgotar durante a execução?
A: A API retornará um código de erro na próxima chamada para /createTask. O cliente deste guia lança um erro nesse caso, que você pode capturar e tratar — por exemplo, enviando um alerta ou pausando a tarefa. Adicionar uma verificação de saldo ao iniciar (como mostrado no guia) é a maneira mais simples de evitar isso.

Q: Posso usar este cliente em um navegador (JavaScript frontend)?
A: Não. Sua chave de API deve permanecer no lado do servidor. Exibi-la no código frontend permitiria que qualquer pessoa usasse seus créditos. Sempre chame a API do CapSolver a partir de um backend Node.js, função sem servidor ou outro ambiente do lado do servidor.

Q: O que devo fazer se uma tarefa retornar failed?
A: Um status failed normalmente significa que os parâmetros do desafio estavam incorretos (chave de site incorreta, tipo de tarefa incompatível ou uma configuração de página não suportada). Verifique o campo errorDescription na resposta, confirme seus parâmetros de tarefa contra a documentação do tipo de tarefa, e tente novamente com valores corrigidos. Você também pode verificar a FAQ do CapSolver para padrões comuns de erros.

P: Existe um SDK oficial para JavaScript/Node.js?
R: O CapSolver fornece SDKs oficiais para múltiplos idiomas. Para projetos JavaScript, você pode usar os padrões deste guia diretamente, ou verificar o GitHub do CapSolver por qualquer pacote npm publicado e exemplos de código.

Próximos Passos

Com esta implementação, você tem uma base sólida para adicionar capacidades de resolução de CAPTCHA aos seus projetos de automação JavaScript. Você pode estender este cliente com tipos de tarefa adicionais, integrá-lo com ferramentas de automação de navegador como Puppeteer ou Playwright, ou combiná-lo com um fluxo de raspagem com IA para pipelines de extração de dados mais avançados.

Para outros tipos de desafio e seus parâmetros específicos, consulte a documentação oficial dos tipos de tarefa.

Comece a resolver CAPTCHAs nos seus projetos JavaScript hoje com CapSolver—crie sua conta, obtenha sua chave de API e insira o código do cliente acima em seu próximo projeto de automação.