Cloudflare Turnstile
e CapMonster Cloud

Risoluzione CAPTCHA, installazione sul sito web e test.

Prezzi della soluzione Cloudflare Turnstile

CAPTCHA	Prezzo (USD)	Successo
Cloudflare Turnstile 99%	$ 1.30 1000 gettoni	99%

Hai ereditato un sito con una captcha o un'altra protezione ma senza accesso al codice sorgente? È normale chiedersi quale soluzione sia installata, se sia configurata correttamente e come testarla.

In questo articolo abbiamo cercato di rispondere a tutte le domande principali. Il primo passo per risolvere il problema è capire quale sistema di protezione viene utilizzato. A questo scopo puoi consultare l’elenco dei captcha e dei sistemi di protezione antibot più diffusi, dove trovi esempi visivi e caratteristiche chiave che ti aiutano a identificare rapidamente con cosa hai a che fare.

Se scopri che sul tuo sito viene utilizzato Cloudflare Turnstile, il passo successivo è analizzarne più nel dettaglio le proprietà e il funzionamento. In questo stesso articolo puoi anche studiare la guida all’integrazione di Cloudflare Turnstile, per comprendere a fondo come opera sul tuo sito. Questo ti permetterà non solo di capire la protezione attuale, ma anche di pianificarne correttamente la manutenzione.

Cos'è Cloudflare Turnstile

Cloudflare Turnstile è un CAPTCHA moderno di Cloudflare che protegge i siti web da azioni automatizzate. Per i visitatori del sito web, la verifica è quasi invisibile, non è necessario completare compiti: di solito è sufficiente un clic sulla casella di controllo, dopo di che il sistema decide se lasciare passare il visitatore o bloccarlo in caso di sospetto bot. A differenza di Cloudflare Challenge, il CAPTCHA Turnstile viene posizionato direttamente sul sito web, non in una finestra separata, di solito nei moduli di accesso o registrazione.

Come risolvere Cloudflare Turnstile tramite CapMonster Cloud

Quando testi form che includono Cloudflare Turnstile devi spesso verificare che la captcha funzioni e sia integrata correttamente.

Puoi verificare manualmente la captcha inserita nel tuo sito.

Apri la pagina del form e assicurati che la captcha venga visualizzata.
Prova a inviare il form senza risolverla: il server dovrebbe restituire un errore.
Dopo una soluzione corretta il form deve essere inviato senza problemi.

Per la risoluzione automatica puoi usare strumenti come CapMonster Cloud, che accetta i parametri della captcha, li elabora sui propri server e restituisce un token pronto all'uso. Inserisci quel token nel form per superare il controllo senza intervento dell'utente.

Lavorare con CapMonster Cloud via API di solito prevede i seguenti passaggi:

Creazione della task

In questa fase, passi la tua chiave API, il tipo di CAPTCHA e i suoi parametri. Il servizio restituisce un taskId univoco, che può essere utilizzato successivamente per recuperare il risultato.

Invio della richiesta API

Nella richiesta per risolvere Cloudflare Turnstile è necessario specificare i seguenti parametri:

type - TurnstileTask;

websiteURL - indirizzo della pagina dove viene risolto il CAPTCHA;

websiteKey - chiave Turnstile.

Ulteriori dettagli sui parametri e su come recuperarli automaticamente prima di inviare una richiesta sono disponibili nella documentazione di CapMonster Cloud.

Endpoint per inviare la task:

https://api.capmonster.cloud/createTask

Esempio di richiesta:

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

Risposta:

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

Ricezione del risultato

Dopo aver creato la task, verifica periodicamente lo stato della soluzione.

Indirizzo per ricevere il risultato:

https://api.capmonster.cloud/getTaskResult

Esempio di richiesta:

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

Risposta:

{
  "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"
  }
}

Inserimento del token nella pagina

Dopo che il server ha ricevuto il token Turnstile da CapMonster Cloud, deve essere passato al sito web. Il server verificherà i dati e confermerà che il CAPTCHA è stato risolto con successo. Per l'automazione, è possibile utilizzare richieste HTTP o strumenti come Puppeteer, Selenium o Playwright: consentono di inserire valori nel modulo e inviare la richiesta, emulando le azioni dell'utente.

Riconoscimento di Cloudflare Turnstile utilizzando librerie pronte

Il servizio CapMonster Cloud fornisce librerie pronte per un lavoro comodo nei linguaggi Python, JavaScript (Node.js) e C#.

Python

JavaScript

Risoluzione, inserimento token e invio del modulo

Esempio in Node.js per il ciclo completo di riconoscimento CAPTCHA sulla tua pagina web. Approcci possibili: utilizzare richieste HTTP per ottenere HTML e parametri CAPTCHA, inviare la risposta e elaborare il risultato; oppure con strumenti di automazione (ad esempio, Playwright): aprire la pagina, attendere il CAPTCHA, inviare i parametri (per i test è possibile inviare sia dati corretti che errati), ottenere la soluzione tramite il client CapMonster Cloud, inserire il token nel modulo e vedere il risultato.

