Migre uma integração reCAPTCHA do CapSolver para a solvethree

O solvethree usa reCAPTCHA v3 Enterprise por padrão e também aceita v3 padrão. Seus outros produtos públicos são Kasada e Ticketmaster TMPT. Ele não oferece suporte a reCAPTCHA v2, hCaptcha, Turnstile nem resolução por extensão de navegador, portanto não é um substituto universal para todas as integrações do CapSolver.

Antes de enviar uma tarefa de reCAPTCHA, configure o site de destino no console e verifique se há um perfil ativo disponível para o seu workspace. Enviar um hostname e uma ação não cria esse perfil. Não remova o campo websiteKey do CapSolver presumindo que o restante da requisição é suficiente.

A requisição inicial usa o clientKey do CapSolver e um envelope de tarefa específico do provedor:

{
  "clientKey": "CAPSOLVER_API_KEY",
  "task": {
    "type": "ReCaptchaV3Task",
    "websiteURL": "https://accounts.example.com/login",
    "websiteKey": "PUBLIC_SITE_KEY",
    "pageAction": "login",
    "isEnterprise": true,
    "proxy": "http://user:[email protected]:8080"
  }
}

Para o solvethree, envie o corpo sem aninhamento abaixo para POST https://api.solvethree.com/v1/tasks. Defina o cabeçalho Authorization como Bearer seguido da chave de API do seu workspace. Mantenha essa chave no servidor; não leve clientKey para o novo corpo JSON.

{
  "site": "accounts.example.com",
  "action": "login",
  "proxy": "http://user:[email protected]:8080",
  "requestId": "example_login_001"
}

O exemplo é uma requisição Enterprise porque mantém recaptchaType no valor padrão. Selecione v3 padrão explicitamente quando o destino usar essa versão; não converta todos os tipos de tarefa do CapSolver para o padrão Enterprise.

Uma tarefa ProxyLess do CapSolver não tem um equivalente direto sem proxy aqui: o solvethree exige que o chamador forneça um proxy. Se a sua integração atual não gerencia um proxy, isso é uma mudança na integração, não uma renomeação de campo. Também não copie uma configuração de proxy SOCKS para a nova requisição; o solvethree aceita URLs de proxy HTTP e HTTPS.

Comece com um único proxy para que a rota usada na resolução e no envio seja inequívoca. Se usar proxyCandidates em vez disso, forneça no máximo doze URLs distintas de proxy HTTP ou HTTPS, sem caminhos, queries ou fragmentos. Os candidatos permitem que o serviço tente rotas de saída alternativas; eles não garantem que um proxy ou destino funcionará.

O CapSolver consulta resultados assíncronos por meio de getTaskResult com clientKey e taskId. O solvethree os consulta por meio de GET /v1/tasks/:id com autenticação Bearer. Atualize tanto o parser do resultado quanto a chamada HTTP; os campos de status e erro do CapSolver pertencem a um contrato diferente.

1. 1.

   Verifique primeiro a resposta HTTP

   Trate respostas HTTP sem sucesso antes de ler um payload de sucesso. Um erro de requisição HTTP e uma tarefa de resolução com falha precisam de tratamentos separados.

2. 2.

   Inspecione a tarefa retornada na criação

   A criação de reCAPTCHA aguarda até 15 segundos por padrão, então a resposta já pode estar em um estado terminal. Apenas ready contém uma solução utilizável. Se a tarefa estiver em pending ou solving, consulte-a usando o ID de tarefa do solvethree retornado.

3. 3.

   Pare as consultas nos estados ready ou failed

   Para ready, passe a solução ao seu código de envio. Para failed, inspecione errorCode e error e pare de consultar essa tarefa. Resoluções que falham são reembolsadas. Não tente novamente às cegas com os mesmos dados de entrada inválidos nem presuma que toda falha significa crédito insuficiente.

Durante uma migração em etapas, mantenha cada ID de tarefa identificado com seu provedor. Conclua as tarefas existentes do CapSolver pelo CapSolver e encaminhe as novas tarefas do solvethree pelo solvethree. Normalize os resultados no seu adaptador em vez de enviar um ID de tarefa do provedor antigo para a nova API.

Use solution.token ao enviar o resultado do reCAPTCHA ao destino pretendido. Retenha também os valores retornados de userAgent e secChUa e use o proxy bem-sucedido no envio. Se o seu adaptador atual retorna apenas uma string de token, altere-o para levar essas informações até o cliente responsável pelo envio.

Se um token pronto for rejeitado, inspecione a requisição de saída da aplicação antes de pagar por outra resolução. Verifique se ela contém o novo token — não um ID de tarefa ou um token antigo — e se o envio usa a identidade de navegador retornada, o proxy bem-sucedido e a URL de destino pretendida. Uma tarefa ready significa que uma solução foi gerada, não que o destino aceitou sua requisição subsequente.

O exemplo após a migração inclui requestId para recuperação. Gere um para cada nova tarefa lógica e mantenha-o junto aos dados de entrada exatos da requisição. Ele deve conter de 1–64 letras ASCII, números, sublinhados ou hífens. Reutilizá-lo com a mesma requisição de tarefa retorna a tarefa existente; usá-lo com dados de entrada diferentes causa um conflito.

Se a criação atingir o timeout, consulte a tarefa caso tenha o ID dela ou reenvie o mesmo corpo com o mesmo requestId. Uma resposta perdida não prova que a criação falhou. Não gere um novo ID apenas porque seu cliente parou de esperar.

No timeout do seu cliente, considere a espera padrão de criação do reCAPTCHA de até 15 segundos mais a sobrecarga de rede. As consultas GET retornam sem esperar por padrão e aceitam waitMs de até 15000. Coloque waitMs na query da URL, não no JSON da tarefa, e considere essa espera também no timeout das consultas.