Leitor de CAPTCHA – Serviço de resolução de CAPTCHA com IA e acesso via API

Um leitor de CAPTCHA confiável é essencial quando você precisa automatizar fluxos protegidos por desafios como Google reCAPTCHA, Cloudflare Turnstile/Challenge e outros, sem quebrar sua arquitetura ou a UX. CapMonster Cloud oferece um serviço de resolução de CAPTCHA com IA, com uma API HTTP limpa e SDKs oficiais que permitem integrar soluções de CAPTCHA diretamente nos seus aplicativos, bots e serviços de backend.

Este guia orienta você a usar o CapMonster Cloud como um leitor de CAPTCHA usando o Google reCAPTCHA v3 como exemplo: o fluxo principal da API, integração de demo/sandbox e exemplos completos de código retirados diretamente da documentação oficial, incluindo requisições JSON e uso de SDK. Ao final, você saberá como conectar esse serviço de CAPTCHA ao seu próprio app de CAPTCHA, bot de CAPTCHA ou stack de automação.

1. Como o CapMonster Cloud funciona como leitor de CAPTCHA

O CapMonster Cloud atua como um solucionador de CAPTCHA baseado em nuvem: você envia uma descrição da tarefa de CAPTCHA (URL do site, chaves e opções), o serviço resolve do lado dele e então retorna um token ou uma resposta em texto que você pode enviar ao site de destino. A plataforma suporta tipos comuns de CAPTCHA, como Google reCAPTCHA v2 e v3 (incluindo versões Enterprise), além de tarefas genéricas baseadas em imagem via ImageToTextTask e outros tipos de tarefa documentados na API.

Cada requisição que você envia define um objeto task que descreve o CAPTCHA a resolver e um objeto solution que você recebe mais tarde, como um token gRecaptchaResponse . Para o reCAPTCHA v3 especificamente, os tipos de tarefa RecaptchaV3TaskProxyless e RecaptchaV3EnterpriseTask usam a própria infraestrutura de proxy do CapMonster Cloud, então você não precisa gerenciar proxies por conta própria ao integrar esse solucionador de CAPTCHA aos seus fluxos.

Papéis importantes que o CapMonster Cloud pode desempenhar no seu stack incluem:

• Como um backend de solução de CAPTCHA para suas ferramentas de scraping e test harnesses.

• Como uma etapa de remoção de CAPTCHA dentro de fluxos de automação (por exemplo, login ou envio de formulário).

• Como um módulo de serviço de CAPTCHA reutilizável compartilhado entre vários microsserviços.

2. Fluxo principal da API do CapMonster Cloud

A API HTTP do CapMonster Cloud é organizada em torno de um padrão simples: criar uma tarefa e depois consultar (poll) o resultado. Todas as requisições usam JSON via POST e incluem seu clientKey, a chave de API exclusiva da sua conta do CapMonster Cloud.

Em alto nível, um fluxo típico de resolução de CAPTCHA se parece com isto:

1. Prepare um objeto de tarefa com o type correto e parâmetros do CAPTCHA (por exemplo, RecaptchaV3TaskProxyless mais websiteURL, websiteKey, minScore e pageAction).

2. Call o método createTask em https://api.CapMonster.cloud/createTask com seu clientKey e o objeto task.

3. Poll https://api.CapMonster.cloud/getTaskResult com o taskId retornado até que o status se torne ready e então leia a solução (por exemplo, gRecaptchaResponse).

3. Primeiros passos: conta, chaves, sandbox e demo de CAPTCHA

Para usar o CapMonster Cloud como leitor de CAPTCHA, primeiro você obtém um clientKey (chave de API) da sua conta, que depois você envia em cada chamada de API no campo clientKey .

Para desenvolvimento e testes com segurança, o CapMonster fornece páginas de demo dedicadas, como https://lessons.zennolab.com/captchas/recaptcha/v3.php?level=beta para reCAPTCHA v3  ou https://capmonster.cloud/en/demo/recaptcha-v2 para reCAPTCHA v2. Esses endpoints de demo funcionam como um sandbox onde você pode integrar e depurar sua lógica de resolução de CAPTCHA online sem tocar em sistemas de produção, tornando-o um alvo ideal para demo de CAPTCHA.

Um padrão de configuração recomendado é:

