> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloudflare Turnstile Protocol Recognition API Integration Instructions

> Cloudflare Turnstile Captcha Service API guide - Ace Data Cloud

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](https://platform.acedata.cloud/console/applications) per ottenere il tuo API Token, da conservare per uso futuro.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

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](https://platform.acedata.cloud/console/coin).

> 📘 Documentazione completa: [Cloudflare Turnstile Protocol Recognition API →](https://platform.acedata.cloud/documents/captcha-token-turnstile)

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

```json theme={null}
{
  "token": "0.mNQ2f9uP6mQ0y3H5Q8bqO7iM......",
  "started_at": 1784885653.0,
  "finished_at": 1784885665.4,
  "elapsed": 12.4
}
```

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:

```python theme={null}
import requests

token = '{token}'

data = {
    'cf-turnstile-response': token
}

response = requests.post('https://react-turnstile.vercel.app', data=data)

if response.status_code == 200:
    print(response.text)
```

Inoltre, se desideri generare il codice di integrazione corrispondente, puoi semplicemente copiare il codice generato, ad esempio il codice CURL è il seguente:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/captcha/token/turnstile' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "website_key": "0x4AAAAAAADnPIDROrmt1Wwj",
  "website_url": "https://react-turnstile.vercel.app"
}'
```

Il codice di integrazione Python è il seguente:

```python theme={null}
import requests

url = "https://api.acedata.cloud/captcha/token/turnstile"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "website_key": "0x4AAAAAAADnPIDROrmt1Wwj",
    "website_url": "https://react-turnstile.vercel.app"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

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

```json theme={null}
{
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab"
}
```

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:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/captcha/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002"
}'
```

Durante l'elaborazione verrà restituito `status: processing`; al termine dell'elaborazione verrà restituito `status: ready` e il token:

```json theme={null}
{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "ready",
  "token": "0.mNQ2f9uP6mQ0y3H5Q8bqO7iM......"
}
```

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

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.