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:
Prepare um objeto de tarefa com o type correto e parâmetros do CAPTCHA (por exemplo, RecaptchaV3TaskProxyless mais websiteURL, websiteKey, minScore e pageAction).
Call o método createTask em https://api.capmonster.cloud/createTask com seu clientKey e o objeto task.
- 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 é:
- Usar ambientes de desenvolvimento local ou staging conectados à página de teste lessons.zennolab.com para verificar seu fluxo de solução de CAPTCHA.
- 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:
- Chamar createTask e depois getTaskResult a partir do seu serviço de backend.
- Injetar gRecaptchaResponse na textarea oculta na página de destino.
- 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/CapMonsterCloud/capmonstercloud-client-js
import { CapMonsterCloudClientFactory, ClientOptions, RecaptchaV3ProxylessRequest } from '@zennolab_com/capmonstercloud-client';
const API_KEY = "YOUR_API_KEY"; // Insira sua chave de API do CapMonster Cloud
async function solveRecaptchaV3() {
const cmcClient = CapMonsterCloudClientFactory.Create(
new ClientOptions({ clientKey: API_KEY })
);
// Se necessário, você pode verificar o saldo
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 da sua página com a captcha
websiteKey: "6Le0xVgUAAAAAIt20XEB4rVhYOODgTl00d8juDob",
minScore: 0.6,
pageAction: "myverify",
});
const solution = await cmcClient.Solve(recaptchaV3Request);
console.log("Solution:", solution);
}
solveRecaptchaV3().catch(console.error);
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/CapMonsterCloud/capmonstercloud-client-python
import asyncio
from capmonstercloudclient import CapMonsterClient, ClientOptions
from capmonstercloudclient.requests import RecaptchaV3ProxylessRequest
client_options = ClientOptions(api_key="YOUR_API_KEY") # Insira sua chave de API do CapMonster Cloud
cap_monster_client = CapMonsterClient(options=client_options)
# Se necessário, você pode verificar o saldo
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 da sua página com 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/CapMonsterCloud/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" // Insira sua chave de API do CapMonster Cloud
};
var cmCloudClient = CapMonsterCloudClientFactory.Create(clientOptions);
// Se necessário, você pode verificar o saldo
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 da sua página com 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.
