Cloudflare Turnstile
e CapMonster Cloud

Solução de CAPTCHA, instalação no site e testes.

Preços da solução Cloudflare Turnstile

CAPTCHA	Preço (USD)	Sucesso
Cloudflare Turnstile 99%	$ 1.30 1000 tokens	99%

Você herdou um site com captcha ou outra camada de proteção, mas não tem acesso ao código-fonte? Então é normal querer saber qual solução está instalada, se a configuração está correta e como testar tudo.

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 Cloudflare Turnstile, 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 Cloudflare Turnstile, 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.

O que é Cloudflare Turnstile

Cloudflare Turnstile é um CAPTCHA moderno da Cloudflare que protege sites de ações automatizadas. Para os visitantes do site, a verificação é quase invisível, não há necessidade de completar tarefas: geralmente basta um clique na caixa de seleção, após o qual o sistema decide se permite a passagem do visitante ou o bloqueia em caso de suspeita de bot. Ao contrário do Cloudflare Challenge, o CAPTCHA Turnstile é colocado diretamente no site, não em uma janela separada—geralmente em formulários de login ou cadastro.

Como resolver Cloudflare Turnstile via CapMonster Cloud

Ao testar formulários com Cloudflare Turnstile, é comum precisar confirmar se a captcha está funcionando e integrada corretamente.

Você pode testar manualmente a captcha incorporada no site.

Abra a página do formulário e veja se a captcha é exibida.
Tente enviar sem resolver — o servidor deve retornar erro.
Depois de resolver corretamente, o envio precisa ocorrer sem falhas.

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

Nesta etapa, você passa sua chave API, tipo de CAPTCHA e seus parâmetros. O serviço retorna um taskId único, que pode ser usado posteriormente para recuperar o resultado.

Envio da requisição API

Na solicitação para resolver Cloudflare Turnstile, é necessário especificar os seguintes parâmetros:

type - TurnstileTask;

websiteURL - endereço da página onde o CAPTCHA está sendo resolvido;

websiteKey - chave Turnstile.

Saiba mais sobre os parâmetros e como capturá-los automaticamente antes de enviar a tarefa na documentação do CapMonster Cloud.

Endpoint para envio da tarefa:

javascript

https://api.capmonster.cloud/createTask

Exemplo de requisição:

json

{
  "clientKey": "API_KEY",
  "task": {
    "type": "TurnstileTask",
    "websiteURL": "http://tsmanaged.zlsupport.com",
    "websiteKey": "0x4AAAAAAABUYP0XeMJF0xoy"
  }
}

Resposta:

json

{
  "errorId":0,
  "taskId":407533072
}

Recebimento do resultado

Após criar a tarefa, consulte periodicamente o status da solução.

Endereço para receber o resultado:

javascript

https://api.capmonster.cloud/getTaskResult

Exemplo de requisição:

json

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

Resposta:

json

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/150.0.0.0 Safari/537.36",
    "token": "0.iGX3xsyFCkbGePM3jP4P4khLo6TrLukt8ZzBvwuQOvbC...f61f3082"
  }
}

Aplicação do token na página

Depois que o servidor receber o token Turnstile do CapMonster Cloud, ele deve ser passado para o site. O servidor verificará os dados e confirmará que o CAPTCHA foi resolvido com sucesso. Para automação, você pode usar solicitações HTTP ou ferramentas como Puppeteer, Selenium ou Playwright—elas permitem inserir valores no formulário e enviar a solicitação, emulando ações do usuário.

Reconhecimento de Cloudflare Turnstile usando bibliotecas prontas

O serviço CapMonster Cloud fornece bibliotecas prontas para trabalho conveniente nas linguagens Python, JavaScript (Node.js) e C#.

Python

JavaScript

Solução, inserção de token e envio de formulário

Exemplo em Node.js para o ciclo completo de reconhecimento de CAPTCHA em sua página web. Abordagens possíveis: usar solicitações HTTP para obter HTML e parâmetros do CAPTCHA, enviar a resposta e processar o resultado; ou com ferramentas de automação (por exemplo, Playwright)—abrir a página, aguardar o CAPTCHA, enviar parâmetros (para testes você pode enviar dados corretos e incorretos), obter a solução via cliente CapMonster Cloud, inserir o token no formulário e ver o resultado.

