Como Conectar Rastreadores Lightpanda a uma API Solucionadora de CAPTCHA

Resumo

• O Lightpanda fornece o navegador headless; uma API de CAPTCHA separada fornece o resultado para um desafio compatível dentro de um fluxo autorizado.
• Conecte o Puppeteer ao endpoint CDP do Lightpanda e verifique a página real antes de montar uma requisição para o solucionador.
• Para reCAPTCHA v2, use a URL atual da página, a chave pública do site e quaisquer parâmetros adicionais documentados exigidos por esse desafio.
• Mantenha a página original aberta enquanto o solucionador é executado. Um token de resposta precisa chegar ao callback ou caminho de envio corretos da aplicação.
• Um teste de conexão ao navegador não prova compatibilidade com o script de CAPTCHA nem aceitação final pelo site. Valide isso separadamente na sua página de teste autorizada.

O Lightpanda é um navegador headless criado para automação, crawling, testes e agentes de navegador. Desenvolvedores o controlam por interfaces como o Chrome DevTools Protocol, comumente usando Puppeteer. Ele pode executar JavaScript da página e inspecionar o DOM, o que o torna útil quando uma resposta HTTP sozinha não contém as informações de que um fluxo precisa.

Um CAPTCHA é uma etapa separada. Carregar uma página pelo Lightpanda não significa que o desafio de verificação foi concluído. O CapSolver pode fornecer a API de solução documentada para um CAPTCHA compatível, enquanto sua aplicação continua responsável pelo estado da página e pelo resultado final.

Este guia conecta essas responsabilidades sem assumir que toda página de CAPTCHA se comporta como o Chromium. O exemplo executável verifica a conexão do navegador. A requisição ao solucionador e a aceitação pela aplicação exigem suas próprias credenciais e um desafio autorizado.

Entenda as duas conexões

Uma integração de CAPTCHA com o Lightpanda precisa de uma conexão com o navegador e outra, a partir do backend da aplicação, com a API do solucionador.

O repositório do Lightpanda mostra o Puppeteer conectando a um endpoint CDP. Navegação no navegador, inspeção de página e callbacks da aplicação permanecem desse lado do fluxo. A API de tarefas do CapSolver recebe as entradas específicas da tarefa e retorna uma resposta de tarefa.

Não aponte uma requisição para a API do solucionador para a porta CDP. Não envie uma URL de WebSocket do navegador como websiteURL, tampouco. Um endereço controla o processo do navegador; o outro identifica a página web que carrega o CAPTCHA.

Um contrato de API também define o limite do que a integração sabe. Um resultado de solucionador não é um comando que retoma automaticamente todos os navegadores. A aplicação precisa usar os campos retornados da forma que a sua página espera.

Instale e inicie o navegador

Instale o Lightpanda e o Puppeteer em uma pasta de projeto isolada antes de adicionar requisições pagas ao solucionador.

O exemplo de conexão usa Lightpanda 1.0.2, Puppeteer Core 25.16.0 e Node.js 24. Instale a dependência do Node com npm install --save-exact puppeteer-core@25.16.0. Baixe o binário para o seu sistema operacional e processador na release oficial 1.0.2, torne-o executável e confirme a versão com ./lightpanda version.

Inicie o servidor CDP local com ./lightpanda serve --host 127.0.0.1 --port 9227. Mantenha esse terminal em execução enquanto o cliente se conecta. A porta no exemplo a seguir deve corresponder à porta do servidor. Use um binding local para esta configuração de desenvolvimento.

Prepare uma página de teste permitida antes de prosseguir. A verificação inicial da conexão pode usar uma página simples que você possua; um teste posterior com CAPTCHA precisa de uma página com o desafio real e uma forma, do lado da aplicação, de observar a aceitação. Também prepare uma chave de API CapSolver válida e saldo antes de criar uma tarefa paga no solucionador.

Nenhuma solução paga é demonstrada neste guia. As etapas de verificação do navegador e uma resposta de autenticação da API estabelecem suas respectivas superfícies de conexão; elas não estabelecem sucesso na resolução do CAPTCHA nem compatibilidade com um site externo específico.

Verifique a conexão Puppeteer-para-Lightpanda

Defina AUTHORIZED_TEST_URL para sua página de teste, salve o código a seguir como lightpanda-connect.mjs e execute node lightpanda-connect.mjs.

O exemplo adapta o padrão oficial de conexão do Lightpanda com Puppeteer. Ele cria um contexto de navegador, carrega a página permitida, lê seu título e URL final e limpa o contexto e a conexão do cliente.

