CapMonster Cloud API
Extensão para navegadores
Neste artigo, procuramos responder a todas as principais dúvidas. Para começar a resolver o problema, o primeiro passo é identificar qual sistema de proteção está sendo utilizado. Para isso, você pode consultar a lista de captchas e sistemas de proteção antibot mais populares, onde há exemplos visuais e sinais principais que ajudam a identificar rapidamente com o que você está lidando.
Se você notar que o seu site utiliza reCAPTCHA v2 Enterprise, o passo seguinte é estudar com mais detalhes as suas características e o seu funcionamento. Neste mesmo artigo, você também pode conferir o guia de integração do reCAPTCHA v2 Enterprise, para entender por completo como o sistema opera no seu site. Isso permitirá não apenas compreender a proteção atual, mas também planejar adequadamente a sua manutenção.
Ao testar formulários com reCAPTCHA v2 Enterprise, é comum precisar confirmar se a captcha está funcionando e integrada corretamente.
Você pode testar manualmente a captcha incorporada no site.
Para resolver automaticamente use ferramentas como o CapMonster Cloud, que recebe os parâmetros da captcha, processa em seus servidores e devolve um token pronto. Basta inseri-lo no formulário para passar na verificação sem interação humana.
Trabalhar com o CapMonster Cloud via API normalmente envolve as etapas abaixo:
Criação da tarefa
Envio da requisição APISua requisição deve incluir:
type - RecaptchaV2EnterpriseTask;
websiteURL - URL da página onde a captcha aparece;
websiteKey - sitekey exibido na página;
enterprisePayload - informe caso o widget reCAPTCHA Enterprise envie um campo s adicional no objeto passado ao grecaptcha.enterprise.render junto com o sitekey;
pageAction - valor action enviado pelo widget para o Google (padrão: verify).
https://api.capmonster.cloud/createTask{
"clientKey": "API_KEY",
"task": {
"type": "RecaptchaV2EnterpriseTask",
"websiteURL": "https://mydomain.com/page-with-recaptcha-enterprise",
"websiteKey": "6Lcg7CMUAAAAANphynKgn9YAgA4tQ2KI_iqRyTwd",
"pageAction": "verify",
"enterprisePayload": {
"s": "SOME_ADDITIONAL_TOKEN"
}
}
}
{
"errorId":0,
"taskId":407533072
}
Recebimento do resultadohttps://api.capmonster.cloud/getTaskResult{
"clientKey":"API_KEY",
"taskId": 407533072
}
{
"errorId": 0,
"status": "ready",
"solution": {
"gRecaptchaResponse": "03AFcWeA66ZARdA5te7acD9vSwWE2hEQ2-B2aqFxm455iMA-g-Jis..."
}
}
Aplicação do token na páginaimport { chromium } from 'playwright';
import { CapMonsterCloudClientFactory, ClientOptions, RecaptchaV2EnterpriseRequest } from '@zennolab_com/capmonstercloud-client';
(async () => {
const browser = await chromium.launch({ headless: false });
const context = await browser.newContext();
const page = await context.newPage();
// 2. Abra a página com a captcha
await page.goto('https://example.com');
// 3. Crie o cliente CapMonster Cloud
const cmcClient = CapMonsterCloudClientFactory.Create(
new ClientOptions({ clientKey: '<your_capmonster_cloud_api_key>' })
);
// 4. Configure a requisição para resolver a captcha
const recaptchaRequest = new RecaptchaV2EnterpriseRequest({
websiteURL: page.url(),
websiteKey: '6Lf76sUnAAAAAIKLuWNyegRsFUfmI-3Lex3xT5N'
// enterprisePayload: { s: 'SOME_ADDITIONAL_TOKEN' } // Parâmetro enterprise opcional
});
// 5. Resolva a captcha usando CapMonster
const solution = await cmcClient.Solve(recaptchaRequest);
const token = solution.solution.gRecaptchaResponse;
console.log('Token do captcha:', token);
// 6. Insira o token em um campo oculto
await page.evaluate((t) => {
const el = document.getElementById('g-recaptcha-response');
if (el) el.value = t;
}, token);
// 7. (Opcional) Envie o formulário — ajuste o seletor
await page.click('button[data-action="submit"]');
await page.waitForTimeout(5000);
await browser.close();
})();Como o reCAPTCHA Enterprise roda no Google Cloud, você precisa primeiro criar um projeto no console:
1. Acesse o Google Cloud Console.
2. No menu superior, escolha um projeto existente ou clique em Novo projeto.
3. Digite um nome para o projeto, informe sua organização e confirme a criação.
4. Abra a página da API: reCAPTCHA Enterprise API e clique em Ativar.
5. No console, vá até Criar chave e clique em Criar chave.
6. Configure as configurações básicas:
Depois, abra as Configurações adicionais, ative Você usará desafios? e habilite Checkbox Challenge.
7. Clique em Criar. Você receberá uma chave que precisa ser adicionada ao seu site para ativar a proteção.
8. Adicione o script à sua página.
Exemplo de trecho HTML que você pode incorporar no seu site<html>
<head>
<title>reCAPTCHA demo: Simple page</title>
<script src="https://www.google.com/recaptcha/enterprise.js" async defer></script>
</head>
<body>
<form action="" method="POST">
<div class="g-recaptcha" data-sitekey="YOUR_SITEKEY" data-action="LOGIN"></div>
<br/>
<input type="submit" value="Submit">
</form>
</body>
</html>9. Valide a resposta no servidor.
Exemplo em PHPO token (g-recaptcha-response) é enviado para o backend.
Ele é válido por 2 minutos, então faça a verificação assim que recebê-lo! Para uma comunicação segura com a API recomendamos as bibliotecas oficiais do Google Cloud:
<?php
require 'vendor/autoload.php';
// Instale as bibliotecas do Google Cloud via Composer
use Google/Cloud/RecaptchaEnterprise/V1/RecaptchaEnterpriseServiceClient;
use Google/Cloud/RecaptchaEnterprise/V1/Event;
use Google/Cloud/RecaptchaEnterprise/V1/Assessment;
use Google/Cloud/RecaptchaEnterprise/V1/CreateAssessmentRequest;
use Google/Cloud/RecaptchaEnterprise/V1/TokenProperties/InvalidReason;
/**
* Valide o token do reCAPTCHA Enterprise e obtenha a pontuação de risco.
*
* @param string $recaptchaKey Chave reCAPTCHA do seu site/aplicativo
* @param string $token Token recebido do cliente
* @param string $projectId ID do projeto do Google Cloud
* @param string $action Nome da ação associada ao token
*/
function create_assessment(string $recaptchaKey, string $token, string $projectId, string $action): void {
$client = new RecaptchaEnterpriseServiceClient();
$projectName = $client->projectName($projectId);
// Crie o evento de avaliação (assessment)
$event = (new Event())->setSiteKey($recaptchaKey)->setToken($token);
$assessment = (new Assessment())->setEvent($event);
$request = (new CreateAssessmentRequest())->setParent($projectName)->setAssessment($assessment);
try {
$response = $client->createAssessment($request);
if (!$response->getTokenProperties()->getValid()) {
echo 'Token inválido: ' . InvalidReason::name($response->getTokenProperties()->getInvalidReason());
return;
}
if ($response->getTokenProperties()->getAction() === $action) {
echo 'Pontuação de risco: ' . $response->getRiskAnalysis()->getScore();
} else {
echo 'A ação na tag do reCAPTCHA não corresponde ao valor esperado';
}
} catch (Exception $e) {
echo 'Erro ao verificar o reCAPTCHA: ' . $e->getMessage();
}
}
// Chame a função passando as variáveis
create_assessment(
'YOUR_SITE_KEY',
'YOUR_USER_RESPONSE_TOKEN',
'YOUR_PROJECT_ID',
'YOUR_RECAPTCHA_ACTION'
);
?>
Se você herdou um site que já tem um captcha ou outro sistema de proteção instalado e não tem acesso ao código, não tem problema! É bem fácil identificar qual tecnologia está sendo usada. Para verificar se tudo está funcionando corretamente, você pode usar o serviço de reconhecimento CapMonster Cloud em um ambiente de testes isolado, para garantir que o mecanismo de processamento de tokens e a lógica de verificação estejam funcionando corretamente.
No caso de reCAPTCHA v2 Enterprise, basta identificar o sistema, analisar o comportamento dele e se certificar de que a proteção está funcionando corretamente. No artigo, mostramos como identificar reCAPTCHA v2 Enterprise e onde encontrar instruções para a integração ou reconfiguração, para que você consiga manter a proteção com segurança e controlar o funcionamento dela.
Crie um projeto e saiba mais sobre reCAPTCHA v2 Enterprise →Documentação do CapMonster Cloud (reCAPTCHA v2 Enterprise) →Como resolver reCAPTCHA Enterprise com CapMonster Cloud – passo a passo →