Périmètre sûr : ce guide s'applique exclusivement à vos propres applications, à vos environnements de QA, de préproduction ou de production, ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne porte ni sur l'automatisation de sites tiers, ni sur l'évasion des protections anti-bot de services que vous ne possédez pas.
Un token CAPTCHA résolu ne sert à rien tant qu'il n'atteint pas le bon emplacement de votre formulaire. Il n'existe que trois destinations valides selon le type de widget : la textarea cachée, la fonction de callback, ou le corps de la requête envoyée à votre backend de QA. Cette référence indique laquelle utiliser et la fenêtre de temps à respecter.
Où injecter le token selon le type de CAPTCHA
Identifiez ce que la résolution vous rend — token ou cookie — et où le widget l'attend.
| Type de CAPTCHA | Résultat obtenu | Emplacement d'injection | Méthode |
|---|---|---|---|
| reCAPTCHA v2 / Enterprise | chaîne de token | textarea g-recaptcha-response |
champ caché |
| reCAPTCHA v2 invisible / v3 | chaîne de token | g-recaptcha-response + callback |
champ caché + JS |
| Cloudflare Turnstile | chaîne de token | champ cf-turnstile-response |
champ caché |
| Cloudflare Challenge | cookie cf_clearance |
cookies de session | cookie jar |
Ne mélangez jamais les noms de champ : un token reCAPTCHA écrit dans cf-turnstile-response est ignoré.
Méthode 1 : écrire le token dans le champ caché
Pour reCAPTCHA v2, le widget génère un champ caché nommé g-recaptcha-response. Vous écrivez le token dedans avant de soumettre : c'est la voie la plus directe en QA et celle qui couvre la majorité des intégrations. Turnstile suit la même logique avec cf-turnstile-response. Aucun callback n'est nécessaire si le formulaire valide seulement la présence d'une valeur non vide.
Méthode 2 : déclencher le callback global
Certaines intégrations — reCAPTCHA invisible et v3 notamment — n'avancent pas parce qu'une valeur figure dans la textarea : elles attendent l'appel d'une fonction de callback. Si votre intégration en définit un (par exemple onSolve), écrivez d'abord le token dans le champ caché, puis appelez-le avec la même valeur. Le formulaire progresse alors comme après une résolution humaine.
Exemple JavaScript pour reCAPTCHA v2 :
// Dans votre suite de tests QA interne.
function injectToken(token) {
document.getElementById('g-recaptcha-response').value = token;
if (typeof window.onSolve === 'function') {
window.onSolve(token);
}
document.querySelector('form#protected').submit();
}
Si vous ignorez le nom du callback, lisez l'attribut data-callback du widget et appelez la fonction correspondante sur window.
Méthode 3 : poster le token vers votre backend de QA
Quand votre formulaire est traité par une requête HTTP classique plutôt que par du JavaScript, aucun navigateur n'est requis. Ajoutez le token comme champ du corps (g-recaptcha-response ou cf-turnstile-response selon le type) et envoyez un POST vers votre endpoint de préproduction — la voie la plus rapide à scripter en CI. Pour Cloudflare Challenge, vous transmettez non pas un token mais le cookie cf_clearance, placé dans le jar de session avant d'appeler votre page.
Fenêtre de validité : injectez puis soumettez sans attendre
Les fenêtres ci-dessous sont des ordres de grandeur observés côté widget. Ne conservez jamais un token pour le rejouer plus tard : résolvez à la demande, injectez, soumettez.
| Type de CAPTCHA | Injectez et soumettez dans |
|---|---|
| reCAPTCHA v2 | 120 s |
| reCAPTCHA v3 | 120 s |
| Cloudflare Turnstile | 300 s (5 minutes) |
| Cookie Cloudflare Challenge | 15–30 minutes |
Une simple pause de débogage avant submit() suffit à faire expirer le token : c'est la première cause d'échec silencieux.
Observabilité et journalisation des appels
Instrumentez les appels CAPTCHA pour obtenir des métriques exploitables : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file interne. Corrélez ces identifiants à votre traçage distribué (par exemple OpenTelemetry) pour rejouer un scénario à partir d'un identifiant unique. Côté conformité, gardez le réflexe RGPD : les fixtures de préproduction ne doivent contenir aucune donnée personnelle réelle.
Scénario : préproduction hébergée chez OVHcloud
Prenons une équipe qui teste sa page de connexion sur une préproduction hébergée chez OVHcloud, avec un formulaire reCAPTCHA v2. Dans la CI, chaque exécution résout un token via l'API CaptchaAI, l'écrit dans g-recaptcha-response, déclenche le callback puis soumet — en moins de deux minutes, dans la fenêtre de validité. Une latence vers une région comme eu-west-3 (Paris) reste une illustration : mesurez la vôtre.
Dépannage de l'injection de token
| Problème | Cause | Correctif |
|---|---|---|
| Le token est ignoré | mauvais nom de champ (g-recaptcha-response utilisé pour Turnstile) |
utilisez cf-turnstile-response pour Turnstile |
| Rien ne se passe après l'injection | le formulaire n'est jamais soumis | déclenchez la soumission après avoir écrit le token |
| reCAPTCHA invisible non validé | le callback n'est pas appelé | retrouvez la fonction via data-callback et appelez-la |
| Cookie non transmis aux sous-domaines | domaine sans point initial | déclarez .exemple.com avec le point |
| Token expiré au moment de l'envoi | délai trop long entre injection et soumission | soumettez immédiatement après l'injection |
Liste de contrôle avant exécution
- Le périmètre est limité à vos propres applications ou à des sources autorisées.
- La clé CaptchaAI est dans un secret de CI ou un coffre, jamais dans le code source.
- Le nom du champ correspond au type (
g-recaptcha-responseoucf-turnstile-response). - Les durées d'appel et les codes retour sont tracés à chaque exécution.
- Un retry idempotent couvre les erreurs transitoires, et les tests restent rejouables en CI.
FAQ
Suffit-il d'écrire le token dans le champ caché, ou faut-il aussi appeler le callback ?
Cela dépend du widget. Pour un reCAPTCHA v2 standard, écrire la valeur dans g-recaptcha-response suffit. Pour un reCAPTCHA invisible ou v3, le formulaire attend en plus l'appel d'un callback : sans lui, le token est présent mais jamais traité. L'attribut data-callback vous indique dans quel cas vous êtes.
Combien de temps un token reste-t-il valide avant la soumission ?
De l'ordre de 120 s pour reCAPTCHA v2 et v3, jusqu'à 300 s pour Turnstile, et de 15 à 30 minutes pour un cookie Cloudflare Challenge. Traitez ces durées comme des plafonds et soumettez au plus tôt.
Comment sécuriser ma clé CaptchaAI dans une intégration continue ?
Placez-la dans le gestionnaire de secrets de votre CI ou un coffre dédié, puis injectez-la comme variable d'environnement à l'exécution. Elle ne doit jamais apparaître dans le dépôt ni les journaux.
Ce guide couvre-t-il l'automatisation de sites que je ne possède pas ?
Non. Tous les exemples portent sur vos propres applications ou sur des environnements de test autorisés par écrit. Si votre projet implique une source externe, vérifiez d'abord ses conditions d'utilisation et votre base juridique.
Guides connexes
- Le guide de démarrage rapide CaptchaAI
- Faire de la QA CAPTCHA en environnements autorisés
- Tester l'endpoint de l'API sur vos formulaires
- Intégrer la résolution CAPTCHA en CI
- Résoudre reCAPTCHA v2 via l'API
- Résoudre Cloudflare Turnstile via l'API
Fiabilisez la transmission de vos tokens CAPTCHA dans vos propres environnements avec une méthode reproductible. – Obtenez votre clé CaptchaAI.