1. Usar ambientes de desenvolvimento local ou staging conectados à página de teste lessons.zennolab.com para verificar seu fluxo de solução de CAPTCHA.
2. Quando estiver estável, trocar websiteURL e websiteKey para corresponder às páginas reais do seu aplicativo, mantendo os mesmos padrões de integração da API do CapMonster Cloud.

Essa abordagem permite que você integre seu leitor de CAPTCHA com segurança antes de migrar para tráfego de produção.

4. Solução de CAPTCHA via API do reCAPTCHA v3 (demo)

O tipo de tarefa do reCAPTCHA v3 RecaptchaV3TaskProxyless é um bom exemplo de como transformar o CapMonster Cloud em um leitor de CAPTCHA pronto para produção para desafios invisíveis. A documentação explica que o reCAPTCHA v3 roda em segundo plano, avalia o comportamento do usuário e retorna uma pontuação de 0.1 a 0.9; seu bot ou app de CAPTCHA precisa definir minScore e pageAction de forma adequada ao criar as tarefas.

4.1. Criar uma tarefa RecaptchaV3TaskProxyless

Para o reCAPTCHA v3, a createTask request para uma página de demo se parece com isto:

{
 "clientKey": "API_KEY",
 "task": {
   "type": "RecaptchaV3TaskProxyless",
   "websiteURL": "https://lessons.zennolab.com/captchas/recaptcha/v3.php?level=beta",
   "websiteKey": "6Le0xVgUAAAAAIt20XEB4rVhYOODgTl00d8juDob",
   "minScore": 0.3,
   "pageAction": "myverify"
 }
}

Aqui

• websiteURL aponta para a página sandbox do reCAPTCHA v3 em lessons.zennolab.com.
• websiteKey é a site key pública do ReCaptcha extraída dos scripts da página.
• minScore especifica a pontuação mínima de confiança aceitável para a solução, de 0.1 a 0.9.
• pageAction reflete a string de ação passada para grecaptcha.execute, como 'login_test' ou o "myverify" usado neste exemplo.

Seu backend ou wrapper do serviço de CAPTCHA enviaria este JSON via POST para https://api.CapMonster.cloud/createTask e então leria o taskId retornado se errorId for 0.

4.2. Consultar (poll) getTaskResult para a solução do CAPTCHA

Depois que a tarefa é criada, você recupera a solução do CAPTCHA usando o método getTaskResult .

Request

{ 
 "clientKey":"API_KEY", 
 "taskId": 407533072 
}

Response

{ 
 "errorId":0, 
 "status":"ready", 
 "solution": { 
   "gRecaptchaResponse":"3AHJ_VuvYIBNBW5yyv0zRYJ75VkOKvhKj9_xGBJKnQimF72rfoq3Iy-DyGHMwLAo6a3" 
 } 
}

O campo `solution.gRecaptchaResponse` é uma string de token que deve ser inserida no campo do formulário do reCAPTCHA v3 `<textarea ></textarea>`. A documentação observa que esse é o valor retornado ao resolver o CAPTCHA e é o que transforma sua chamada de API em uma resolução completa do CAPTCHA no navegador ou no cliente HTTP. 

Em um cenário de automação baseada em navegador, seu bot de CAPTCHA poderia:

1. Chamar createTask e depois getTaskResult a partir do seu serviço de backend.
2. Injetar gRecaptchaResponse na textarea oculta na página de destino.
3. Enviar o formulário, efetivamente usando o CapMonster Cloud como uma etapa de remoção de CAPTCHA entre a renderização da página e o envio do formulário.

Juntas, essas etapas implementam um pipeline completo de solução de CAPTCHA para o reCAPTCHA v3.

5. Criando um app de CAPTCHA ou bot de CAPTCHA com SDKs

O CapMonster Cloud fornece bibliotecas de SDK oficiais que encapsulam a API HTTP e facilitam a criação de um app de CAPTCHA, um serviço interno de CAPTCHA ou um bot de CAPTCHA maior sem ter que montar manualmente cada requisição JSON. A página de documentação do reCAPTCHA v3 inclui exemplos prontos para uso para JavaScript, Python e .NET.

5.1. Exemplo do SDK JavaScript