import puppeteer from 'puppeteer-core';

const target = process.env.AUTHORIZED_TEST_URL;
if (!target) throw new Error('Set AUTHORIZED_TEST_URL to your permitted test page');
const browser = await puppeteer.connect({
  browserWSEndpoint: 'ws://127.0.0.1:9227',
});
try {
  const context = await browser.createBrowserContext();
  try {
    const page = await context.newPage();
    await page.goto(target, { waitUntil: 'domcontentloaded' });
    console.log({ title: await page.title(), url: page.url() });
  } finally {
    await context.close();
  }
} finally {
  await browser.disconnect();
}

A saída deve identificar a página que foi realmente carregada. Se ela relatar uma página de erro, redirecionamento ou documento não relacionado, corrija isso antes de montar uma requisição de CAPTCHA. A execução bem-sucedida de JavaScript em uma página de teste simples é um ponto de partida útil, mas não mostra que todas as APIs de navegador de um widget real são compatíveis.

A referência de connect do Puppeteer descreve o anexo a um navegador existente. É por isso que o exemplo usa connect em vez de lançar um processo Chromium separado: o processo sob teste precisa continuar sendo o Lightpanda.

Prepare uma tarefa de CAPTCHA documentada

Monte a tarefa do solucionador a partir do desafio real carregado pelo navegador, mantendo suas entradas associadas a essa página.

Para o reCAPTCHA v2 padrão, comece pela referência oficial de tarefas v2. Uma requisição sem proxy usa ReCaptchaV2TaskProxyLess, websiteURL e websiteKey. Outros parâmetros observados pertencem a seus campos documentados; não os infira apenas da caixa de seleção visível.

O JSON a seguir ilustra o formato dessa requisição. Ele contém placeholders e não é um desafio ativo nem uma requisição paga executada. Substitua os valores a partir da sua própria página permitida e use a API oficial ou o exemplo de SDK linkado acima para enviá-lo.

{
  "clientKey": "YOUR_API_KEY",
  "task": {
    "type": "ReCaptchaV2TaskProxyLess",
    "websiteURL": "https://example.com/authorized-form",
    "websiteKey": "PUBLIC_SITE_KEY_FROM_THIS_PAGE"
  }
}

Mantenha clientKey no processo de backend. Ela não é uma chave de site do lado do navegador e não deve ser inserida na página. websiteURL deve descrever a página web que carrega o CAPTCHA, e não a URL do iframe do CAPTCHA nem o endpoint de controle do Lightpanda.

Se você não souber a versão ou parâmetros adicionais, use o fluxo documentado de detecção de parâmetros de CAPTCHA enquanto inspeciona a página permitida. Isso é uma etapa de preparação; não significa que uma extensão do Chrome possa ser carregada no Lightpanda.

Resgate Seu Código de Bônus CapSolver

Impulsione instantaneamente seu orçamento de automação!
Use o código de bônus CAP26 ao recarregar sua conta CapSolver para obter 5% de bônus extra em cada recarga — sem limites.
Resgate agora no seu Dashboard CapSolver

Recupere o resultado do solucionador sem substituir a página

Mantenha a página do Lightpanda e o estado da aplicação ativos enquanto a API de tarefas é concluída.

Para uma resposta assíncrona, retenha o ID da tarefa retornado por createTask e use getTaskResult para essa tarefa. Inspecione erros de API e o estado de processamento antes de ler a solução. O campo documentado de token de resposta do resultado v2 é gRecaptchaResponse.

Não crie um novo contexto de navegador apenas porque a requisição ao solucionador foi concluída. Um novo contexto é um ambiente de página diferente, e sua aplicação pode ter estado associado à operação original. Da mesma forma, não reutilize um resultado para outra página pendente apenas porque essa página exibe o mesmo tipo de widget.

O script acima, apenas de conexão, fecha o contexto deliberadamente. Ao integrar a execução do solucionador em uma aplicação real, coloque a operação do solucionador e a continuação específica da página dentro do tempo de vida do contexto, antes de essa limpeza ocorrer. Preserve a limpeza tanto em caso de erro quanto de sucesso.

Use a transferência de token controlada pela aplicação

Aplique o resultado por meio do callback ou caminho de envio definido pela sua própria aplicação. Não existe um nome de callback universal que funcione em todas as páginas. Não cole uma função presumida em uma integração e assuma que o formulário aceitou o valor.

Um adaptador mínimo do lado do navegador pode ser verificado primeiro em um fixture de sua propriedade com uma string inerte: verifique se o callback pretendido recebe essa string e se o campo relevante é alterado. Isso valida apenas o adaptador. Ele não deve enviar a string inerte como se fosse uma resposta de CAPTCHA válida.

