Skip to main content
Cet article présente une documentation sur l’API de reconnaissance du protocole Cloudflare Turnstile, qui permet aux utilisateurs de valider sans avoir à reconnaître et à cliquer sur le captcha Turnstile, en soumettant simplement la clé du site Web pour un décodage automatique en arrière-plan.

​
Processus de demande

Pour utiliser l’API de reconnaissance du protocole Cloudflare Turnstile, commencez par obtenir votre jeton API sur le tableau de bord Ace Data Cloud pour le garder en réserve. Si vous n’êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion pour vous inviter à vous inscrire et à vous connecter, après quoi vous serez automatiquement renvoyé à la page actuelle. Un jeton API suffit pour appeler tous les services de la plateforme, sans avoir à en demander un pour chaque service. La première demande vous donnera un quota gratuit pour une expérience sans frais ; si le quota est insuffisant, vous pouvez recharger le solde général dans le tableau de bord.
📘 Documentation complète : API de reconnaissance du protocole Cloudflare Turnstile →

​
Utilisation de base

Tout d’abord, comprenez la méthode d’utilisation de base, qui consiste à entrer l’URL du site Web nécessitant le traitement du captcha Turnstile pour obtenir le résultat traité. Vous devez d’abord transmettre un champ website_url, notre site d’exemple est : https://react-turnstile.vercel.app, nous devons obtenir la website_key sur la page website_url, ouvrez d’abord cette page, appuyez sur F12 pour accéder à la console, effectuez une recherche globale sur la page Element pour cf-turnstile, vous trouverez l’élément conteneur portant Turnstile, où la chaîne correspondant à data-sitekey est la valeur de website_key. Les en-têtes de requête définis incluent :
  • accept : le format de réponse souhaité, ici rempli avec application/json, c’est-à-dire au format JSON.
  • authorization : la clé pour appeler l’API, que vous pouvez sélectionner directement après la demande.
De plus, le corps de la requête comprend :
  • website_url : l’URL du site Web nécessitant le traitement du captcha.
  • website_key : l’identifiant de clé de site dans Cloudflare Turnstile.
  • action : paramètre optionnel, à transmettre uniquement si le site cible a défini une action personnalisée pour le composant Turnstile.
  • cdata : paramètre optionnel, à transmettre uniquement si le site cible a défini un cData personnalisé pour le composant Turnstile.
Cliquez sur le bouton « Essayer » pour effectuer le test, et nous obtenons le résultat suivant :
Le résultat de retour contient plusieurs champs, décrits comme suit :
  • token, le résultat de validation après le traitement de la tâche de captcha Cloudflare Turnstile.
  • started_at, finished_at : le temps de début et de fin du traitement de cette demande, en timestamp Unix (secondes, flottant).
  • elapsed : le temps total de traitement (secondes).
Nous pouvons voir que nous avons obtenu le résultat de validation du captcha Turnstile, que nous pouvons ensuite utiliser pour un envoi POST ou une soumission simulée au site cible, à usage unique, avec une durée de validité de 120s, il est conseillé de l’utiliser dans les 60s. Lors de la soumission, le token est généralement envoyé en tant que paramètre cf-turnstile-response au site cible, le code Python correspondant à l’appel de validation du token est le suivant :
Si vous souhaitez également générer le code d’intégration correspondant, vous pouvez le copier directement, par exemple, le code CURL est le suivant :
Le code d’intégration Python est le suivant :

​
Mode asynchrone (async)

Par défaut, l’API est synchrone et bloquante : une demande attendra jusqu’à ce que le traitement du token soit terminé avant de renvoyer une réponse. Si vous effectuez une rotation de plusieurs solveurs (multi-solver rotation) et souhaitez « obtenir immédiatement le task_id après avoir soumis la tâche, puis planifier d’autres solveurs et revenir plus tard pour lire le résultat », vous pouvez passer async: true dans le corps de la requête. En passant async: true, l’interface renverra immédiatement un task_id sans bloquer l’attente :
Pour vérifier activement l’avancement, vous pouvez utiliser ce task_id pour interroger POST /captcha/tasks (il est conseillé de le faire toutes les 3 à 5 secondes). Cette interface ne déclenchera ni n’accélérera le traitement de la tâche ; même si vous ne consultez pas, si vous perdez la connexion ou quittez le client, le serveur continuera à traiter :
En cours de traitement, cela renverra status: processing ; une fois le traitement terminé, cela renverra status: ready et le token :
Explication de la facturation : en mode asynchrone, la création de tâches et la lecture de l’état « en cours de traitement » ne sont pas facturées ; le client est facturé une fois lors de la première lecture d’un résultat réussi (conforme au comportement actuel et au prix du mode synchrone). Le serveur avancera la tâche de manière autonome, mais ne facturera pas à l’avance simplement parce que le traitement en arrière-plan est terminé. Si la tâche n’est pas réussie dans les 120 secondes, elle sera arrêtée avec un HTTP 504 timeout, sans facturation. /captcha/tasks n’est pas responsable de l’avancement des tâches.
Remarque : Cloudflare Turnstile ne prend pas encore en charge les proxies apportés (Bring Your Own Proxy), donc cette interface n’accepte pas le paramètre proxy ; si ce paramètre est passé, cela renverra 400 invalid_proxy.

​
Gestion des erreurs

Lors de l’appel de l’API, si une erreur se produit, l’API renverra le code d’erreur et les informations correspondantes. Par exemple :
  • 400 token_mismatched : Mauvaise demande, probablement en raison de paramètres manquants ou invalides.
  • 400 invalid_proxy : Mauvaise demande, le proxy n’est pas pris en charge pour ce type de captcha.
  • 401 invalid_token : Non autorisé, jeton d’autorisation invalide ou manquant.
  • 429 too_many_requests : Trop de demandes, vous avez dépassé la limite de taux.
  • 500 api_error : Erreur interne du serveur, quelque chose s’est mal passé sur le serveur.

​
Exemple de réponse d’erreur

​
Conclusion

Grâce à ce document, vous avez compris comment utiliser l’API de reconnaissance du protocole Cloudflare Turnstile pour permettre aux utilisateurs de ne pas avoir à reconnaître et cliquer sur le captcha Turnstile, mais simplement de soumettre la clé du site pour réaliser un décodage automatique en arrière-plan et compléter la vérification. Nous espérons que ce document vous aidera à mieux intégrer et utiliser cette API. Si vous avez des questions, n’hésitez pas à contacter notre équipe de support technique.