Como Detectar os Parâmetros do Turnstile da Cloudflare: sitekey, cData, action

TL;DR:

• O Cloudflare Turnstile é configurado por um punhado de parâmetros, e eles são legíveis a partir da página. A sitekey está sempre presente; action, cData e o callback são definidos pelo site quando o utiliza.
• Widgets em modo implícito carregam os parâmetros como atributos data-*. Leia data-sitekey, data-action, data-cdata e data-callback diretamente do elemento .cf-turnstile.
• Widgets em modo explícito passam os parâmetros para turnstile.render(). Intercepte essa chamada antes que a página a execute e você captura o objeto de opções completo — sitekey, action, cData e chlPageData.
• Em uma execução ao vivo, o widget expôs sitekey 0x4AAAAAAAW9zqSPAlyOSMfO e um callback. O gancho de renderização permaneceu vazio porque essa página usa o modo implícito — os parâmetros estavam no DOM em vez disso.
• Faça isso em um navegador real. Os parâmetros só existem uma vez que o script do widget foi executado, portanto, leia-os de uma página renderizada, não de HTML bruto.
• Grátis para começar. Novas contas do Scrapeless incluem um tempo de execução gratuito do Scraping Browser — inscreva-se em app.scrapeless.com.

Introdução: os parâmetros que configuram um widget Turnstile

O Cloudflare Turnstile é o widget que um site incorpora para verificar se um visitante é humano — o sucessor de um CAPTCHA de caixa de seleção. Quando carrega, é configurado por um pequeno conjunto de parâmetros: uma chave pública do site que identifica o widget, um rótulo de ação opcional que nomeia o evento protegido, um payload cData opcional que o site anexa, e um callback que recebe o token uma vez que o widget passa. Saber como ler esses parâmetros de uma página é o primeiro passo para entender, testar ou automatizar qualquer fluxo protegido pelo Turnstile.

Existem duas maneiras de um site conectar o Turnstile, e cada uma expõe os parâmetros de maneira diferente. Este guia cobre ambas — lê-los do DOM em modo implícito e capturá-los da chamada turnstile.render() em modo explícito — com uma execução ao vivo contra um verdadeiro widget Turnstile.

Os parâmetros, e o que cada um é

A chave do site é pública por design — é para estar na página. Os valores action e cData existem apenas quando o site opta por defini-los.

Por que Scrapeless Scraping Browser

O Scrapeless Scraping Browser é um navegador em nuvem personalizável e anti-detecção, projetado para crawlers da web e agentes de IA. Para ler parâmetros de widgets especificamente, ele traz:

• Renderização real do lado da nuvem — o script do widget realmente é executado, então os parâmetros existem para serem lidos.
• Uma conexão padrão do Puppeteer — puppeteer.connect() retorna um Browser comum; você inspeciona a página normalmente.
• Suporte a evaluateOnNewDocument — injete um gancho antes que os próprios scripts da página sejam executados, que é o que a captura em modo explícito precisa.
• Proxies residenciais em mais de 195 países — acesse páginas que servem seu verdadeiro widget apenas para egressos limpos.

Obtenha sua chave de API no plano gratuito em app.scrapeless.com.

Pré-requisitos

• Node.js 18 ou mais recente
• Uma conta no Scrapeless e chave de API — inscreva-se em app.scrapeless.com
• Familiaridade básica com Puppeteer e o DOM

Instalação

npm install puppeteer-core

export SCRAPELESS_API_KEY="seu_token_api_aqui"

Modo implícito: leia os parâmetros do DOM

O caso comum é um widget implícito: um elemento <div class="cf-turnstile" data-sitekey="…"> que o Turnstile renderiza automaticamente. Os parâmetros são os data-* atributos personalizados do elemento, então leia-os uma vez que o widget tenha sido montado:

import puppeteer from 'puppeteer-core';

const params = new URLSearchParams({
  token: process.env.SCRAPELESS_API_KEY,
  sessionTTL: '180',
  proxyCountry: 'US',
});
const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://browser.scrapeless.com/api/v2/browser?${params}`,
});

const page = await browser.newPage();
await page.goto('https://www.scrapingcourse.com/login/cf-turnstile', {
  waitUntil: 'domcontentloaded',
  timeout: 60000,
});
await new Promise((r) => setTimeout(r, 6000)); // deixar o script do widget montar

const widget = await page.evaluate(() => {
  const el = document.querySelector('.cf-turnstile, [data-sitekey]');
se (!el) return null;
  const attrs = {};
  for (const a of el.attributes) attrs[a.name] = a.value;
  return attrs;
});

console.log(widget);
// {
//   id: "waf",
//   class: "cf-turnstile",
//   "data-sitekey": "0x4AAAAAAAW9zqSPAlyOSMfO",
//   "data-callback": "javascriptCallback"
// }
await browser.close();

