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.
Une base de connaissances interne autour de l'extension CaptchaAI tient la route quand vous traitez l'extension comme un workflow reproductible, pas comme un bouton à activer. Quatre éléments méritent d'être documentés : l'état du compte, le profil de navigateur, le choix du handler CAPTCHA et le comportement après résolution. C'est là que naissent les confusions et que vous retirez le plus de charge de support.
Les quatre éléments à documenter
| Élément | À documenter |
|---|---|
| État du compte | Le plan et ses threads : CaptchaAI facture par thread concurrent, résolutions illimitées par thread (par exemple BASIC à $15/mois, 5 threads). |
| Profil de navigateur | Profil dédié, extensions et cookies conservés, pour un état identique sur chaque poste et runner CI. |
| Handler CAPTCHA | Le type attendu : reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile, GeeTest v3, image/OCR ou grille. |
| Comportement après résolution | Où le token est injecté et ce qui valide le succès côté page. |
Architecture cible
Votre composant interne appelle CaptchaAI en HTTPS pour récupérer un token, puis l'injecte dans votre formulaire ou votre route d'API. Règle d'or : appliquez le token dans la même session que celle du défi — même contexte de navigateur, même client HTTP, même cookie jar. Une session dépareillée est la première cause de rejet.
Soumission puis interrogation du résultat
- Ne capturez que l'utile : sitekey, URL de la page, action, proxy optionnel. Le reste crée de fausses pistes.
- Envoyez la tâche à
https://ocr.captchaai.com/in.phpavecjson=1; tout statut différent de1est une erreur à journaliser. - Interrogez le résultat sur
https://ocr.captchaai.com/res.php: attendez 15 s, puis toutes les 5 s, plafond de 120 s par tâche. - Appliquez le token dans la même session, puis validez l'acceptation.
Secrets et exemple de code
La clé API CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou un secret de CI, jamais dans le code, et se monte en variable d'environnement. Sur des workers OVHcloud, Scaleway ou en région eu-west-3 (Paris), le principe reste le même.
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))
Le même appel se transpose vers Node.js ou Go, sans clé en clair.
Observabilité et indicateurs
Instrumentez chaque appel : durée d'obtention du token, code retour HTTP et identifiant de tâche. Fixez des cibles, pas des garanties — les résultats varient selon l'environnement et le volume : latence p95 sous 60 s pour les CAPTCHA à token, taux de réussite d'au moins 95 % par type, acceptation de bout en bout d'au moins 95 % après injection. Côté conformité, minimisez les données personnelles dans les logs et vérifiez vos obligations RGPD.
Liste de contrôle avant merge
- Périmètre limité à vos applications ou sources autorisées.
- Clé API en coffre ou secret de CI, jamais dans le code.
- Durées d'appel et codes retour tracés à chaque exécution.
- Token appliqué dans la même session que le défi.
- Retry idempotent, plafonné à trois tentatives.
Dépannage
| Problème | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Espace parasite ou mauvais compte. | Recopiez la clé, stockez-la en secret de CI. |
ERROR_ZERO_BALANCE |
Solde sous le minimum par tâche. | Rechargez et ajoutez une alerte de seuil. |
ERROR_PAGEURL / ERROR_BAD_PARAMETERS |
Paramètre requis absent ou mal formé. | Revalidez l'URL, le sitekey et les champs du type. |
| Token refusé après résolution | Token appliqué dans une autre session. | Gardez résolution et envoi dans le même contexte. |
FAQ
Que documenter pour chaque type de CAPTCHA ?
Notez les paramètres d'entrée exacts, l'endpoint de soumission et le champ où le token est injecté, avec un exemple capturé sur votre page.
Où stocker la clé API CaptchaAI en toute sécurité ?
Dans un coffre ou un secret de CI, monté en variable d'environnement au runtime. Jamais dans le dépôt, un fichier versionné ni les logs.
CaptchaAI prend-il en charge hCaptcha ?
Non, pas encore pris en charge. Il résout reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, l'image/OCR, les grilles et BLS, avec CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta). FunCaptcha n'est pas pris en charge ; GeeTest v4 est à venir.
Guides connexes
- le guide de démarrage rapide CaptchaAI
- la QA CAPTCHA en environnements autorisés
- tester l'endpoint API sur vos formulaires
- l'intégration CAPTCHA en CI
- résoudre reCAPTCHA v2 via l'API
Documentez votre intégration une fois, mesurez-la, et la longue traîne de tickets CAPTCHA quitte votre file de support. – Obtenez votre clé CaptchaAI.