python

// npm install playwright @zennolab_com/capmonstercloud-client

import { chromium } from "playwright";
import { CapMonsterCloudClientFactory, ClientOptions, TurnstileRequest } from "@zennolab_com/capmonstercloud-client";

async function main() {
  // 1. Resolver Turnstile via CapMonster Cloud
  const cmcClient = CapMonsterCloudClientFactory.Create(
    new ClientOptions({ clientKey: 'YOUR_CAPMONSTER_API_KEY' })
  );

  const turnstileRequest = new TurnstileRequest({
    websiteURL: 'http://tsmanaged.zlsupport.com',
    websiteKey: '0x4AAAAAAABUYP0XeMJF0xoy',
  });

  const result = await cmcClient.Solve(turnstileRequest);
  const token = result.solution.token;
  console.log('Token Turnstile recebido:', token);

  // 2. Iniciando Playwright
  const browser = await chromium.launch({ headless: false });
  const context = await browser.newContext();
  const page = await context.newPage();
  await page.goto('http://tsmanaged.zlsupport.com');

  // 3. Preenchendo login e senha
  await page.fill('#username', 'your_username');
  await page.fill('#password', 'your_password');

  // 4. Aguardando o aparecimento do campo de token oculto
  await page.waitForSelector('#token', { state: 'attached', timeout: 60000 });

  // 5. Inserindo token e tornando o campo visível
  await page.evaluate((t) => {
    const tokenInput = document.querySelector('#token');
    if (tokenInput) {
      tokenInput.type = 'text';  // tornar o campo visível
      tokenInput.value = t;      // inserir token
      console.log('Token inserido no campo token');
    } else {
      console.error('Campo #token não encontrado');
    }
  }, token);

  // 6. Verificando se o token foi realmente inserido
  const checkValue = await page.$eval('#token', el => el.value);
  console.log('Verificação do valor do token:', checkValue);

  // 7. Enviando formulário
  await page.click('button[type="submit"]');
  console.log('Formulário enviado com token Turnstile');

  // await browser.close();
}

main().catch(err => console.error(err));

Também existe uma excelente opção para testar o reconhecimento de CAPTCHA usando a extensão de navegador CapMonster Cloud, que permite verificar rapidamente a funcionalidade do CAPTCHA diretamente na página e rastrear o processo de solução em tempo real sem escrever código—disponível para instalação no Chrome e Firefox.

Como conectar Cloudflare Turnstile ao seu site

Para navegar com confiança no funcionamento do CAPTCHA em seu site, entender a lógica de sua verificação, reconectá-lo ou reconfigurá-lo, recomendamos estudar esta seção. Ela descreve o processo de conexão da proteção—isso ajudará a entender rapidamente todas as nuances.

1. Vá para a página Cloudflare Turnstile, clique em Começar agora.

2. Cadastre-se no serviço.

3. Em Turnstile Widgets, clique no botão azul Add Widget.

HowTo Connect image 1

4. Configure o Cloudflare Turnstile, especifique:

Widget name—nome do CAPTCHA (para conveniência, por exemplo, Login form).
Hostname Management—domínios onde o CAPTCHA funcionará (por exemplo, example.com).
Widget Mode:
- Managed—opção ideal, o CAPTCHA decide por si só se mostra a caixa de seleção.
- Non-interactive—a verificação é realizada automaticamente sem cliques.
- Invisible—completamente invisível.
Pre-clearance—defina como Yes se o site passa pelo Cloudflare Proxy (para não repetir o CAPTCHA).

5. Após criar o widget, você receberá duas chaves—Site Key e Secret Key.

HowTo Connect image 2

6. Conecte a parte do cliente

1) Conecte o script Turnstile

Renderização automática (o widget é criado automaticamente ao carregar a página):

markup

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

Controle programático (você mesmo cria o widget via JavaScript):

markup

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit" defer></script>

Importante: o script deve ser carregado do URL exato. Proxy ou cache podem causar falhas.

2) Crie um contêiner para o widget

Automático:

markup

<div class="cf-turnstile" data-sitekey="<YOUR_SITEKEY>"></div>