Em uma execução ao vivo, isso retornou a data-sitekey do widget (0x4AAAAAAAW9zqSPAlyOSMfO) e seu data-callback. Esta página específica não configura data-action ou data-cdata — essas chaves simplesmente não estão presentes, o que é normal: elas aparecem apenas quando o site as configura, e você as lê da mesma forma quando elas estão disponíveis.

Obtenha sua chave de API no plano gratuito: app.scrapeless.com

Modo explícito: capture os parâmetros de turnstile.render()

Quando um site renderiza o Turnstile de forma explícita, ele chama turnstile.render(container, options) em JavaScript, e os parâmetros vivem nesse objeto options — não no DOM. Para lê-los, conecte turnstile.render antes que o próprio script da página seja executado, usando evaluateOnNewDocument e um definidor de propriedade via Object.defineProperty:

await page.evaluateOnNewDocument(() => {
  window.__tsParams = [];
  Object.defineProperty(window, 'turnstile', {
    configurable: true,
    get() { return this.__ts; },
    set(v) {
      this.__ts = v;
      if (v && v.render && !v.__wrapped) {
        const orig = v.render.bind(v);
        v.render = (el, opts) => { window.__tsParams.push(opts || {}); return orig(el, opts); };
        v.__wrapped = true;
      }
    },
  });
});

await page.goto('https://example.com/turnstile-page', { waitUntil: 'domcontentloaded' });
await new Promise((r) => setTimeout(r, 7000));

const captured = await page.evaluate(() => window.__tsParams);
console.log(captured);
// render explícito → [{ sitekey: "0x…", action: "login", cData: "…", callback: [Function] }]

A conexão envolve render no momento em que o site atribui window.turnstile, então cada renderização explícita é capturada com suas opções completas — sitekey, action, cData, e chlPageData, quando presentes. Em uma página de modo implícito este array permanece vazio, porque o site nunca chama render() por conta própria — um sinal confiável de que você deve ler os parâmetros dos atributos do DOM em vez disso. Execute ambos e use aquele que estiver populado.

Notas

• A chave do site é pública; trate action e cData como opcionais. Proteja-se contra sua ausência em vez de assumir que todo widget as define.
• Leia de uma página renderizada, não de HTML bruto. No modo explícito, os parâmetros nunca aparecem na marcação servida — eles existem apenas depois que o script do widget é executado, motivo pelo qual um navegador real é necessário.
• Prefira um seletor durável. .cf-turnstile e [data-sitekey] são âncoras estáveis; a marcação ao redor não é.
• O token é uma etapa separada. Ler os parâmetros não é o mesmo que passar o widget — o token cf-turnstile-response é produzido pela callback após a validação do widget, e é verificado no lado do servidor conforme a documentação de validação do lado do servidor do Cloudflare Turnstile.

Conclusão: a configuração do widget, lida a partir da página

Os parâmetros do Turnstile não estão ocultos — a chave do site é destinada a ser pública, e os valores de action e cData são legíveis onde quer que o site os defina. Leia-os dos atributos data-* no modo implícito, ou conecte turnstile.render() para capturar o objeto de opções no modo explícito, e execute ambos para que o que a página usar esteja coberto. Para a mecânica de conduzir o navegador em nuvem, a documentação do Scraping Browser cobre todo o fluxo, e o lado anti-bot é explicado no guia sobre como contornar os desafios do Cloudflare; a documentação abrange o resto.

Pronto para Construir Seu Pipeline de Dados Potenciado por IA?

Junte-se à nossa comunidade para reivindicar um plano gratuito e se conectar com desenvolvedores que trabalham em fluxos anti-bot: Discord · Telegram.
Inscreva-se em app.scrapeless.com para obter gratuitamente o tempo de execução do Scraping Browser e veja preços para escalabilidade.

FAQ

P: Quais parâmetros um widget Turnstile possui?
Uma sitekey pública (sempre presente, formato 0x…), um rótulo action opcional, uma string cData opcional e um callback que recebe o token. Renderizações explícitas também podem passar chlPageData.

P: Onde posso encontrar a chave do site?
No elemento do widget como data-sitekey em modo implícito, ou nas opções passadas para turnstile.render() em modo explícito. Em uma execução ao vivo, ler-se-á 0x4AAAAAAAW9zqSPAlyOSMfO.

P: Por que falta data-action ou data-cdata?
Porque o site não os configurou — ambos são opcionais. Quando um site os utiliza, eles aparecem como data-action / data-cdata (implícito) ou action / cData (explícito), sendo lidos da mesma forma.

P: Por que preciso de um navegador real em vez de buscar o HTML?
No modo explícito, os parâmetros são passados em JavaScript e nunca aparecem na marcação servida; eles existem apenas após a execução do script do widget. Um navegador em nuvem renderiza a página, de modo que os valores estão presentes.

P: Ler os parâmetros passa o desafio?
Não. Os parâmetros configuram o widget; o token cf-turnstile-response é produzido separadamente pelo callback após a validação do widget e é verificado no servidor.