// npm install playwright @zennolab_com/capmonstercloud-client

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

async function main() {
  // 1. Risoluzione Turnstile tramite 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 ricevuto:', token);

  // 2. Avvio di 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. Compilazione di login e password
  await page.fill('#username', 'your_username');
  await page.fill('#password', 'your_password');

  // 4. Attesa della comparsa del campo token nascosto
  await page.waitForSelector('#token', { state: 'attached', timeout: 60000 });

  // 5. Inserimento del token e rendere visibile il campo
  await page.evaluate((t) => {
    const tokenInput = document.querySelector('#token');
    if (tokenInput) {
      tokenInput.type = 'text';  // rendi visibile il campo
      tokenInput.value = t;      // inserisci il token
      console.log('Token inserito nel campo token');
    } else {
      console.error('Campo #token non trovato');
    }
  }, token);

  // 6. Verifica che il token sia stato effettivamente inserito
  const checkValue = await page.$eval('#token', el => el.value);
  console.log('Verifica del valore del token:', checkValue);

  // 7. Invio del modulo
  await page.click('button[type="submit"]');
  console.log('Modulo inviato con token Turnstile');

  // await browser.close();
}

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

C'è anche un'eccellente opzione per testare il riconoscimento CAPTCHA utilizzando l'estensione del browser CapMonster Cloud, che consente di verificare rapidamente la funzionalità del CAPTCHA direttamente sulla pagina e tracciare il processo di risoluzione in tempo reale senza scrivere codice, disponibile per l'installazione in Chrome e Firefox.

Come connettere Cloudflare Turnstile al tuo sito web

Per navigare con sicurezza nel funzionamento del CAPTCHA sul tuo sito web, comprendere la logica della sua verifica, riconnetterlo o riconfigurarlo, ti consigliamo di studiare questa sezione. Descrive il processo di connessione della protezione: ciò ti aiuterà a comprendere rapidamente tutte le sfumature.

1. Vai alla pagina Cloudflare Turnstile, fai clic su Inizia ora.

2. Registrati al servizio.

3. In Turnstile Widgets, fai clic sul pulsante blu Add Widget.

HowTo Connect image 1

4. Configura Cloudflare Turnstile, specifica:

Widget name: nome del CAPTCHA (per comodità, ad esempio Login form).
Hostname Management: domini dove il CAPTCHA funzionerà (ad esempio, example.com).
Widget Mode:
- Managed: opzione ottimale, il CAPTCHA decide da solo se mostrare la casella di controllo.
- Non-interactive: la verifica viene eseguita automaticamente senza clic.
- Invisible: completamente invisibile.
Pre-clearance: imposta su Yes se il sito passa attraverso Cloudflare Proxy (per evitare di ripetere il CAPTCHA).

5. Dopo aver creato il widget, riceverai due chiavi: Site Key e Secret Key.

HowTo Connect image 2

6. Connetti la parte client

1) Connetti lo script Turnstile

Rendering automatico (il widget viene creato automaticamente al caricamento della pagina):

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

Controllo programmatico (crei tu stesso il widget tramite JavaScript):

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

Importante: lo script deve essere caricato dall'URL esatto. Proxy o cache possono causare malfunzionamenti.

2) Crea un contenitore per il widget

Automatico:

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

Programmaticamente:

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

3) Configurazione del widget

Tramite attributi data:

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

Tramite JavaScript:

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

4) Lavorare con i token

const token = turnstile.getResponse(widgetId);      // ottieni il token
const isExpired = turnstile.isExpired(widgetId);    // verifica la scadenza
turnstile.reset(widgetId);                          // reimposta
turnstile.remove(widgetId);                         // rimuovi
turnstile.execute("#turnstile-container");         // esecuzione manuale

5) Integrazione con il modulo

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

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

Esempio di codice

<title>Turnstile Example</title>
  <!-- Connetti lo script Turnstile -->
  <script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
</head>
<body>
  <h1>Esempio di modulo con Turnstile</h1>

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

  <script>
    // Callback chiamato dopo il superamento del CAPTCHA
    function onTurnstileSuccess(token) {
      console.log("Token Turnstile ricevuto:", token);
      // Salva il token nel campo modulo nascosto (facoltativo)
      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);
    }

    // Invio del modulo
    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("Modulo inviato con successo e token verificato!");
      } else {
        alert("Errore di verifica del token Turnstile. Riprova.");
        // Reimposta il widget in modo che l'utente possa completare nuovamente il CAPTCHA
        turnstile.reset();
      }
    });
  </script>