// https://github.com/ZennoLab/CapMonstercloud-client-js
import {
 CapMonsterCloudClientFactory,
 ClientOptions,
 RecaptchaV3ProxylessRequest
} from '@zennolab_com/CapMonstercloud-client';
document.addEventListener('DOMContentLoaded', async () => {
 const cmcClient = CapMonsterCloudClientFactory.Create(
   new ClientOptions({ clientKey: 'YOUR_API_KEY' }) // Specify your CapMonster Cloud API key
 );
 // Optionally, you can check the balance
 const balance = await cmcClient.getBalance();
 console.log('Balance:', balance);
 const recaptchaV3Request = new RecaptchaV3ProxylessRequest({
   websiteURL: 'https://lessons.zennolab.com/captchas/recaptcha/v3.php?level=beta', // URL of your page with captcha
   websiteKey: '6Le0xVgUAAAAAIt20XEB4rVhYOODgTl00d8juDob',
   minScore: 0.6,  
   pageAction: 'myverify',
 });
 const solution = await cmcClient.Solve(recaptchaV3Request);
 console.log('Solution:', solution);
});

Este exemplo mostra como:

• Inicializar o cliente com clientKey.
• Opcionalmente chamar getBalance() para verificar os fundos da conta.
• Construir um RecaptchaV3ProxylessRequest com a URL e a chave do site de demo.
• Chamar Solve para resolver um CAPTCHA e registrar a solução.

Você pode adaptar esse padrão em extensões de navegador, scripts Node.js ou controladores de automação web ao criar seu leitor de CAPTCHA.

5.2. Exemplo do SDK Python

# https://github.com/Zennolab/CapMonstercloud-client-python
import asyncio
from CapMonstercloudclient import CapMonsterClient, ClientOptions
from CapMonstercloudclient.requests import RecaptchaV3ProxylessRequest
client_options = ClientOptions(api_key="YOUR_API_KEY")  # Specify your CapMonster Cloud API key
cap_monster_client = CapMonsterClient(options=client_options)
# Optionally, you can check the balance
balance = asyncio.run(cap_monster_client.get_balance())
print("Balance:", balance)
recaptcha_v3_request = RecaptchaV3ProxylessRequest(
   websiteUrl="https://lessons.zennolab.com/captchas/recaptcha/v3.php?level=beta",  # URL of your page with captcha
   websiteKey="6Le0xVgUAAAAAIt20XEB4rVhYOODgTl00d8juDob",
   minScore=0.6,
   pageAction="myverify"
)
async def solve_captcha():
   return await cap_monster_client.solve_captcha(recaptcha_v3_request)
responses = asyncio.run(solve_captcha())
print(responses)

Este trecho demonstra uma chamada assíncrona solve_captcha com o mesmo websiteUrl e websiteKey que você viu no exemplo de JSON bruto, fornecendo uma resolução completa de CAPTCHA por meio de uma simples chamada de método.

5.3. Exemplo do SDK .NET

// https://github.com/ZennoLab/CapMonstercloud-client-dotnet
using Zennolab.CapMonsterCloud.Requests;
using Zennolab.CapMonsterCloud;
class Program
{
   static async Task Main(string[] args)
   {
       var clientOptions = new ClientOptions
       {
           ClientKey = "YOUR_API_KEY"  // Specify your CapMonster Cloud API key
       };
       var cmCloudClient = CapMonsterCloudClientFactory.Create(clientOptions);
       // Optionally, you can check the balance
       var balance = await cmCloudClient.GetBalanceAsync();
       Console.WriteLine("Balance: " + balance);
       var recaptchaV3Request = new RecaptchaV3ProxylessRequest
       {
           WebsiteUrl = "https://lessons.zennolab.com/captchas/recaptcha/v3.php?level=beta",  // URL of your page with captcha
           WebsiteKey = "6Le0xVgUAAAAAIt20XEB4rVhYOODgTl00d8juDob",
           MinScore = 0.6,
           PageAction = "myverify"
       };
       var recaptchaV3Result = await cmCloudClient.SolveAsync(recaptchaV3Request);
       Console.WriteLine("Solution: " + recaptchaV3Result.Solution.Value);
   }
}

Aqui, SolveAsync oculta as chamadas de baixo nível createTask e getTaskResult , retornando um objeto de resultado tipado com o valor da solução pronto para ser injetado na página de destino ou na requisição HTTP. Você pode incorporar isso em uma ferramenta de console, microsserviço ou app de CAPTCHA maior que centraliza a lógica de resolução de CAPTCHA para múltiplos sistemas.

6. Tratamento de erros, tokens inválidos e aceitação de tokens

