CapMonster Cloud API
Extensão para navegadores
Neste artigo procurámos responder a todas as questões importantes. Para começar a resolver o problema, o primeiro passo é identificar que sistema de proteção está a ser utilizado. Para isso, pode consultar a lista de captchas e sistemas de proteção antibot mais populares, onde encontrará exemplos visuais e sinais principais que ajudam a perceber rapidamente com o que está a lidar.
Se verificar que o seu site utiliza reCAPTCHA v2 Enterprise, o passo seguinte é analisar mais detalhadamente as suas características e o seu funcionamento. Neste mesmo artigo também pode consultar o guia de integração de reCAPTCHA v2 Enterprise, para compreender totalmente como o sistema funciona no seu site. Isto permitirá não só entender a proteção atual, como também planear corretamente a sua manutenção.
Ao testar formulários que incluem reCAPTCHA v2 Enterprise, é comum precisar verificar se a captcha foi integrada e funciona corretamente.
Pode testar manualmente a captcha incorporada no seu site.
Para resolução automática recorra a ferramentas como o CapMonster Cloud, que recebe os parâmetros da captcha, processa-os nos seus servidores e devolve um token pronto. Basta inseri-lo no formulário para ultrapassar a verificação sem interação do utilizador.
Trabalhar com o CapMonster Cloud através da API normalmente envolve os passos seguintes:
Criação da tarefa
Envio do pedido APISua requisição deve conter:
type - RecaptchaV2EnterpriseTask;
websiteURL - URL da página onde a captcha aparece;
websiteKey - o sitekey exibido na página;
enterprisePayload - informe se o widget reCAPTCHA Enterprise envia um campo s adicional no objeto passado a grecaptcha.enterprise.render junto com o sitekey;
pageAction - o valor action que o widget envia ao 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
}
Receção 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 o request de resolução
const recaptchaRequest = new RecaptchaV2EnterpriseRequest({
websiteURL: page.url(),
websiteKey: '6Lf76sUnAAAAAIKLuWNyegRsFUfmI-3Lex3xT5N'
// enterprisePayload: { s: 'SOME_ADDITIONAL_TOKEN' } // Parâmetro enterprise opcional
});
// 5. Resolva a captcha via 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 é executado 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. Insira um nome para o projeto, especifique a 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, aceda a Criar chave e clique em Criar chave.
6. Configure as definições básicas:
Em seguida, abra as Configurações adicionais, ative Vai utilizar desafios? e ative Checkbox Challenge.
7. Clique em Criar. Receberá uma chave que deve ser adicionada ao seu site para ativar a proteção.
8. Adicione o script à sua página.
Exemplo de trecho HTML que pode ser incorporado 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, portanto faça a verificação assim que o receber! 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 A chave reCAPTCHA do seu site/aplicação
* @param string $token Token recebido do cliente
* @param string $projectId ID do projeto no 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 com as variáveis
create_assessment(
'YOUR_SITE_KEY',
'YOUR_USER_RESPONSE_TOKEN',
'YOUR_PROJECT_ID',
'YOUR_RECAPTCHA_ACTION'
);
?>
Se 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 há problema! É bastante fácil identificar qual a tecnologia que está a ser utilizada. Para verificar se tudo está a funcionar corretamente, pode usar o serviço de reconhecimento CapMonster Cloud num ambiente de teste isolado, para garantir que o mecanismo de processamento de tokens e a lógica de verificação estão a funcionar corretamente.
No caso de reCAPTCHA v2 Enterprise, basta identificar o sistema, analisar o seu comportamento e confirmar que a proteção está a funcionar corretamente. No artigo, mostramos como identificar reCAPTCHA v2 Enterprise e onde encontrar instruções para a sua integração ou reconfiguração, para que possa manter a proteção com confiança e controlar o seu funcionamento.
