Périmètre sûr : ce guide s'applique exclusivement à vos propres applications 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.
L'extension Chrome de CaptchaAI résout les CAPTCHA directement dans le navigateur, sans réécrire la logique de chaque page. Bien intégrée, elle devient une brique stable de vos workflows ; mal cadrée, elle génère l'essentiel de la charge de support. La clé est de la traiter comme un workflow reproductible : profil dédié, appel à l'API, vérification côté backend et gestion du token après la résolution.
Ce que l'extension prend en charge
| Type de CAPTCHA | Statut |
|---|---|
| reCAPTCHA v2 et v3 | Pris en charge |
| Cloudflare Turnstile et Challenge | Pris en charge |
| GeeTest v3 | Pris en charge |
| Image/OCR et grilles d'images | Pris en charge |
| CaptchaFox, Friendly Captcha, Lemin | Bêta |
| hCaptcha, FunCaptcha (Arkose Labs) | Non pris en charge |
| GeeTest v4 | À venir |
La facturation repose sur les threads, pas sur le nombre de résolutions : le plan BASIC ($15/mois, 5 threads) suffit pour valider une intégration.
Le déroulé en cinq étapes
- Capturez uniquement les paramètres attendus :
sitekey, URL de votre page, éventuel proxy. - Envoyez la tâche à l'API et traitez tout statut inattendu comme une erreur à journaliser.
- Interrogez le résultat à intervalle régulier, avec un plafond de temps par tâche.
- Appliquez le token dans la session qui a déclenché le défi — même contexte, même cookie jar.
- Suivez la latence, les retries et l'acceptation en aval : une résolution réussie n'est pas un workflow réussi.
Préparer un profil de navigateur dédié
Ne chargez jamais l'extension dans votre profil Chrome quotidien. Créez un profil isolé (--user-data-dir) réservé à l'automatisation, avec l'extension chargée via --load-extension : l'environnement reste rejouable et à l'abri de vos cookies personnels. Vérifiez aussi que la clé CaptchaAI vit dans un coffre ou un secret CI, et que vos endpoints internes acceptent le trafic de test.
Exemple : créer une tâche Turnstile en Node.js
Voici un exemple en français commenté qui appelle l'API :
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;
}
La fonction crée la tâche et renvoie un taskId ; interrogez ensuite le résultat, puis appliquez le token. Le contrat est identique dans tout langage compatible HTTP.
Vérifier le token côté backend
Le token renvoyé doit être vérifié par votre propre backend avant toute opération métier : c'est la frontière de confiance de votre application. Aucune requête ne doit passer sur la base d'un token périmé ou contrefait, jamais depuis le navigateur.
Instrumenter et journaliser les appels
Instrumentez chaque appel : durée d'obtention du token, code retour HTTP, identifiant de tâche. Corrélez ces identifiants à votre traçage distribué (par exemple OpenTelemetry). Côté conformité, appliquez le principe RGPD de minimisation : ne journalisez pas de données personnelles superflues. Que vos workers tournent sur OVHcloud, Scaleway ou une région AWS eu-west-3 (Paris), gardez la même discipline.
Liste de contrôle avant la mise en production
- Le périmètre est 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 durées d'appel et les codes retour sont tracés à chaque exécution.
- Une stratégie de retry idempotent avec backoff exponentiel borné est en place.
- La résolution et la soumission ont lieu dans le même contexte de navigateur.
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec des espaces ou mauvais compte. | Recopiez la clé et stockez-la comme secret CI. |
ERROR_ZERO_BALANCE |
Solde inférieur au minimum par tâche. | Rechargez le solde et ajoutez une alerte. |
ERROR_PAGEURL / ERROR_BAD_PARAMETERS |
Paramètre requis manquant ou mal formé. | Revalidez l'URL et le sitekey contre le HTML réel. |
| Token refusé après résolution | Token appliqué dans une session différente. | Gardez la résolution et la soumission dans le même contexte. |
FAQ
L'extension fonctionne-t-elle avec Selenium et Playwright ?
Oui. Vous chargez l'extension via --load-extension dans un profil dédié, avec Selenium comme avec Playwright ou Puppeteer. Le pilote démarre le navigateur avec le profil isolé, et l'extension traite le défi.
Pourquoi mon token est-il refusé après la résolution ?
Presque toujours parce qu'il a été appliqué dans une session différente de celle qui a déclenché le défi. Conservez le même contexte de navigateur et le même cookie jar entre la résolution et la soumission.
Combien coûte l'utilisation à grande échelle ?
Le coût suit le nombre de threads concurrents, pas le nombre de résolutions : chaque plan offre des résolutions illimitées par thread. Les boucles de mauvais paramètres restent le vrai poste de coût.
Guides connexes
- Le démarrage rapide CaptchaAI
- La QA CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- Intégrer la résolution CAPTCHA dans votre CI
- Résoudre reCAPTCHA v2 via l'API
Améliorez la qualité de vos workflows CAPTCHA avec une approche méthodique et reproductible. – Obtenez votre clé CaptchaAI.
