Périmètre sûr : Ce guide s'applique exclusivement à vos propres applications, environnements de QA, de préproduction ou de production, ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni le contournement de protections, ni l'évasion d'anti-bot.
Un Durable Object conserve l'état de votre flux entre deux requêtes : c'est précisément là que la résolution d'un CAPTCHA doit s'insérer proprement. L'objectif de ce guide est concret : brancher CaptchaAI sur une étape protégée par un CAPTCHA (le plus souvent Cloudflare Turnstile ou Cloudflare Challenge) de façon assez stable pour tourner sans surveillance, en CI, dans un cron ou derrière une file d'attente interne. Vous obtenez un token, vous l'injectez dans la même session, et vous tracez chaque appel pour repérer les régressions avant vos utilisateurs.
Ce que l'état des Durable Objects change pour vos CAPTCHAs
Une intégration qui semble triviale dans un notebook casse souvent dès qu'elle tourne sans surveillance. Un Durable Object coordonne un état à instance unique — parfait pour dédupliquer les tâches et sérialiser les appels — mais il n'est pas fait pour stocker des tokens à l'avance : un CAPTCHA se résout à la demande. Une intégration solide repose sur trois piliers :
- Une latence prévisible et des modes d'échec propres, même sans surveillance.
- Une API cohérente sur les familles reCAPTCHA, Cloudflare et GeeTest v3.
- Une facturation par thread — à partir de BASIC ($15/mois, 5 threads), résolutions illimitées — qui ne punit pas la montée en charge.
Architecture cible avec Cloudflare Durable Objects
Votre Worker (et son Durable Object) appelle CaptchaAI via HTTPS pour récupérer un token, puis l'injecte dans votre formulaire ou votre route d'API. Le Durable Object sert de point de coordination : il évite qu'une même tâche soit soumise deux fois et centralise la file d'attente interne. Tracer chaque étape facilite la détection de régressions.
Gestion des secrets et de la configuration
La clé CaptchaAI ne doit jamais vivre dans le code source. Quelques règles suffisent, que vous hébergiez sur OVHcloud, Scaleway ou une région AWS eu-west-3 (Paris) :
- Stockez la clé dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret CI.
- Montez-la en variable d'environnement au runtime, jamais en dur dans un fichier versionné.
- Faites-la transiter par le gestionnaire de secrets de la plateforme, pas par le dépôt Git.
Exemple de code : créer une tâche Turnstile
Appel HTTP côté serveur, dans votre propre service. Ne capturez que les paramètres attendus (sitekey, URL, action, proxy éventuel). La fonction renvoie un taskId ; interrogez ensuite getTaskResult (environ 15 s d'attente, puis toutes les 5 s, avec un plafond ferme par tâche) jusqu'à obtention du token, que vous injectez dans la session qui a déclenché le défi.
import fetch from 'node-fetch';
const API_KEY = process.env.CAPTCHAAI_KEY;
export async function createTurnstileTask(siteKey, pageUrl) {
const res = await fetch('https://api.captchaai.com/createTask', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
clientKey: API_KEY,
task: {
type: 'TurnstileTaskProxyless',
websiteURL: pageUrl,
websiteKey: siteKey,
},
}),
});
const data = await res.json();
return data.taskId;
}
Observabilité et journalisation
Quel que soit le langage, instrumentez les appels CAPTCHA : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente interne alimentent vos tableaux de bord et vos alertes. Séparez les journaux par environnement et corrélez les identifiants à votre traçage distribué (par exemple OpenTelemetry) pour rejouer un scénario à partir d'un identifiant unique. Côté RGPD, journalisez les métriques techniques, jamais le contenu du formulaire ni les données personnelles : minimisez ce que vous conservez. Des journaux bien découpés divisent par deux le temps de diagnostic en cas d'incident.
Mesurer la réussite : les indicateurs à suivre
Les résultats varient selon l'environnement, le volume et le moment de la journée ; traitez toute cible comme un seuil que vous fixez. Suivez quatre signaux : la latence d'obtention du token (Turnstile se résout généralement en moins de 10 s), le taux de réussite de résolution (p. ex. ≥ 95 %), l'acceptation en aval dans la même session et le coût par résolution acceptée. Un écart entre résolution et acceptation en aval trahit presque toujours un problème de session.
Liste de contrôle avant mise en production
- Le périmètre est strictement limité à vos propres applications ou à des sources autorisées.
- La clé CaptchaAI est stockée dans un secret CI ou un coffre, jamais dans le code source.
- Les durées d'appel et les codes retour sont tracés pour chaque exécution, sans données personnelles.
- Le token est injecté dans la même session que celle qui a déclenché le défi.
- Une stratégie de retry idempotent est en place : trois tentatives, backoff exponentiel borné, plafond à 30 s.
- Les tests sont rejouables et reproductibles depuis votre intégration continue.
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace parasite ou mauvais compte. | Recopiez la clé depuis le tableau de bord et stockez-la en secret CI. |
ERROR_KEY_DOES_NOT_EXIST |
Mauvaise clé de projet ou clé ayant été renouvelée. | Vérifiez la clé active dans le tableau de bord et faites tourner le secret. |
ERROR_ZERO_BALANCE |
Solde du compte sous le minimum requis. | Rechargez et ajoutez une alerte de solde. |
CAPCHA_NOT_READY en boucle |
Interrogation trop rapide ou plafond de temps dépassé. | Attendez 15 s, interrogez toutes les 5 s, bornez la durée par tâche. |
| Token refusé après résolution | Token injecté dans une session différente du défi. | Gardez résolution et soumission dans le même contexte navigateur ou la même session HTTP. |
FAQ
Faut-il stocker le token CAPTCHA dans l'état du Durable Object ?
Non. Un CAPTCHA se résout à la demande. Le Durable Object coordonne la file et déduplique les tâches ; il ne doit pas servir de réserve de tokens, car ceux-ci ont une durée de vie courte et deviennent vite invalides.
CaptchaAI prend-il en charge hCaptcha derrière Cloudflare ?
Non — pas encore pris en charge. CaptchaAI résout en revanche Cloudflare Turnstile, Cloudflare Challenge, reCAPTCHA v2 et v3, GeeTest v3, ainsi que les CAPTCHA image/OCR et en grille. Si votre page bascule vers un type non couvert, adaptez le workflow plutôt que de forcer une résolution.
Pourquoi le token Turnstile est-il refusé après résolution ?
Presque toujours parce qu'il est injecté dans une session différente de celle du défi. Gardez le même contexte navigateur, le même client HTTP et le même cookie jar entre la résolution et la soumission. Vérifiez aussi que l'URL de la page et le sitekey envoyés correspondent au HTML en direct.
Que faut-il journaliser sans exposer de données personnelles ?
Conservez l'identifiant de tâche, la durée de résolution, le code retour HTTP et la taille de la file d'attente. N'enregistrez ni le contenu des champs ni les identifiants de l'utilisateur final : minimisez les données personnelles et vérifiez vos obligations RGPD. Ces métriques techniques suffisent à diagnostiquer un incident.
Guides connexes
- Démarrage rapide CaptchaAI
- QA CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- Intégration CAPTCHA en continu (CI)
- Résoudre reCAPTCHA v2 via l'API
Fiabilisez vos workflows CAPTCHA avec une intégration méthodique et reproductible. — Obtenez votre clé CaptchaAI.
