Use o APIRequestContext do Playwright com uma solução de CAPTCHA

1. 1.

   Instale as dependências

   Use Node.js 22+ e instale o pacote playwright. Instale o SDK oficial de JavaScript a partir do arquivo tarball da versão 0.1.0 do solvethree: solvethree-sdk-0.1.0.tgz, em /downloads/ no solvethree.com. Ele é importado como @solvethree/sdk; não presuma que haja uma versão disponível no registro.

2. 2.

   Defina as variáveis de ambiente

   Forneça SOLVETHREE_API_KEY, SOLVETHREE_PROXY e TARGET_URL ao processo do Node.js. Mantenha a chave de API do espaço de trabalho no lado do servidor. TARGET_URL deve ser o endpoint POST real da aplicação, não apenas a página que exibe o CAPTCHA. Use uma URL de proxy HTTP ou HTTPS sem caminho, consulta ou fragmento.

3. 3.

   Confirme o perfil do site e a ação

   O nome de host de destino precisa ter um perfil ativo disponível para o seu espaço de trabalho. Configure-o no console antes de resolver o CAPTCHA; passar um nome de host não cria um perfil. O exemplo usa a ação login; altere-a se o destino esperar outra ação. A requisição usa reCAPTCHA Enterprise v3 por padrão.

Tenha em mãos os campos de formulário obrigatórios e os requisitos de sessão da aplicação antes de executar o exemplo. Ele envia apenas o campo de resposta do CAPTCHA. Consulte a configuração do perfil do site se o nome de host ainda não estiver configurado.

import { request } from 'playwright';
import { Solvethree } from '@solvethree/sdk';
const client = new Solvethree({ apiKey: process.env.SOLVETHREE_API_KEY });
const target = new URL(process.env.TARGET_URL);
const proxy = new URL(process.env.SOLVETHREE_PROXY);
const result = await client.solve({ site: target.hostname, action: 'login', proxy: process.env.SOLVETHREE_PROXY });
const proxyConfig = { server: `${proxy.protocol}//${proxy.host}`, username: decodeURIComponent(proxy.username), password: decodeURIComponent(proxy.password) };

const targetClient = await request.newContext({
  proxy: proxyConfig, timeout: 30000,
  extraHTTPHeaders: { 'User-Agent': result.solution.userAgent, 'sec-ch-ua': result.solution.secChUa },
  // storageState: 'your-application-session.json', // only if your flow needs it
});
try {
  const response = await targetClient.post(target.href, {
    form: { 'g-recaptcha-response': result.solution.token }, maxRedirects: 0,
  });
  console.log('Application HTTP status:', response.status());
  // Inspect the response and supply the application's actual fields/CSRF/session.
} finally { await targetClient.dispose(); }

client.solve() cria a tarefa uma única vez e consulta seu status até que ela esteja pronta ou lança uma exceção. O exemplo usa um único proxy tanto para a resolução quanto para o envio. Para o Playwright, ele separa o endereço do servidor proxy das credenciais e decodifica o nome de usuário e a senha.

O contexto de requisição aplica solution.userAgent e solution.secChUa como cabeçalhos. O formulário envia solution.token em g-recaptcha-response, não o ID da tarefa. Mantenha o proxy e a identidade retornada juntos; não os substitua por cabeçalhos de navegador sem relação com eles nem envie o token para outro destino.

Adicione ao formulário os campos reais da aplicação, incluindo credenciais ou dados CSRF quando necessário. Se você já tiver a sessão exigida pela aplicação, habilite a configuração opcional storageState e aponte-a para o estado salvo dessa sessão.

O APIRequestContext mantém seu próprio armazenamento de cookies, portanto as requisições feitas pelo mesmo contexto preservam os cookies recebidos. Ele não compartilha cookies automaticamente com um contexto de navegador independente. Mantenha as requisições prévias de sessão e o POST final no mesmo contexto quando precisarem compartilhar cookies. O bloco finally libera os recursos do contexto quando o envio termina.

O exemplo registra o status HTTP da aplicação; isso não comprova que o login foi bem-sucedido. Com maxRedirects definido como zero, você vê a resposta inicial em vez de seguir um redirecionamento. Compare o corpo, os cabeçalhos e os cookies com a resposta de sucesso esperada pela aplicação. Um redirecionamento ou HTTP 200, por si só, pode não indicar se a operação foi bem-sucedida.

A tarefa está pronta, mas a aplicação rejeita o POST.

Primeiro, inspecione a requisição de saída: campo do token, nome de host e ação, proxy, identidade retornada, campos de formulário obrigatórios, valor CSRF e cookies de sessão.

Experimente: Corrija os dados ausentes ou incompatíveis da requisição antes de pagar por outra resolução. Uma tarefa pronta fornece uma solução utilizável, não uma garantia de aceitação pela aplicação de destino.

A resolução termina com uma tarefa com falha.

Leia errorCode e error; não trate toda falha como um problema de créditos.

Experimente: Pare de consultar essa tarefa e corrija a causa informada. Resoluções com falha são reembolsadas. Para interpretar os erros, consulte tratamento de erros da API.

A criação da tarefa excede o tempo limite ou a conexão cai.

Verifique se você tem um ID de tarefa ou usou um requestId. Um tempo limite de conexão não comprova que a criação falhou.

Experimente: Recupere a tarefa existente quando tiver o ID dela. Para requisições de criação recuperáveis, forneça um requestId e reutilize-o com exatamente os mesmos dados de entrada; isso retorna a tarefa existente. Não inicie imediatamente outra resolução lógica.

A requisição à aplicação retorna um erro HTTP.

Inspecione a resposta do destino separadamente do resultado da tarefa do solvethree.

Experimente: Trate a resposta que não indica sucesso antes de considerar seu corpo como um payload de sucesso. Corrija a requisição à aplicação ou o erro de servidor informado, em vez de presumir que o token foi a causa.