Une extension de navigateur qui résout les CAPTCHA fait une chose précise : elle récupère un token résolu, puis l'injecte dans le champ caché que la page attend — g-recaptcha-response pour reCAPTCHA, cf-turnstile-response pour Turnstile — sans jamais quitter la session qui a déclenché le défi. Tout le reste n'est que tuyauterie. Comprendre le rôle exact du content script, c'est éviter la moitié des tickets de support liés à l'extension.
Périmètre sûr : ce guide s'applique uniquement à 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 décrit ni l'automatisation de sites tiers, ni aucune technique d'anti-détection sur des protections que vous ne contrôlez pas.
Le modèle mental : qui déclenche, qui résout, qui vérifie
Posez d'abord le modèle mental : trois acteurs suffisent à raisonner sur la quasi-totalité des intégrations.
- Le front-end affiche le widget et expose un champ de réponse vide.
- Le fournisseur du CAPTCHA (Google pour reCAPTCHA, Cloudflare pour Turnstile) émet le token une fois le défi résolu.
- Votre backend valide ce token côté serveur avant d'accorder l'accès.
L'extension s'insère entre les deux premiers : elle obtient le token via l'API CaptchaAI, puis le dépose dans le champ attendu.
Le rôle exact du content script
Un content script est un script que l'extension injecte dans le contexte de la page visitée. Son travail tient en trois étapes : lire les paramètres du défi (sitekey, URL, action éventuelle), demander la résolution à CaptchaAI, puis écrire le token reçu dans le champ caché et déclencher le callback attendu par le formulaire.
Le point sensible tient en une phrase : le token doit être appliqué dans la même session que celle qui a déclenché le défi — même contexte de navigateur, mêmes cookies, même origine. Un token valide injecté dans une autre session reste la cause la plus fréquente de rejet après résolution.
Dépannage des rejets les plus fréquents
Les échecs viennent presque toujours de la session ou du compte, rarement du token :
| Problème | Cause probable | Correctif |
|---|---|---|
| Token refusé après résolution | Injection dans une autre session que celle du défi | Conservez le même contexte de navigateur, les mêmes cookies et la même origine |
| Champ de réponse resté vide | Callback non déclenché après l'injection | Déclenchez le callback attendu par le widget |
ERROR_ZERO_BALANCE |
Solde inférieur au minimum par tâche | Rechargez le compte et ajoutez une alerte de solde |
Exemple de code
Avant même de brancher l'extension, vérifiez que votre clé API répond et que le solde est suffisant. Ce court appel, tiré de votre propre suite de tests, suffit :
import os
import requests
API_KEY = os.environ['CAPTCHAAI_KEY']
def get_balance() -> float:
resp = requests.post(
'https://api.captchaai.com/getBalance',
json={'clientKey': API_KEY},
timeout=15,
)
resp.raise_for_status()
return float(resp.json().get('balance', 0))
Liste de contrôle avant la mise en production
- Le token est injecté dans la même session que celle qui a déclenché le défi.
- Le périmètre reste 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 appels CAPTCHA sont tracés (durée, code retour, identifiant de tâche) pour chaque exécution.
- La vérification du token reste effectuée côté serveur, avec un retry idempotent et un backoff exponentiel borné pour les erreurs transitoires.
FAQ
Pourquoi un token valide est-il parfois rejeté après résolution ?
Dans la quasi-totalité des cas, le token a été injecté dans une session différente de celle qui a déclenché le défi. Un token reCAPTCHA ou Turnstile est lié à la session qui l'a demandé : vérifiez que le contexte de navigateur, les cookies et l'origine restent identiques entre l'obtention du token et l'envoi du formulaire.
L'extension dispense-t-elle de vérifier le token côté serveur ?
Non. L'extension fournit un token, elle ne valide rien. La vérification du token auprès du fournisseur doit rester une étape serveur, suivie de votre logique métier selon le score. Traiter l'injection côté client comme une preuve d'accès est une faille classique.
Ce guide concerne-t-il l'automatisation de sites tiers ?
Non. Tous les exemples portent sur vos propres applications ou sur des environnements autorisés par écrit. Si votre projet implique une source externe, validez d'abord les conditions d'utilisation et la base juridique — notamment vos obligations RGPD pour les données personnelles.
La facturation dépend-elle du nombre de CAPTCHA injectés ?
Non. CaptchaAI facture au thread simultané, pas au CAPTCHA résolu : chaque offre inclut un nombre de threads fixe et des résolutions illimitées. L'offre BASIC ($15/mois, 5 threads) couvre déjà un poste de QA ; les volumes plus importants montent simplement en threads.
Guides connexes
- Démarrage rapide : votre première résolution
- Résolution de CAPTCHA en QA sur des environnements autorisés
- Tester l'endpoint de l'API sur vos formulaires web
- Gérer les CAPTCHA dans votre pipeline CI
- Résoudre reCAPTCHA v2 via l'API
Passez d'un schéma théorique à une intégration CaptchaAI qui tient en production. — Obtenez votre clé CaptchaAI.
