Architecture de l'extension CaptchaAI : comment elle détecte les CAPTCHA

Périmètre sûr : ce guide vise vos propres applications et environnements (QA, préproduction, production) ou des systèmes pour lesquels vous disposez d'une autorisation écrite, jamais l'automatisation de sites tiers sans accord.

L'extension CaptchaAI détecte un CAPTCHA en observant la page : elle repère les marqueurs qu'un widget laisse dans le DOM — sitekey, iframe de défi, champ de réponse masqué comme g-recaptcha-response ou cf-turnstile-response — puis route la tâche vers le handler correspondant et réinjecte le token dans la même session. Comprendre cette chaîne élimine la plupart des surprises côté navigateur.

Ce que l'extension observe dans le DOM

Chaque famille de CAPTCHA laisse une signature reconnaissable. L'extension identifie la famille à partir de ces marqueurs, puis extrait les seuls paramètres utiles à la résolution.

Le parcours d'un token, du widget à votre backend

Trois acteurs suffisent à raisonner sur presque toutes les intégrations : le front qui affiche le widget, le fournisseur CAPTCHA (reCAPTCHA, Turnstile, GeeTest v3…) qui émet le token, et votre backend qui le valide côté serveur. L'extension s'insère entre les deux premiers et suit toujours le même cycle :

1. Repérer le widget et sa famille dans le DOM.
2. Extraire le sitekey, l'URL et l'action, puis envoyer la tâche au service.
3. Attendre le token, puis l'injecter dans le champ de réponse masqué.
4. Rejouer la même session — même contexte de navigateur, même jar de cookies — pour l'envoi du formulaire.
5. Laisser votre backend vérifier le token auprès du fournisseur.

L'étape 4 est la plus sensible : un token appliqué dans une autre session que celle du défi est la première cause de rejet. Côté application, vous gardez trois leviers : configuration du widget, vérification serveur du token, et réponse appliquée selon le score.

Vérifier le solde avant un lot

Exemple côté client, tiré de votre propre suite de tests, pour contrôler le solde avant de lancer un traitement par lots :

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))

Métriques et journalisation conformes RGPD

Instrumentez les appels CAPTCHA pour disposer de signaux exploitables :

• durée d'obtention du token et code retour HTTP ;
• identifiant de tâche et taille de la file d'attente ;
• taux de réussite du solveur et acceptation en aval, mesurés séparément.

Séparez les journaux par environnement et corrélez-les à votre traçage distribué (OpenTelemetry). Côté conformité, appliquez le principe RGPD de minimisation : ne journalisez que les métadonnées techniques utiles, aucune donnée personnelle superflue.

Erreurs fréquentes et correctifs

FAQ

Comment l'extension sait-elle quel type de CAPTCHA résoudre ?

Elle identifie la famille à partir des marqueurs du DOM — sitekey, iframe du fournisseur, champ masqué — puis choisit le handler adapté (reCAPTCHA v2/v3, Turnstile, GeeTest v3, image/OCR). Aucune indication manuelle n'est nécessaire dans les cas standards.

CaptchaAI prend-il en charge hCaptcha via l'extension ?

Non — hCaptcha et FunCaptcha (Arkose Labs) ne sont pas pris en charge. L'extension gère reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, les CAPTCHA image/OCR et en grille ; CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta) restent en bêta.

Combien coûte l'usage à grande échelle ?

La facturation repose sur les threads, pas sur le nombre de résolutions : chaque plan inclut des résolutions illimitées par thread. Le plan BASIC ($15/mois, 5 threads) suffit à des tests réguliers ; augmentez les threads selon votre débit.

Que faire si aucun widget n'est détecté ?

Le CAPTCHA se charge sans doute dans une iframe ou après un délai. Attendez le rendu complet, puis relancez le repérage. Vérifiez aussi qu'il n'est pas masqué derrière un bandeau de consentement cookies ou un écran de connexion.

Guides connexes

1. Le démarrage rapide CaptchaAI
2. La QA CAPTCHA en environnements autorisés
3. Tester l'endpoint API sur vos formulaires
4. Intégrer la résolution CAPTCHA en CI
5. Résoudre reCAPTCHA v2 via l'API

Passez du schéma à une intégration qui tient en production. – Créez votre compte CaptchaAI.