</body>
</html>

6) Configura la parte server

Processo di verifica lato server:

Client: l'utente completa Turnstile sulla pagina → viene creato il token.
Il modulo viene inviato: il token insieme ai dati del modulo viene inviato al server.
Server: effettua una richiesta POST all'API Siteverify di Cloudflare con il token e il segreto.
Cloudflare: restituisce JSON con il risultato (success: true/false) e informazioni aggiuntive (action, hostname, tempo di completamento).
Server: decide se consentire o rifiutare l'azione dell'utente.

API Siteverify:

POST

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

Parametri della richiesta:

secret (obbligatorio): chiave segreta Turnstile dal pannello Cloudflare
response (obbligatorio): token ricevuto sul client
remoteip (facoltativo): indirizzo IP dell'utente (consigliato)
idempotency_key (facoltativo): UUID univoco per la protezione contro verifiche ripetute

Proprietà del token:

Lunghezza massima: 2048 caratteri
Valido per 5 minuti
Monouso
In caso di scadenza o nuova verifica, l'API restituirà l'errore timeout-or-duplicate

Esempio di verifica in 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);
}

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

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

if($result['success']){
    echo "Modulo inviato con successo!";
} else {
    echo "Errore di verifica: " . implode(', ', $result['error-codes']);
}
?>

Tutte le istruzioni dettagliate per l'installazione e la configurazione di Cloudflare Turnstile, inclusa l'integrazione client e server, esempi di codice, descrizioni degli errori e raccomandazioni sulla sicurezza, sono disponibili nella documentazione ufficiale di Cloudflare.

Possibili errori e debug

Parametri errati

Il CAPTCHA non viene visualizzato o restituisce errori come invalid-input-secret, missing-input-response, invalid-input-response. Verifica la validità di sitekey e secret key, nonché le impostazioni nel Dashboard di Cloudflare.

Timeout della soluzione

Il token è scaduto (valido per 300 secondi) o non è stato ricevuto in tempo. Assicurati di avere una connessione stabile e una corretta integrazione API.

Token vuoto o errato

Il parametro cf-turnstile-response è mancante o errato. Verifica il trasferimento del token al modulo e al server.

Risposta success=false

Il token è non valido, scaduto o già utilizzato. Ogni token può essere verificato una sola volta. Abilita il logging delle richieste e risposte Siteverify per l'analisi.

Verifiche della resilienza della protezione

Dopo l'integrazione assicurati che il sistema protegga davvero il sito dalle azioni automatizzate.

Prova a eseguire la richiesta senza risolvere il CAPTCHA: il server dovrebbe restituire success: false.

Esegui test di carico (ad esempio, utilizzando k6 o JMeter) a velocità superiori a 100+ richieste al secondo. Turnstile dovrebbe elaborare correttamente le richieste e il server dovrebbe verificare i token in modo stabile tramite l'API Siteverify.

Verifica la risposta ai token scaduti o reinviati: risposta API prevista: success: false e error-codes: ["timeout-or-duplicate"].

Suggerimenti di sicurezza e ottimizzazione

Verifica i token solo sul server, non chiamare mai l'API Siteverify dal frontend: ciò esporrà la tua chiave segreta.

Verifica i token solo sul server, non chiamare mai l'API Siteverify dal frontend: ciò esporrà la tua chiave segreta.

Utilizza variabili d'ambiente o un sistema di gestione dei segreti invece di memorizzare le chiavi nel codice.

Utilizza variabili d'ambiente o un sistema di gestione dei segreti invece di memorizzare le chiavi nel codice.

Verifica i campi aggiuntivi (<span class="font-bold">hostname</span>, <span class="font-bold">action</span>) per assicurarti che la richiesta provenga dal tuo sito web.

Verifica i campi aggiuntivi (hostname, action) per assicurarti che la richiesta provenga dal tuo sito web.

Utilizza HTTPS: tutte le chiamate a Siteverify devono essere effettuate tramite una connessione sicura.

Utilizza HTTPS: tutte le chiamate a Siteverify devono essere effettuate tramite una connessione sicura.

Implementa la gestione degli errori: quando l'API non è disponibile, mostra all'utente un messaggio chiaro senza rivelare dati interni.

Implementa la gestione degli errori: quando l'API non è disponibile, mostra all'utente un messaggio chiaro senza rivelare dati interni.

Limita l'uso della sitekey per domini.

Aggiungi link alla <span class="font-bold">Informativa sulla privacy</span> e ai <span class="font-bold">Termini di servizio di Cloudflare</span> al modulo se richiesto dalla tua organizzazione o dalla politica sulla privacy.

Aggiungi link alla Informativa sulla privacy e ai Termini di servizio di Cloudflare al modulo se richiesto dalla tua organizzazione o dalla politica sulla privacy.

