Périmètre sûr : ce guide s'applique à vos propres applications et aux environnements (QA, préproduction, production) pour lesquels vous disposez d'une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni le contournement de protections.
Dans l'extension CaptchaAI, un reCAPTCHA v2 se traite de deux manières : soit vous récupérez un token prêt à injecter (le champ g-recaptcha-response), soit la résolution passe par la grille d'images à cliquer. Le token suffit quand la case « Je ne suis pas un robot » se valide seule ; la grille intervient lorsque Google déclenche la sélection d'images. Savoir lequel s'applique à votre page élimine la plupart des faux diagnostics côté extension.
L'erreur classique consiste à traiter l'extension comme un simple bouton à activer, alors que c'est un workflow de navigateur reproductible : état du compte, profil, mode de résolution retenu, puis comportement après injection sur la page cible.
Token ou grille : ce qui les distingue
Les deux modes aboutissent au même résultat côté serveur — un g-recaptcha-response valide — mais ne se déclenchent pas dans les mêmes conditions ni avec la même latence.
| Critère | Token | Grille d'images |
|---|---|---|
| Déclenchement | Case validée seule | Défi visuel imposé par Google |
| Traitement | Chaîne signée récupérée directement | Résolution image par image |
| Latence | Quelques secondes | Un peu plus longue |
Quel mode pour quelle page
Retenez le token quand votre intégration est pilotée par du code — suite de tests, worker planifié ou endpoint interne : votre composant appelle CaptchaAI via HTTPS, récupère le token et l'injecte dans votre formulaire ou votre route d'API. La grille, elle, s'impose quand la page force le défi visuel, souvent après plusieurs tentatives ou selon le score de risque de Google ; dans l'extension, ce basculement est automatique. Prévoyez alors une latence supérieure et un plafond de temps par tâche.
Architecture de référence
La clé CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret CI ; le déploiement la monte en variable d'environnement au runtime, jamais en clair dans le code — même logique pour un worker hébergé sur OVHcloud en région eu-west-3.
Exemple côté client, tiré de votre propre suite de tests :
import os
import requests
API_KEY = os.environ['CAPTCHAAI_KEY']
def submit_recaptcha_v2(sitekey: str, page_url: str) -> str:
payload = {
'clientKey': API_KEY,
'task': {
'type': 'NoCaptchaTaskProxyless',
'websiteURL': page_url,
'websiteKey': sitekey,
},
}
resp = requests.post('https://api.captchaai.com/createTask', json=payload, timeout=30)
resp.raise_for_status()
return resp.json()['taskId']
Ajoutez des tests d'intégration sur vos endpoints critiques et publiez, par environnement, la latence, le taux de réussite et la consommation de threads.
Observabilité et journalisation
Quel que soit le langage, instrumentez les appels CAPTCHA : durée totale d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente interne. Ces signaux alimentent vos alertes de QA.
Séparez les journaux par environnement et corrélez les identifiants à votre traçage distribué (OpenTelemetry, par exemple) : vous rejouerez un scénario complet à partir d'un seul identifiant, ce qui réduit fortement le temps de diagnostic. Côté conformité, minimisez les données personnelles journalisées et vérifiez vos obligations RGPD avant de conserver des identifiants de session.
Liste de contrôle avant fusion
| Vérification | Attendu |
|---|---|
| Périmètre | Vos propres applications ou des sources autorisées |
| Clé CaptchaAI | Dans un secret CI ou un coffre, jamais dans le code |
| Mode de résolution | Token ou grille identifié pour la page cible |
| Traçage | Durées d'appel et codes retour à chaque exécution |
| Erreurs transitoires | Retry idempotent en place |
| Tests | Rejouables depuis votre intégration continue |
FAQ
Faut-il choisir manuellement entre le token et la grille ?
Non. L'extension bascule automatiquement selon ce que reCAPTCHA v2 renvoie : un token direct quand la case se valide seule, une résolution de grille quand Google impose le défi visuel. Dans les deux cas, votre code reçoit un g-recaptcha-response à injecter.
Pourquoi mon token est-il refusé après l'injection ?
La cause la plus fréquente est une session différente : le token doit être injecté dans le même contexte de navigateur (mêmes cookies) que celui qui a déclenché le défi. Vérifiez aussi que le sitekey et l'URL correspondent exactement à la page live.
La grille d'images coûte-t-elle plus cher que le token ?
Non. La facturation CaptchaAI se fait par thread simultané, avec des résolutions illimitées par thread ; le plan BASIC ($15/mois, 5 threads) est le point d'entrée. Une grille occupe un thread un peu plus longtemps qu'un token, mais aucun surcoût par type de CAPTCHA ne s'applique. Pour lisser les incidents, plafonnez les tentatives à trois avec backoff exponentiel et alertez sur les échecs terminaux.
Guides connexes
- Démarrage rapide CaptchaAI
- QA CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- Intégration CAPTCHA en continu
- Résoudre reCAPTCHA v2 via l'API
Fiabilisez vos workflows reCAPTCHA v2 avec une approche méthodique et reproductible. – Obtenez votre clé CaptchaAI.