Programaticamente:

markup

<div id="turnstile-container"></div>

3) Configuração do widget

Via atributos data:

markup

<div class="cf-turnstile"
            data-sitekey="<YOUR_SITEKEY>"
            data-theme="light"
            data-size="normal"
            data-callback="onSuccess">
          </div>

Via JavaScript:

javascript

const widgetId = turnstile.render("#turnstile-container", {
  sitekey: "<YOUR_SITEKEY>",
  theme: "light",
  size: "normal",
  callback: token => console.log("Token:", token)
});

4) Trabalhando com tokens

javascript

const token = turnstile.getResponse(widgetId);      // obter token
const isExpired = turnstile.isExpired(widgetId);    // verificar expiração
turnstile.reset(widgetId);                          // redefinir
turnstile.remove(widgetId);                         // remover
turnstile.execute("#turnstile-container");         // execução manual

5) Integração com formulário

markup

<form id="my-form" method="POST">
  <input type="hidden" name="cf-turnstile-response" id="cf-turnstile-response">
  <button type="submit">Enviar</button>
</form>

<script>
function onSuccess(token) {
  document.getElementById("cf-turnstile-response").value = token;
}
</script>

Exemplo de código

markup

<title>Turnstile Example</title>
  <!-- Conectar script Turnstile -->
  <script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
</head>
<body>
  <h1>Exemplo de formulário com Turnstile</h1>

  <form id="my-form">
    <label for="username">Nome:</label>
    <input type="text" name="username" id="username" required>
    
    <!-- Contêiner para Turnstile -->
    <div class="cf-turnstile" data-sitekey="<YOUR_SITEKEY>" data-callback="onTurnstileSuccess"></div>
    
    <button type="submit">Enviar</button>
  </form>

  <script>
    // Callback chamado após passar no CAPTCHA
    function onTurnstileSuccess(token) {
      console.log("Token Turnstile recebido:", token);
      // Salvar token em campo oculto do formulário (opcional)
      document.getElementById("cf-turnstile-token")?.remove();
      const input = document.createElement("input");
      input.type = "hidden";
      input.name = "cf-turnstile-response";
      input.id = "cf-turnstile-token";
      input.value = token;
      document.getElementById("my-form").appendChild(input);
    }

    // Envio do formulário
    document.getElementById("my-form").addEventListener("submit", async (e) => {
      e.preventDefault();

      const formData = new FormData(e.target);
      const response = await fetch("/submit-form", {
        method: "POST",
        body: formData
      });

      const result = await response.json();
      if(result.success){
        alert("Formulário enviado com sucesso e token verificado!");
      } else {
        alert("Erro de verificação do token Turnstile. Tente novamente.");
        // Redefinir widget para que o usuário possa completar o CAPTCHA novamente
        turnstile.reset();
      }
    });
  </script>
</body>
</html>

6) Configure a parte do servidor

Processo de verificação do lado do servidor:

Cliente: o usuário completa o Turnstile na página → o token é criado.
Formulário é enviado: o token junto com os dados do formulário é enviado ao servidor.
Servidor: faz uma solicitação POST para a API Siteverify da Cloudflare com o token e o segredo.
Cloudflare: retorna JSON com o resultado (success: true/false) e informações adicionais (action, hostname, tempo de conclusão).
Servidor: decide se permite ou rejeita a ação do usuário.

API Siteverify:

javascript

POST

https://challenges.cloudflare.com/turnstile/v0/siteverify

Parâmetros da solicitação:

secret (obrigatório): chave secreta Turnstile do painel Cloudflare
response (obrigatório): token recebido no cliente
remoteip (opcional): endereço IP do usuário (recomendado)
idempotency_key (opcional): UUID único para proteção contra verificações repetidas

Propriedades do token:

Comprimento máximo: 2048 caracteres
Válido por 5 minutos
Uso único
Quando expirado ou reverificado, a API retornará o erro timeout-or-duplicate

Exemplo de verificação em PHP

php

