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.
La blacklist de l'extension CaptchaAI sert à exclure certains domaines du traitement automatique : sur les sites que vous y ajoutez, l'extension n'intercepte plus les défis CAPTCHA et laisse la page se comporter normalement. C'est l'outil pour cantonner l'extension à vos propres applications. La suite montre comment intégrer l'appel à l'API autour de cette logique, dans un workflow reproductible.
Quand exclure un site du traitement
Prenons une équipe QA d'un éditeur SaaS qui déploie l'extension sur plusieurs applications internes. Certaines de ces pages chargent un domaine d'analytique tiers qui affiche lui aussi un CAPTCHA. Sans liste d'exclusion, l'extension tenterait de le résoudre à chaque chargement : du bruit et des threads occupés pour rien. En l'ajoutant à la blacklist, vous gardez l'extension concentrée sur vos propres pages. La démarche s'inscrit aussi dans une logique RGPD : vous limitez les interactions automatisées aux systèmes pour lesquels vous avez une base légale claire.
| Type de domaine | Dans votre périmètre ? | Action |
|---|---|---|
| Vos applications internes | Oui | Laissez l'extension active |
| Domaine d'analytique tiers | Non | Ajoutez-le à la blacklist |
| Widget d'un partenaire embarqué | Selon le contrat | Vérifiez l'autorisation écrite |
Préparer un environnement de test isolé
Avant d'écrire la moindre ligne, verrouillez trois points :
- Isolez l'environnement de QA de la production.
- Stockez la clé CaptchaAI dans un coffre ou un secret d'intégration continue.
- Vérifiez que vos endpoints internes acceptent les requêtes de test.
Un environnement propre absorbe la plupart des incidents.
Encapsuler l'appel à l'API CaptchaAI
Isolez l'appel à CaptchaAI dans une fonction réutilisable. Elle reçoit la sitekey et l'URL de votre propre page, renvoie un token, et trace la durée ainsi que le code retour.
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 tâche ci-dessus vise Cloudflare Turnstile, mais le même contrat se transpose aux autres types : changez le type de tâche et conservez la boucle d'envoi puis d'interrogation.
Vérifier le token côté backend
Le token renvoyé doit être validé par votre propre backend avant toute opération métier. Cette étape empêche qu'une requête soit acceptée sur la foi d'un token périmé ou forgé. Appliquez-le toujours dans la même session que celle qui a déclenché le défi — même contexte de navigateur, même client HTTP, mêmes cookies. Un décalage de session reste la première cause de rejet après résolution.
Journaliser et observer les résolutions
Instrumentez les appels CAPTCHA pour alimenter vos tableaux de bord de QA et vos alertes :
- durée totale d'obtention du token ;
- code retour HTTP ;
- identifiant de tâche ;
- taille de la file d'attente interne.
Séparez ensuite les journaux par environnement — développement, préproduction, production — et corrélez les identifiants à votre traçage distribué (OpenTelemetry, par exemple). Un seul identifiant suffit alors à rejouer un scénario complet.
Liste de contrôle avant la mise en production
- Le périmètre reste strictement limité à vos propres applications ou à des sources autorisées.
- Les domaines hors périmètre sont ajoutés à la blacklist de l'extension.
- La clé CaptchaAI est stockée dans un secret d'intégration continue 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é couvre les erreurs transitoires.
- Les tests sont rejouables depuis votre intégration continue.
FAQ
À quoi sert la blacklist de l'extension CaptchaAI ?
Elle indique à l'extension les domaines sur lesquels elle ne doit pas intervenir. Sur ces sites, aucun défi CAPTCHA n'est intercepté ni résolu : la page se comporte comme si l'extension était absente.
Exclure un site réduit-il ma consommation de threads ?
Indirectement, oui. La facturation CaptchaAI repose sur les threads simultanés, pas sur le nombre de résolutions — l'offre BASIC ($15/mois, 5 threads) inclut des résolutions illimitées par thread. En écartant les domaines hors périmètre, vous évitez d'occuper un thread pour rien.
Comment vérifier qu'un site est bien exclu ?
Chargez la page concernée avec l'extension active et vérifiez qu'aucune tâche de résolution n'est déclenchée : ni requête vers l'API, ni token injecté. Vos journaux le confirment : un domaine bien exclu ne génère aucune entrée d'appel CAPTCHA.
Quels types de CAPTCHA l'extension peut-elle traiter ?
Les familles principales sont prises en charge : reCAPTCHA v2 et v3, Cloudflare Turnstile et Cloudflare Challenge, GeeTest v3, ainsi que les CAPTCHA image/OCR et les grilles d'images. CaptchaFox, Friendly Captcha et Lemin sont disponibles en bêta. En revanche, hCaptcha et FunCaptcha ne sont pas pris en charge.
Guides connexes
- Démarrage rapide avec CaptchaAI
- Résolution de CAPTCHA en environnement de test autorisé
- Tester l'endpoint de l'API sur vos formulaires
- Intégrer la résolution de 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.
