Périmètre sûr : ce guide s'applique exclusivement à vos propres applications, à vos environnements de test autorisés, ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni la neutralisation de protections, ni l'évasion d'anti-bot.
L'extension CaptchaAI résout un CAPTCHA par onglet actif. Pour traiter plusieurs pages en même temps, vous épinglez chaque flux dans son propre onglet et vous laissez l'extension travailler en parallèle. La vraie contrainte n'est pas le nombre d'onglets, mais le nombre de résolutions simultanées que votre plan autorise, c'est-à-dire vos threads.
Pourquoi épingler plusieurs onglets pour résoudre en parallèle
Un onglet épinglé conserve son contexte, ses cookies et sa session tant que le navigateur reste ouvert : idéal pour un worker qui enchaîne des résolutions sans surveillance.
La facturation de CaptchaAI est basée sur les threads : chaque onglet qui résout un CAPTCHA occupe un thread, libéré pour l'onglet suivant dès la résolution terminée. Le plan BASIC ($15/mois, 5 threads) autorise donc cinq résolutions simultanées. Dimensionnez vos onglets sur ce chiffre, pas sur la RAM de la machine.
Préparer le profil et l'environnement de l'extension
Avant d'ouvrir le premier onglet, isolez l'environnement. Utilisez un profil navigateur dédié et chargez-y l'extension CaptchaAI. Stockez la clé API dans un coffre ou un secret CI, jamais en clair dans un script.
Pour un worker persistant hébergé chez OVHcloud ou Scaleway, fixez le profil sur un volume durable afin que les onglets épinglés survivent aux redémarrages.
Encapsuler l'appel à l'API CaptchaAI
Centralisez la logique de résolution dans une fonction réutilisable. Elle prend en paramètre le sitekey et l'URL de la page de votre propre application, retourne un token, puis trace la durée et le code retour. Vous rejouez ainsi un scénario identique dans chaque onglet.
Le contrat submit/poll reste identique d'une famille à l'autre ; seul le type de tâche change.
Exemple : créer une tâche Turnstile
L'exemple suivant crée une tâche Turnstile et renvoie son identifiant, à interroger pour récupérer le token :
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;
}
Vérifier le token côté backend
Le token renvoyé doit être validé par votre propre backend avant toute opération métier : aucune requête ne doit être acceptée sur la base d'un token périmé ou contrefait. Appliquez-le dans la session qui a déclenché le défi, même contexte navigateur et même client HTTP.
Dépannage des résolutions en parallèle
Ces symptômes couvrent la majorité des tickets sur ce type d'intégration.
| Symptôme | Cause probable | Correctif |
|---|---|---|
| Token refusé après résolution | Token appliqué dans une session différente du défi | Rejouez le défi et le token dans le même onglet. |
ERROR_ZERO_BALANCE |
Solde insuffisant pour la tâche | Rechargez le solde et ajoutez une alerte. |
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace ou mauvais compte | Recopiez la clé et stockez-la en secret CI. |
| Onglets bloqués en attente | Plus d'onglets actifs que de threads disponibles | Réduisez les onglets ou montez de plan. |
Liste de contrôle avant la mise en production
- Le périmètre est limité à vos propres applications ou à des sources autorisées.
- Le nombre d'onglets épinglés actifs ne dépasse pas le nombre de threads de votre plan.
- La clé CaptchaAI est stockée dans un secret CI ou un coffre, jamais dans le code source.
- Les durées d'appel, les codes retour et l'identifiant d'onglet sont tracés pour chaque exécution.
- Un retry idempotent avec backoff exponentiel borné est en place.
Observabilité et journalisation des résolutions parallèles
Instrumentez chaque appel pour obtenir des métriques exploitables : durée totale d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente interne. Avec plusieurs onglets actifs, ajoutez l'identifiant de l'onglet à chaque ligne de journal, sans quoi deux résolutions concurrentes deviennent illisibles.
Séparez les journaux par environnement et corrélez-les à votre traçage distribué. Côté RGPD, ne journalisez que les données nécessaires au diagnostic.
FAQ
Combien d'onglets puis-je résoudre en même temps ?
Autant que votre plan compte de threads. Chaque résolution en cours occupe un thread ; le plan BASIC ($15/mois, 5 threads) permet cinq résolutions simultanées, et les onglets excédentaires patientent qu'un thread se libère.
L'extension fonctionne-t-elle en mode headless ?
L'extension a besoin d'un contexte navigateur réel avec son profil. Utilisez un contexte persistant (par exemple launchPersistentContext avec Playwright) plutôt qu'un mode headless strict.
Que faire si un token est refusé après la résolution ?
Vérifiez la cohérence de session : le token doit être appliqué dans le même onglet que le défi. Contrôlez aussi qu'il n'a pas expiré et que le sitekey et l'URL correspondent à la page réelle.
L'extension prend-elle en charge hCaptcha ?
Non, hCaptcha n'est pas encore pris en charge, pas plus que FunCaptcha (Arkose Labs). L'extension couvre en revanche reCAPTCHA v2/v3, Turnstile, Challenge, GeeTest v3 et les CAPTCHA image.
Guides connexes
- Le guide de 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
Fiabilisez vos workflows CAPTCHA avec une approche méthodique et reproductible. – Obtenez votre clé CaptchaAI.