<?php
function validateTurnstile($token, $secret, $remoteip = null) {
    $url = 'https://challenges.cloudflare.com/turnstile/v0/siteverify';
    $data = ['secret' => $secret, 'response' => $token];
    if ($remoteip) $data['remoteip'] = $remoteip;

    $options = [
        'http' => [
            'header'  => "Content-type: application/x-www-form-urlencoded
",
            'method'  => 'POST',
            'content' => http_build_query($data)
        ]
    ];

    $response = file_get_contents($url, false, stream_context_create($options));
    if ($response === FALSE) {
        return ['success' => false, 'error-codes' => ['internal-error']];
    }

    return json_decode($response, true);
}

// Uso
$secret_key = 'YOUR_SECRET_KEY';
$token = $_POST['cf-turnstile-response'] ?? '';
$remoteip = $_SERVER['REMOTE_ADDR'];

$result = validateTurnstile($token, $secret_key, $remoteip);

if($result['success']){
    echo "Formulário enviado com sucesso!";
} else {
    echo "Erro de verificação: " . implode(', ', $result['error-codes']);
}
?>

Todas as instruções detalhadas para instalar e configurar o Cloudflare Turnstile, incluindo integração de cliente e servidor, exemplos de código, descrições de erros e recomendações de segurança, podem ser encontradas na documentação oficial da Cloudflare.

Possíveis erros e depuração

Parâmetros incorretos

O CAPTCHA não é exibido ou retorna erros como invalid-input-secret, missing-input-response, invalid-input-response. Verifique a validade de sitekey e secret key, bem como as configurações no Painel Cloudflare.

Tempo limite da solução

O token expirou (válido por 300 segundos) ou não foi recebido a tempo. Garanta uma conexão estável e integração correta com a API.

Token vazio ou incorreto

O parâmetro cf-turnstile-response está ausente ou incorreto. Verifique a transferência do token para o formulário e servidor.

Resposta success=false

O token é inválido, expirado ou já foi usado. Cada token só pode ser verificado uma vez. Ative o registro de solicitações e respostas Siteverify para análise.

Verificação da robustez

Depois da integração, confirme que o sistema de fato protege o site contra ações automatizadas.

Tente executar a solicitação sem resolver o CAPTCHA—o servidor deve retornar success: false.

Realize testes de carga (por exemplo, usando k6 ou JMeter) a velocidades acima de 100+ solicitações por segundo. O Turnstile deve processar as solicitações corretamente e o servidor deve verificar os tokens de forma estável através da API Siteverify.

Verifique a resposta a tokens expirados ou reenviados—resposta esperada da API: success: false e error-codes: ["timeout-or-duplicate"].

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

Verifique os tokens apenas no servidor, nunca chame a API Siteverify do frontend—isso exporá sua chave secreta.

Verifique os tokens apenas no servidor, nunca chame a API Siteverify do frontend—isso exporá sua chave secreta.

Use variáveis de ambiente ou um sistema de gerenciamento de segredos em vez de armazenar chaves no código.

Use variáveis de ambiente ou um sistema de gerenciamento de segredos em vez de armazenar chaves no código.

Verifique campos adicionais (<span class="font-bold">hostname</span>, <span class="font-bold">action</span>) para garantir que a solicitação veio do seu site.

Verifique campos adicionais (hostname, action) para garantir que a solicitação veio do seu site.

Use HTTPS—todas as chamadas para Siteverify devem ser feitas através de uma conexão segura.

Use HTTPS—todas as chamadas para Siteverify devem ser feitas através de uma conexão segura.

Implemente tratamento de erros—quando a API não estiver disponível, mostre ao usuário uma mensagem clara sem revelar dados internos.

Implemente tratamento de erros—quando a API não estiver disponível, mostre ao usuário uma mensagem clara sem revelar dados internos.

Restrinja o uso da sitekey por domínios.

Adicione links para a <span class="font-bold">Política de Privacidade</span> e os <span class="font-bold">Termos de Serviço da Cloudflare</span> ao formulário se exigido por sua organização ou política de privacidade.

Adicione links para a Política de Privacidade e os Termos de Serviço da Cloudflare ao formulário se exigido por sua organização ou política de privacidade.

Captchas suportados

Conclusão

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 Cloudflare Turnstile, basta identificar o sistema, analisar o comportamento dele e se certificar de que a proteção está funcionando corretamente. No artigo, mostramos como identificar Cloudflare Turnstile 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.

