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 décrit ni l'automatisation de sites tiers, ni le contournement de protections, ni l'évasion d'anti-bot.
Un défi Shape Security ou Imperva n'est pas un simple CAPTCHA : c'est une couche de gestion de bots qui observe le comportement du navigateur avant de laisser passer la requête ou d'exiger une vérification. Pour automatiser un parcours qui la traverse sur votre propre application, cartographiez d'abord trois acteurs : qui déclenche le défi, qui produit le token et qui le vérifie.
Qu'est-ce qu'un défi Shape Security ou Imperva ?
Shape Security (aujourd'hui intégré à F5) et Imperva Advanced Bot Protection sont des systèmes de gestion de bots pensés pour l'entreprise. Contrairement à un widget reCAPTCHA que vous ajoutez vous-même, ils s'intercalent au niveau du réseau ou du CDN et évaluent chaque requête via l'empreinte du navigateur et des signaux comportementaux. Au-delà d'un certain score de risque, le système peut afficher un CAPTCHA : c'est à cette étape qu'une intégration comme CaptchaAI entre en jeu, sur les seules applications que vous exploitez.
Le modèle mental : trois acteurs
- Le front-end affiche le widget et déclenche le défi.
- Le fournisseur CAPTCHA génère le token après résolution.
- Votre backend vérifie le token côté serveur avant d'accorder l'accès.
Ce que vous maîtrisez sur votre application
Trois leviers sont entre vos mains ; le reste relève de la couche anti-bot :
- la configuration du widget CAPTCHA ;
- la vérification du token côté serveur ;
- la réponse appliquée selon le résultat.
Où intervient CaptchaAI
CaptchaAI ne « neutralise » pas la couche anti-bot : il résout uniquement le CAPTCHA qu'elle peut afficher quand il relève d'une famille prise en charge. Vous envoyez la tâche, interrogez le résultat et appliquez le token, avec une facturation par thread à partir du BASIC ($15/mois, 5 threads) et des résolutions illimitées.
| Famille de CAPTCHA | Prise en charge |
|---|---|
| reCAPTCHA v2 et v3 (widget, invisible, Enterprise) | Oui |
| Cloudflare Turnstile et Cloudflare Challenge | Oui |
| GeeTest v3, image/OCR, grilles d'images | Oui |
| hCaptcha, FunCaptcha (Arkose Labs) | Non |
| GeeTest v4 | À venir |
Exemple : vérifier le solde avant une exécution
Avant de lancer un lot en CI, vérifiez que votre solde couvre la charge prévue. Cet exemple interroge l'endpoint de solde :
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))
Observabilité et RGPD
Métriques à suivre
- durée d'obtention du token et code retour HTTP ;
- latence médiane de résolution et taux de réussite par famille.
Journaux et conformité
Corrélez chaque appel à votre traçage distribué (OpenTelemetry) et séparez les journaux par environnement. Appliquez la minimisation RGPD et déployez votre worker sur une région européenne (OVHcloud, Scaleway ou eu-west-3 à Paris).
Liste de contrôle avant la mise en production
- Le périmètre reste limité à vos propres applications ou à des sources autorisées.
- La clé CaptchaAI vit dans un secret CI, jamais dans le code source.
- Les durées d'appel et les codes retour sont tracés à chaque exécution.
- Un retry idempotent avec backoff borné couvre les erreurs transitoires.
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
| Token refusé après résolution | Session différente de celle du défi | Même contexte navigateur et mêmes cookies de bout en bout. |
ERROR_ZERO_BALANCE |
Solde inférieur au minimum par tâche | Rechargez et ajoutez une alerte de solde. |
ERROR_WRONG_USER_KEY |
Clé erronée ou espace parasite | Recopiez la clé et stockez-la comme secret CI. |
FAQ
CaptchaAI résout-il directement Shape Security ou Imperva ?
Non. CaptchaAI ne cible pas la couche de gestion de bots ; il résout le CAPTCHA qu'elle peut afficher lorsqu'il relève d'une famille prise en charge, sur une application que vous contrôlez.
CaptchaAI prend-il en charge hCaptcha ou FunCaptcha ?
Non, pas encore pris en charge. hCaptcha et FunCaptcha (Arkose Labs) ne figurent pas dans les familles gérées, et GeeTest v4 est annoncé « à venir ».
Que faire en cas d'erreur transitoire de l'API ?
Mettez en place un retry avec backoff exponentiel borné (trois tentatives, plafond à 30 s) et tracez chaque échec avec son identifiant de tâche. Si l'erreur persiste, vérifiez la configuration réseau et les quotas de votre clé.
Guides connexes
- Démarrage rapide CaptchaAI
- QA CAPTCHA en environnement autorisé
- Tester l'endpoint API sur vos formulaires
- Intégration CAPTCHA en CI
- Résoudre reCAPTCHA v2 via l'API
Bâtissez des workflows CAPTCHA reproductibles, du premier test à la production. – Obtenez votre clé CaptchaAI.
