Périmètre sûr : ce guide couvre uniquement vos propres applications, vos environnements de QA ou de production, ou des sources pour lesquelles vous disposez d'une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni l'évasion des protections anti-bot.
L'extension CaptchaAI reste stable avec Undetected ChromeDriver à une seule condition : la traiter comme un profil de navigateur persistant, et non comme un simple clic d'activation. Chargée depuis un profil dédié, réutilisé entre les exécutions, elle cesse de poser l'essentiel des problèmes d'intégration.
Restent quatre points à stabiliser : l'état du compte, le profil du navigateur, le choix du type de CAPTCHA et l'injection du token dans la bonne session.
Comment l'extension s'articule avec un profil persistant
Undetected ChromeDriver démarre Chrome depuis un répertoire de profil (--user-data-dir) et charge l'extension dépaquetée (--load-extension). Ce profil conserve la clé API, les préférences et les cookies. Repartir d'un profil neuf à chaque lancement force l'extension à se reconfigurer et rend les runs non déterministes : gardez un profil par rôle, réutilisé d'une exécution à l'autre.
Injecter le token dans la même session
Le rejet de token après résolution vient presque toujours du même écart : le token est produit dans un contexte et appliqué dans un autre. La séquence fiable tient en trois temps :
- Résolvez et soumettez le formulaire dans le même contexte — mêmes cookies, même session.
- Attendez 15 s, puis interrogez le résultat toutes les 5 s, plafond de 120 s par tâche.
- Mesurez séparément la réussite de la résolution et celle du workflow.
Exemple d'appel côté serveur
Pour un flux qui appelle l'API en parallèle de l'extension — Turnstile, par exemple — la tâche reste minimale :
import fetch from 'node-fetch';
const API_KEY = process.env.CAPTCHAAI_KEY;
export async function createTurnstileTask(siteKey, pageUrl) {
const res = await fetch('https://api.captchaai.com/createTask', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
clientKey: API_KEY,
task: {
type: 'TurnstileTaskProxyless',
websiteURL: pageUrl,
websiteKey: siteKey,
},
}),
});
const data = await res.json();
return data.taskId;
}
Le même contrat vaut pour tous les types : changez le type de tâche, gardez la boucle.
Observabilité et journalisation
Instrumentez les appels CAPTCHA : durée d'obtention du token, code retour HTTP, identifiant de tâche, taille de la file d'attente. Séparez les journaux par environnement et corrélez les identifiants à votre traçage distribué (OpenTelemetry) pour rejouer un scénario complet depuis un identifiant unique.
Combien ça coûte à l'échelle
La facturation CaptchaAI repose sur les threads, pas sur les résolutions : chaque plan inclut des résolutions illimitées par thread sur le mois. Une équipe QA francophone sur Scaleway ou OVHcloud démarre souvent avec BASIC ($15/mois, 5 threads), puis passe à STANDARD ($30/mois, 15 threads) quand le pool grossit. Le coût dépendant des threads concurrents, ce sont les retrys et les mauvais paramètres qui érodent les marges.
Liste de contrôle avant la mise en production
| Vérification | Pourquoi | Réglage |
|---|---|---|
| Périmètre autorisé | Éviter toute automatisation non autorisée. | Vos propres applications ou des sources autorisées uniquement. |
| Profil par worker | Prévenir les verrous de fichiers concurrents. | Un --user-data-dir dédié, réutilisé entre les exécutions. |
| Clé en secret | Ne jamais exposer la clé. | Coffre ou secret de CI, jamais dans le code. |
| Retry borné | Contenir les erreurs transitoires. | Backoff exponentiel plafonné, rejouable en CI. |
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace parasite ou mauvais compte. | Recopiez la clé depuis le tableau de bord, stockez-la en secret de CI. |
ERROR_ZERO_BALANCE |
Solde sous le minimum par tâche. | Rechargez le solde et ajoutez une alerte au tableau de bord. |
| Token rejeté après résolution | Token appliqué dans une autre session que celle du défi. | Résolvez et soumettez dans le même contexte de navigateur. |
| L'extension ne se charge pas | Profil recréé à neuf ou dossier non dépaqueté. | Pointez --load-extension vers l'extension dépaquetée, --user-data-dir vers un profil persistant. |
FAQ
Pourquoi l'extension CaptchaAI ne se charge-t-elle pas au lancement de Chrome ?
Le plus souvent, --load-extension pointe vers un dossier non dépaqueté, ou le profil est recréé à neuf à chaque run. Vérifiez que l'extension est dépaquetée sur disque et que --user-data-dir désigne un profil persistant.
Faut-il un profil de navigateur distinct pour chaque worker parallèle ?
Oui. Deux instances Chrome sur le même --user-data-dir se disputent des verrous de fichiers et se corrompent. Provisionnez un répertoire par worker, réutilisé entre ses exécutions.
CaptchaAI résout-il hCaptcha ou FunCaptcha avec cette configuration ?
Non — hCaptcha et FunCaptcha (Arkose Labs) ne sont pas pris en charge, quelle que soit la méthode. CaptchaAI couvre reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, l'image/OCR, les grilles et BLS, plus CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta).
Guides connexes
- Le démarrage rapide CaptchaAI
- La QA CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- Intégration continue et gestion des CAPTCHA
- Résoudre reCAPTCHA v2 via l'API
Fiabilisez vos workflows CAPTCHA avec une méthode reproductible. – Obtenez votre clé CaptchaAI.