O guia de verificação de resposta do reCAPTCHA do Google explica a etapa de verificação separada do lado da aplicação. Depois que um resultado genuíno do solucionador é repassado de volta, verifique o resultado da aplicação para a mesma tentativa. Um campo preenchido ou um callback concluído, por si só, é evidência insuficiente.

Diagnostique falhas pelo componente que falhou

Separe carregamento do navegador, execução do solucionador e aceitação pela aplicação para que novas tentativas resolvam o problema real.

O Puppeteer não consegue se conectar

Confirme que o processo do Lightpanda ainda está em execução e que host e porta correspondem. Verifique as versões fixadas do cliente e do navegador antes de supor que um script funcionando no Chromium é compatível com a build atual do Lightpanda.

A página carrega, mas o widget de CAPTCHA não

Inspecione erros de script da página e as requisições de rede do widget. Uma API de solucionador não pode corrigir um recurso do engine de navegador exigido pela página. Prove que a página autorizada carrega o desafio esperado antes de prosseguir com uma tarefa paga.

A API de tarefas rejeita a requisição

Leia a resposta de erro documentada e verifique a chave, o tipo de tarefa, URL, chave de site e campos condicionais. Um erro de autenticação comprova que a API respondeu; ele não estabelece uma integração de solucionador bem-sucedida. Não envie repetidamente a mesma entrada inválida.

O solucionador retorna um token, mas a aplicação o rejeita

Verifique a propriedade da página, a transferência do token, o comportamento do callback e a verificação do lado do servidor. Registre o ID da tarefa e o motivo de falha redigido. Evite registrar chaves de API ou tokens de resposta brutos em saídas de build compartilhadas.

O fluxo funciona apenas no fixture

Trate o fixture como um teste de adaptador. Execute o fluxo real de CAPTCHA permitido antes de confiar na integração. Comportamento do navegador, scripts do widget e validação da aplicação são condições adicionais, e nenhuma delas decorre automaticamente de um handshake CDP bem-sucedido.

Decida se esta integração se encaixa no seu crawler

Lightpanda mais uma API de solucionador externa é relevante quando um crawler já usa Lightpanda, encontra um CAPTCHA compatível durante uma tarefa autorizada e possui uma forma verificada de continuar na mesma página. Não é um motivo para adicionar um solucionador a páginas sem CAPTCHA nem para reivindicar compatibilidade universal de navegador.

Comece com a conexão real do navegador, verifique o schema da tarefa e teste um fluxo de aplicação permitido antes de adicionar concorrência. Mantenha cada resultado associado à sua página requisitante e meça o resultado real da aplicação.

Construa fluxos de automação confiáveis com o CapSolver

Use o solucionador em um checkpoint de CAPTCHA verificado e, em seguida, confirme o resultado da aplicação. O CapSolver fornece a interface de solucionador documentada para essa etapa. Experimente o CapSolver com um fluxo de teste permitido antes de estender a integração.

Perguntas frequentes

P: Isso instala um solucionador de CAPTCHA dentro do Lightpanda?

Não. A aplicação se comunica com o Lightpanda via CDP e chama a API externa do solucionador separadamente. Ela então precisa aplicar o resultado por meio do fluxo esperado da aplicação autorizada.

P: Posso carregar a extensão do Chrome do CapSolver neste navegador?

Este tutorial não estabelece suporte a extensões do Chrome no Lightpanda. Ele usa a API externa de tarefas. A inspeção de parâmetros em um ambiente Chrome compatível é uma etapa de preparação separada.

P: A conexão do Puppeteer prova que o reCAPTCHA funciona no Lightpanda?

Não. Ela prova que o cliente consegue se conectar e executar as operações de navegador demonstradas. Os scripts reais de CAPTCHA e a aceitação pela aplicação precisam de seus próprios testes.

P: Qual tipo de reCAPTCHA o exemplo JSON usa?

Ele ilustra o reCAPTCHA v2 padrão com ReCaptchaV2TaskProxyLess. Enterprise, v3 e outras famílias de desafios precisam de seus próprios tipos de tarefa e entradas documentados.

P: Alguma solução de CAPTCHA paga foi concluída pelo código de exemplo?

Não. O exemplo executável verifica a conexão do navegador, enquanto o JSON explica o formato da tarefa com placeholders. Uma conta de solucionador válida e um desafio ativo autorizado são necessários para testar a solução e a aceitação final.