Captcha supportati

Conclusione

Se ti è capitato un sito con un captcha o un altro sistema di protezione già installato e senza accesso al codice, nessun problema! È piuttosto facile capire quale tecnologia viene utilizzata. Per verificare che tutto funzioni correttamente, puoi usare il servizio di riconoscimento CapMonster Cloud in un ambiente di test isolato, così da assicurarti che il meccanismo di elaborazione dei token e la logica di verifica funzionino correttamente.

Nel caso di Cloudflare Turnstile, è sufficiente individuare il sistema, analizzarne il comportamento e assicurarsi che la protezione funzioni correttamente. Nell’articolo abbiamo mostrato come riconoscere Cloudflare Turnstile e dove trovare le istruzioni per la sua integrazione o riconfigurazione, in modo da poter mantenere la protezione in modo affidabile e controllarne il funzionamento.

Link utili

Documentazione Cloudflare Turnstile →

Registrati su Cloudflare →

Registrati su CapMonster Cloud →

Documentazione CapMonster Cloud (lavorare con Cloudflare Turnstile) →

Cos'è il CAPTCHA Cloudflare e come risolverlo con CapMonster Cloud →

Come Cloudflare rileva il traffico automatizzato: protezione dei siti web dai bot →

L'estensione browser di CapMonster Cloud è disponibile per Chrome e Firefox. La guida completa all'installazione e all'uso è disponibile qui.

Domande frequenti su Cloudflare Turnstile

Come risolvere Cloudflare Turnstile tramite l'API CapMonster Cloud?

Per risolvere Cloudflare Turnstile con CapMonster Cloud:

Invia una richiesta POST a https://api.capmonster.cloud/createTask con i seguenti parametri JSON:

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

clientKey: La tua chiave API CapMonster Cloud
task.type: TurnstileTask
task.websiteURL: L'URL della pagina in cui viene risolto il captcha
task.websiteKey: Chiave Turnstile site key. Scopri come trovarla.

L'API restituisce un taskId.

Interroga https://api.capmonster.cloud/getTaskResult con clientKey e taskId finché lo stato della risposta non diventa ready.

Quando l'attività è risolta, la risposta include un token e il corrispondente userAgent.

Passa entrambi i valori alla stessa sessione del browser che invierà il modulo.

Consulta la documentazione dell'attività Turnstile per dettagli ed esempi.

Quali modalità del widget Cloudflare Turnstile sono disponibili?

Cloudflare Turnstile supporta tre modalità del widget:

Managed: Turnstile decide se mostrare un controllo interattivo o far passare il visitatore silenziosamente in base al rischio.
Non-interactive: Funziona senza interazione dell'utente ma mostra comunque un widget visibile durante i controlli.
Invisible: Funziona anch'esso senza interazione dell'utente, ma il widget non viene mostrato al visitatore.

Come verifico un token Cloudflare Turnstile lato server come sviluppatore?

Una volta che il backend riceve il token Turnstile dal client:

Invialo tramite POST a https://challenges.cloudflare.com/turnstile/v0/siteverify con i parametri:

secret: La chiave segreta del widget dal pannello Cloudflare
response: Il token dal widget lato client
remoteip (opzionale): L'IP del visitatore
idempotency_key (opzionale): Un UUID generato per riprovare la validazione in sicurezza

L'endpoint accetta sia application/x-www-form-urlencoded che application/json.

Se il token ha superato la verifica, Cloudflare restituisce success: true.

Come passare un token Turnstile a un modulo in Playwright?

Usa page.evaluate() o un altro metodo a livello DOM per iniettare il token nel campo con [name="cf-turnstile-response"] prima dell'invio del modulo.

Tieni presente che alcune integrazioni si basano anche su callback o gestori JavaScript personalizzati. In tal caso, chiama la funzione di callback JS del widget (definita in data-callback) e passa il token ricevuto alla verifica lato server.

Cosa significa timeout-or-duplicate nella verifica server Turnstile?

L'errore timeout-or-duplicate di Turnstile siteverify di solito significa che il token è scaduto prima della verifica o è stato inviato più di una volta. I token Turnstile sono monouso e scadono dopo cinque minuti.

Per il debug degli errori:

Abilita la registrazione delle richieste a https://challenges.cloudflare.com/turnstile/v0/siteverify
Confronta l'ora di creazione del token con l'ora di verifica.
Verifica se il backend controlla lo stesso token due volte, ad esempio durante tentativi, reindirizzamenti o gestione di richieste duplicate.

Cloudflare Turnstile e CapMonster Cloud

Prezzi della soluzione Cloudflare Turnstile

Come risolvere Cloudflare Turnstile tramite CapMonster Cloud

Captcha supportati

Domande frequenti su Cloudflare Turnstile

Cloudflare Turnstile
e CapMonster Cloud