Skip to main content
Questo documento introduce una guida all’integrazione dell’API di riconoscimento del protocollo Cloudflare Turnstile, che consente agli utenti di completare la verifica senza dover riconoscere e selezionare il captcha Turnstile, semplicemente inviando la Website Key per ottenere la decodifica automatica in background.

​
Processo di richiesta

Per utilizzare l’API di riconoscimento del protocollo Cloudflare Turnstile, prima di tutto vai al Ace Data Cloud Console per ottenere il tuo API Token, da conservare per uso futuro. Se non hai ancora effettuato il login o la registrazione, verrai automaticamente reindirizzato alla pagina di login che ti invita a registrarti e accedere; una volta completato, verrai riportato automaticamente alla pagina corrente. Un API Token è sufficiente per accedere a tutti i servizi della piattaforma, senza necessità di richiederne uno per ogni servizio. La prima richiesta riceverà un credito gratuito, per un’esperienza senza costi; se il credito è insufficiente, puoi ricaricare il saldo generale nella console.
📘 Documentazione completa: Cloudflare Turnstile Protocol Recognition API →

​
Utilizzo di base

Iniziamo a comprendere il modo di utilizzo di base, che consiste nell’inserire l’URL del sito web che deve elaborare il captcha Turnstile, per ottenere il risultato elaborato. È necessario prima passare un campo website_url, il nostro sito di esempio è: https://react-turnstile.vercel.app, dobbiamo ottenere il website_key dalla pagina website_url, aprendo questa pagina, premendo F12 per accedere alla console e cercando globalmente cf-turnstile nella pagina Element, dove possiamo trovare l’elemento contenitore che ospita il Turnstile, il cui valore della stringa corrispondente a data-sitekey è il valore di website_key. Le intestazioni della richiesta impostate includono:
  • accept: il formato di risposta desiderato, qui impostato su application/json, ovvero formato JSON.
  • authorization: la chiave per chiamare l’API, che può essere selezionata direttamente dopo la richiesta.
Inoltre, è stato impostato il corpo della richiesta, che include:
  • website_url: l’URL del sito web che deve elaborare il captcha.
  • website_key: l’identificatore della chiave del sito nel Cloudflare Turnstile (sitekey).
  • action: parametro opzionale, da passare solo se il sito target ha impostato un action personalizzato per il componente Turnstile.
  • cdata: parametro opzionale, da passare solo se il sito target ha impostato un cData personalizzato per il componente Turnstile.
Cliccando sul pulsante “Try” possiamo effettuare un test, e otteniamo il seguente risultato:
Il risultato restituito contiene diversi campi, descritti come segue:
  • token, il risultato della verifica dopo l’elaborazione del captcha Cloudflare Turnstile.
  • started_at, finished_at: il tempo di inizio e di completamento della richiesta, timestamp Unix (secondi, float).
  • elapsed: il tempo totale impiegato per l’elaborazione (secondi).
Possiamo vedere che abbiamo ottenuto il risultato della verifica del captcha Turnstile, che possiamo utilizzare per un POST o per simulare l’invio al sito target, utilizzabile una sola volta, con una validità di 120s, si consiglia di utilizzarlo entro 60s. Durante l’invio, di solito si invia questo token come parametro cf-turnstile-response al sito target, il codice Python per chiamare la verifica del token è il seguente:
Inoltre, se desideri generare il codice di integrazione corrispondente, puoi semplicemente copiare il codice generato, ad esempio il codice CURL è il seguente:
Il codice di integrazione Python è il seguente:

​
Modalità asincrona (async)

Per impostazione predefinita, l’API è bloccante e sincrona: una richiesta attenderà fino al completamento dell’elaborazione del token prima di restituire una risposta. Se stai effettuando un cambio di risolutori multipli (multi-solver rotation) e desideri “ricevere immediatamente il task_id dopo aver inviato il compito, per poi programmare altri risolutori e tornare in seguito a leggere il risultato”, puoi passare async: true nel corpo della richiesta. Passando async: true, l’interfaccia restituirà immediatamente un task_id, senza bloccare l’attesa:
Se desideri controllare attivamente il progresso, puoi utilizzare il task_id per interrogare POST /captcha/tasks (si consiglia ogni 3~5 secondi). Questa interfaccia non attiverà o accelererà l’elaborazione del compito; anche se non interroghi, perdi la connessione o esci dal client, il server continuerà a elaborare:
Durante l’elaborazione verrà restituito status: processing; al termine dell’elaborazione verrà restituito status: ready e il token:
Informazioni di fatturazione: in modalità asincrona, la creazione di un compito e la lettura dello stato “in elaborazione” non comportano costi; il costo viene addebitato una sola volta quando il client legge il risultato con successo per la prima volta (coerente con il comportamento attuale e il prezzo della modalità sincrona). Il server gestirà autonomamente l’avanzamento del compito, ma non addebiterà costi anticipati se il backend completa prima. Se il compito non viene completato con successo entro 120 secondi, verrà terminato con un HTTP 504 timeout, senza costi. /captcha/tasks non è responsabile dell’avanzamento del compito.
Nota: Cloudflare Turnstile non supporta attualmente l’uso di proxy (Bring Your Own Proxy), quindi questa interfaccia non accetta il parametro proxy; se fornito, restituirà 400 invalid_proxy.

​
Gestione degli errori

Quando chiami l’API, se si verifica un errore, l’API restituirà il codice di errore e le informazioni corrispondenti. Ad esempio:
  • 400 token_mismatched：Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
  • 400 invalid_proxy：Richiesta non valida, il proxy non è supportato per questo tipo di captcha.
  • 401 invalid_token：Non autorizzato, token di autorizzazione non valido o mancante.
  • 429 too_many_requests：Troppe richieste, hai superato il limite di frequenza.
  • 500 api_error：Errore interno del server, qualcosa è andato storto sul server.

​
Esempio di risposta errore

​
Conclusione

Attraverso questo documento, hai compreso come utilizzare l’API di riconoscimento del protocollo Cloudflare Turnstile per consentire agli utenti di non dover riconoscere e selezionare il captcha Turnstile, ma di completare la verifica semplicemente inviando la Website Key per una decodifica automatica in background. Speriamo che questo documento possa aiutarti a integrare e utilizzare meglio questa API. Se hai domande, non esitare a contattare il nostro team di supporto tecnico.