Links úteis

Documentação Cloudflare Turnstile →

Cadastrar-se na Cloudflare →

Cadastrar-se no CapMonster Cloud →

Documentação CapMonster Cloud (trabalhando com Cloudflare Turnstile) →

O que é Cloudflare CAPTCHA e como resolvê-lo com CapMonster Cloud →

Como a Cloudflare detecta tráfego automatizado: proteção de sites contra bots →

A extensão do CapMonster Cloud para navegador está disponível para Chrome e Firefox. Veja o passo a passo completo neste link.

Perguntas frequentes sobre o Cloudflare Turnstile

Como resolver o Cloudflare Turnstile pela API do CapMonster Cloud?

Para resolver o Cloudflare Turnstile com o CapMonster Cloud:

Envie uma requisição POST para https://api.capmonster.cloud/createTask com os seguintes parâmetros JSON:

json

{
  "clientKey": "API_KEY",
  "task": {
    "type": "TurnstileTask",
    "websiteURL": "[page_URL_with_Turnstile]",
    "websiteKey": "[Turnstile_website_key]"
  }
}

clientKey: Sua chave de API do CapMonster Cloud
task.type: TurnstileTask
task.websiteURL: A URL da página onde o captcha é resolvido
task.websiteKey: Chave Turnstile site key. Veja como encontrá-la.

A API retorna um taskId.

Consulte https://api.capmonster.cloud/getTaskResult com clientKey e taskId até que o status da resposta se torne ready.

Quando a tarefa for resolvida, a resposta inclui um token e o userAgent correspondente.

Passe ambos os valores para a mesma sessão do navegador que enviará o formulário.

Consulte a documentação da tarefa Turnstile para detalhes e exemplos.

Quais modos de widget do Cloudflare Turnstile estão disponíveis?

O Cloudflare Turnstile oferece três modos de widget:

Managed: O Turnstile decide se exibe uma verificação interativa ou libera o visitante silenciosamente com base no risco.
Non-interactive: Funciona sem interação do usuário, mas ainda exibe um widget visível durante as verificações.
Invisible: Também funciona sem interação do usuário, mas o widget não é exibido ao visitante.

Como verificar um token do Cloudflare Turnstile no servidor como desenvolvedor?

Quando seu backend recebe o token Turnstile do cliente:

Envie-o via POST para https://challenges.cloudflare.com/turnstile/v0/siteverify com os parâmetros:

secret: A chave secreta do widget no painel da Cloudflare
response: O token do widget no lado do cliente
remoteip (opcional): O IP do visitante
idempotency_key (opcional): Um UUID gerado por você para repetir a validação com segurança

O endpoint aceita tanto application/x-www-form-urlencoded quanto application/json.

Se o token passou na verificação com sucesso, a Cloudflare retorna success: true.

Como passar um token Turnstile para um formulário no Playwright?

Use page.evaluate() ou outro método no nível do DOM para injetar o token no campo com [name="cf-turnstile-response"] antes de enviar o formulário.

Lembre-se de que algumas integrações também dependem de callbacks ou handlers JavaScript personalizados. Nesse caso, chame a função de callback JS do widget (definida em data-callback) e passe o token recebido para a verificação no servidor.

O que significa timeout-or-duplicate na verificação do servidor Turnstile?

O erro timeout-or-duplicate do Turnstile siteverify geralmente significa que o token expirou antes da verificação ou foi enviado mais de uma vez. Os tokens Turnstile são de uso único e expiram após cinco minutos.

Para depuração de erros:

Ative o registro de requisições para https://challenges.cloudflare.com/turnstile/v0/siteverify
Compare o horário de criação do token com o horário de verificação.
Verifique se seu backend valida o mesmo token duas vezes, por exemplo durante novas tentativas, redirecionamentos ou tratamento de requisições duplicadas.

Cloudflare Turnstile e CapMonster Cloud

Preços da solução Cloudflare Turnstile

Como resolver Cloudflare Turnstile via CapMonster Cloud

Captchas suportados

Perguntas frequentes sobre o Cloudflare Turnstile

Cloudflare Turnstile
e CapMonster Cloud