A createTask documentação descreve o modelo padrão de erro que você integrará ao seu leitor de CAPTCHA ou wrapper de serviço de CAPTCHA. Cada resposta inclui um errorId, onde 0 significa sucesso e um valor diferente de zero indica um erro com errorCode e errorDescription.

O método de API createTask inclui este exemplo de resposta de erro:

{
  "errorId": 1,
  "errorCode": "ERROR_KEY_DOES_NOT_EXIST",
  "errorDescription": "Account authorization key not found in the system or has incorrect format",
  "taskId": 0
}

Uma implementação robusta de resolução de CAPTCHA deve:

• Verificar errorId após cada chamada createTask e tratar casos como chaves de API inválidas ou tarefas malformadas.
• Tratar timeouts de rede ou problemas temporários do serviço repetindo a tentativa com backoff quando apropriado.
• Ao consultar (poll) o getTaskResult, continuar até receber um status final (ready ou um erro) e registrar tokens rejeitados ou padrões incomuns para análise posterior.

Trate qualquer rejeição do gRecaptchaResponse pelo site de destino como um sinal para registrar o contexto (URL, ação, pontuação, corpo da resposta), para que você possa ajustar minScore, verificar se seu websiteKey e pageAction estão corretos, ou revalidar se você está usando o tipo de CAPTCHA certo para aquele endpoint.

7. Checklist de implementação para seu leitor de CAPTCHA

Quando você cria seu próprio leitor de CAPTCHA, lógica de extensão de CAPTCHA ou bot de CAPTCHA em torno do CapMonster Cloud, este checklist ajudará a manter tudo consistente com a documentação oficial:

1. Cadastre-se em CapMonster Cloud 

   E obtenha seu clientKey.

2. Identifique o tipo de CAPTCHA

   Confirme que a página usa reCAPTCHA v3 e não outra variante (por exemplo, reCAPTCHA v2) e escolha RecaptchaV3TaskProxyless de acordo.

3. Extraia os parâmetros necessários

   Na página, obtenha websiteKey e o pageAction associado ao grecaptcha.execute, como descrito na documentação do reCAPTCHA v3.

4. Escolha o tipo de tarefa correto

   Use RecaptchaV3TaskProxyless para reCAPTCHA v3, RecaptchaV2Task para o exemplo de v2, ou outros tipos de tarefa como ImageToTextTask ao resolver CAPTCHAs de imagem.

5. Implemente createTask

   Envie um JSON via POST para https://api.CapMonster.cloud/createTask com seu clientKey e o objeto task preenchido corretamente.

6. Implemente o polling do getTaskResult

   De forma periódica, chame https://api.CapMonster.cloud/getTaskResult com o taskId retornado até ver status":"ready" e então leia a solution (por exemplo, gRecaptchaResponse).

7. Injete a solução do CAPTCHA

   Para reCAPTCHA v3, coloque  `solution.gRecaptchaResponse`  em `<textarea id="g-recaptcha-response"></textarea>` antes de enviar o formulário.

8. Valide em sandbox/demo

   Teste seu fluxo completo na página de demo https://lessons.zennolab.com/captchas/recaptcha/v3.php?level=beta antes de direcionar para seu próprio site ou páginas de produção.

9. Monitore e refine

   Registre erros e tokens rejeitados, ajuste minScore e pageAction se necessário e mantenha sua implementação alinhada com a documentação mais recente do CapMonster Cloud.

Esse processo fornece uma forma estruturada e repetível de implementar uma etapa de resolução de CAPTCHA — seja para criar um app de CAPTCHA independente, integrar à automação existente ou expor um serviço de CAPTCHA compartilhado internamente.

Conclusão

CapMonster Cloud fornece um leitor de CAPTCHA robusto, com IA, que você pode integrar aos seus fluxos de web scraping, automação ou testes por meio de chamadas limpas à API HTTP ou SDKs oficiais. Ao seguir os padrões bem documentados de createTask e getTaskResult — e usando as páginas de demo fornecidas para validação inicial — você pode criar soluções confiáveis de CAPTCHA sem reinventar a roda.

Crie uma conta em CapMonster Cloud hoje e veja como a resolução automatizada de CAPTCHA pode ser simples. Visite a documentação oficial em docs.CapMonster.cloud para as referências mais recentes da API, tipos de tarefa e exemplos de integração.

NB: Observe que o produto é destinado à automação de testes em seus próprios sites e em sites aos quais você tem acesso legal.