Resolvedor de reCAPTCHA Enterprise | CapMonster Cloud

reCAPTCHA v2 Enterprise
e CapMonster Cloud

Resolução de captchas, integração no site e testes ponta a ponta.

Preços da solução reCAPTCHA v2 Enterprise

CAPTCHA

Preço

Sucesso

reCAPTCHA v2 Enterprise

97%

$ 1.00

1k tokens

97%

Herdou um site com captcha ou outra proteção mas sem acesso ao código-fonte? É natural perguntar qual solução está instalada, se está configurada corretamente e como testá-la.

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.

O que é o Google reCAPTCHA v2 Enterprise

reCAPTCHA v2 Enterprise é a versão corporativa da proteção padrão do Google contra spam e ataques automatizados. Identifica com mais precisão se há um humano ou um bot na página e usa a API Google Cloud para validar os tokens. Visualmente, é quase idêntico ao reCAPTCHA v2 com checkbox e desafios de imagens, mas carrega https://www.google.com/recaptcha/enterprise.js para oferecer segurança adicional.

Como resolver o reCAPTCHA v2 Enterprise com o CapMonster Cloud

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.

Abra a página do formulário e confirme que a captcha é apresentada.
Tente enviar o formulário sem resolvê-la — o servidor deve devolver um erro.
Após uma resolução bem-sucedida, o formulário deve ser enviado sem problemas.

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

Nesta etapa você envia sua chave de API, tipo de captcha e parâmetros. O serviço retorna um taskId exclusivo para buscar o resultado depois.

Envio do pedido API

Sua 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).

Saiba mais sobre os parâmetros e como recolhê-los automaticamente na documentação do CapMonster Cloud.

Resolvendo reCAPTCHA v2 Enterprise com bibliotecas prontas

O CapMonster Cloud disponibiliza SDKs para Python, JavaScript (Node.js) e C#.

Python

JavaScript

Como conectar o reCAPTCHA v2 Enterprise ao seu site

Para entender como o captcha funciona no seu site, como o processo de validação se comporta e como reconectar ou reconfigurar tudo, consulte esta seção. Ela percorre toda a configuração de proteção para que você consiga cobrir rapidamente cada detalhe.

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.

HowTo Connect image 1

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.

HowTo Connect image 2

6. Configure as definições básicas:

Nome de exibição: qualquer rótulo que ajude a identificar a chave (por exemplo, MySite Login Page).
Tipo de aplicação: escolha WEB (sites) ou Aplicação móvel. Não é possível alterar isto mais tarde.
Lista de domínios: adicione os domínios em que esta chave será utilizada.

Em seguida, abra as Configurações adicionais, ative Vai utilizar desafios? e ative Checkbox Challenge.

HowTo Connect image 3

7. Clique em Criar. Receberá uma chave que deve ser adicionada ao seu site para ativar a proteção.

HowTo Connect image 3

8. Adicione o script à sua página.

Exemplo de trecho HTML que pode ser incorporado no seu site

Possíveis erros e depuração

Site ou chave inválidos

A captcha não carrega ou retorna invalid-input-secret.

Tempo limite de resolução

O servidor não recebeu a resposta a tempo. Aumente o tempo de espera.

Token vazio

Erro ao passar o resultado para a página.

Response success=false

O token expirou, foi reutilizado ou adulterado. Ative o log de requisições e confira o campo error-codes na resposta do Google.

Verificações de robustez

Depois da integração, certifique-se de que o sistema protege efetivamente o site contra ações automatizadas.

Tente enviar um pedido sem resolver o captcha — o servidor deve devolver success: false.

Faça um teste de carga (por exemplo, com o k6 ou o JMeter) a uma velocidade superior a 100 pedidos por segundo — o captcha deve ser apresentado corretamente e o sistema de validação deve manter-se estável.

Verifique a reação do servidor com um token expirado ou reenviado — a resposta esperada deve ser 403 Forbidden.

Recomendações de segurança e otimização

Guarde a <span class="font-bold">Secret Key</span> apenas no servidor e não a envie para a parte cliente.

Guarde a Secret Key apenas no servidor e não a envie para a parte cliente.

Registe os códigos de erro <span class="font-bold">(error-codes)</span> para perceber porque é que determinadas verificações falharam.

Registe os códigos de erro (error-codes) para perceber porque é que determinadas verificações falharam.

Adicione no fundo do formulário ligações para a <span class="font-bold">Política de Privacidade</span> e para os <span class="font-bold">Termos de Utilização da Google</span>, tal como exigido pela licença.

Adicione no fundo do formulário ligações para a Política de Privacidade e para os Termos de Utilização da Google, tal como exigido pela licença.

Captchas suportados

reCAPTCHA v2

reCAPTCHA v3

reCAPTCHA v2 Enterprise

reCAPTCHA v3 Enterprise

GeeTest

Cloudflare Turnstile

Cloudflare Bot Challenge

DataDome

Tencent CAPTCHA

Conclusão

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.

Links úteis

Crie um projeto e saiba mais sobre reCAPTCHA v2 Enterprise →

Documentação CapMonster Cloud (reCAPTCHA v2 Enterprise) →

Como resolver o reCAPTCHA Enterprise com CapMonster Cloud: guia passo a passo →

A extensão de navegador do CapMonster Cloud está disponível para Chrome e Firefox. Instruções completas encontram-se aqui.

{
  "clientKey": "API_KEY",
  "task": {
    "type": "RecaptchaV2EnterpriseTask",
    "websiteURL": "https://mydomain.com/page-with-recaptcha-enterprise",
    "websiteKey": "6Lcg7CMUAAAAANphynKgn9YAgA4tQ2KI_iqRyTwd",
    "pageAction": "verify",
    "enterprisePayload": {
      "s": "SOME_ADDITIONAL_TOKEN"
    }
  }
}

Receção do resultado

Depois de criar a tarefa, acompanhe periodicamente o estado da solução.

Endereço para receber o resultado:

https://api.capmonster.cloud/getTaskResult

Exemplo de pedido:

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

Resposta:

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "gRecaptchaResponse": "03AFcWeA66ZARdA5te7acD9vSwWE2hEQ2-B2aqFxm455iMA-g-Jis..."
  }
}

Resolver, inserir o token e enviar o formulário

Exemplo em Node.js que cobre todo o ciclo: obter HTML e parâmetros via HTTP, enviar a resposta e processar o resultado; ou usar ferramentas como Playwright para abrir a página, esperar a captcha, enviar parâmetros (até mesmo de teste), receber o resultado no cliente CapMonster Cloud, inserir o token e checar o resultado.

import { 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();
})();

Você também pode testar com a extensão CapMonster Cloud para o navegador, verificando a captcha diretamente na página e acompanhando o processo em tempo real sem escrever código. Disponível para Chrome e Firefox.

<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>

Exemplo em PHP

O 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'
);
?>

reCAPTCHA v2 Enterprise e CapMonster Cloud

Preços da solução reCAPTCHA v2 Enterprise

Como resolver o reCAPTCHA v2 Enterprise com o CapMonster Cloud

Captchas suportados

reCAPTCHA v2 Enterprise
e CapMonster Cloud