Périmètre sûr : ce guide couvre uniquement vos propres applications, vos environnements de QA et de préproduction, et les sources pour lesquelles vous disposez d'un accord de collecte écrit. Il ne décrit ni l'automatisation de sites tiers non autorisés, ni aucune technique d'évasion d'anti-bot.
Un relevé de SERP features n'a de valeur que s'il est complet. Dès qu'un défi CAPTCHA interrompt une exécution planifiée, la série temporelle prend un trou — et ce trou devient une fausse alerte : « on a perdu l'extrait optimisé jeudi » alors que le job avait simplement été bloqué. Voici comment brancher CaptchaAI sur un pipeline de surveillance autorisé pour que la collecte reste continue.
Ce que coûte réellement une exécution interrompue
Un job coupé au milieu ne produit pas seulement moins de lignes : il produit des lignes biaisées, puisque les requêtes de fin de cycle sont systématiquement celles qui manquent. Part de voix, position zéro, blocs « Autres questions posées » : tous les indicateurs dérivés héritent du biais. La gestion des défis est une condition de fiabilité de la donnée, à instrumenter comme telle.
Définir le périmètre avant d'écrire la moindre ligne
Avant l'architecture, tranchez la question juridique. Trois configurations sont légitimes : vous êtes propriétaire de l'application qui affiche le défi, vous l'exploitez pour un client qui a autorisé l'intégration par écrit, ou vous collectez une source sous accord signé. En dehors de ces trois cas, n'engagez pas le pipeline.
Pour les équipes en France, en Belgique ou au Québec, ajoutez une revue RGPD des journaux : un relevé de SERP features n'a besoin d'aucune donnée personnelle. Identifiant de tâche, URL cible, durées — rien de plus.
Architecture : trois responsabilités séparées
Trois blocs indépendants. L'ordonnanceur déclenche les cycles — quotidien pour le suivi concurrentiel, horaire en période de forte volatilité. Le worker de collecte exécute les appels HTTP et détecte un défi. Le résolveur appelle CaptchaAI, récupère le token et le rend au worker, qui le réinjecte dans la même session.
Ce dernier point est la principale source d'échec en production : un token obtenu dans un contexte navigateur puis appliqué dans un autre est refusé. Même contexte, même client HTTP, même jar de cookies.
Côté capacité, CaptchaAI facture au thread simultané, pas à la résolution : un thread traite un défi, puis enchaîne le suivant. Un cycle nocturne à faible concurrence tient sur BASIC ($15/mois, 5 threads) ; une agence qui parallélise plusieurs comptes clients sur la même fenêtre passe généralement sur ADVANCE ($90/mois, 50 threads). Dimensionnez sur la concurrence maximale, pas sur le volume mensuel.
Exemple de code
Exemple côté client de votre propre suite de tests :
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 clé ne doit jamais apparaître dans le dépôt : stockez-la dans un secret CI ou un coffre, et faites échouer le build si la variable d'environnement manque.
Les indicateurs qui rendent le pipeline défendable
Les chiffres ci-dessous reposent sur des mesures observées et des retours d'utilisateurs. Les résultats varient selon l'environnement, le volume et le moment de la journée. Fixez vos seuils après deux semaines d'observation.
| Indicateur | Ce qu'il révèle | Seuil de départ raisonnable |
|---|---|---|
| Temps de résolution médian | Santé de l'intégration hors retry | Médiane par type de défi |
| Temps de résolution P95 | Calibration de vos timeouts | Timeout aligné sur P95 × 2 |
| Taux de réussite du résolveur | Justesse des paramètres envoyés | Alerter sur une baisse de 5 points |
| Acceptation en bout de chaîne | Token accepté dans la même session | Écart proche de zéro avec le taux précédent |
| Cycles complets par jour | Continuité réelle de la série temporelle | Aucun cycle partiel toléré |
L'écart entre les deux taux de réussite est le signal le plus utile : quand il se creuse, le problème n'est pas la résolution mais la réinjection du token.
Observabilité et journalisation
Instrumentez chaque appel avec quatre champs : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file interne. Corrélez-les à votre traçage distribué — OpenTelemetry fait l'affaire — pour rejouer un cycle depuis un identifiant unique.
Séparez les journaux par environnement. Que vos workers tournent chez OVHcloud, Scaleway ou dans une région européenne de votre cloud, gardez la même convention de nommage : un incident se diagnostique plus vite quand les trois environnements se lisent avec la même requête.
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
| Le token est refusé après résolution | Session différente de celle du défi | Réinjectez dans le même contexte navigateur ou client HTTP |
| Erreurs transitoires en rafale | Absence de backoff, tentatives non bornées | Trois tentatives, doublement du délai, plafond à 30 s |
| Les cycles s'allongent progressivement | Concurrence supérieure aux threads du plan | Mesurez la file interne, réévaluez le plan |
| Paramètres refusés à l'envoi | Sitekey ou URL de page obsolètes | Recapturez-les depuis le HTML de la page cible |
Liste de contrôle avant la mise en production
- Le périmètre est limité à vos applications ou à des sources sous accord écrit.
- La clé CaptchaAI vit dans un secret CI ou un coffre, jamais dans le code source.
- Durées et codes retour sont tracés pour chaque exécution.
- Le retry est idempotent, borné, avec backoff exponentiel.
- Les journaux ne contiennent aucune donnée personnelle.
- Les cycles sont rejouables depuis votre intégration continue.
FAQ
Combien de threads prévoir pour une surveillance quotidienne ?
Dimensionnez sur la concurrence, pas sur le volume : comptez les défis traités simultanément au pic du cycle. Un cycle séquentiel de quelques centaines de requêtes tient sur BASIC ($15/mois, 5 threads) ; une exécution parallélisée sur plusieurs comptes clients demande davantage.
CaptchaAI prend-il en charge hCaptcha pour ce type de pipeline ?
Non, hCaptcha n'est pas pris en charge, pas plus que FunCaptcha (Arkose Labs). GeeTest v4 est annoncé comme à venir. Les familles couvertes sont reCAPTCHA v2 et v3, Cloudflare Turnstile et Cloudflare Challenge, GeeTest v3, les CAPTCHA image/OCR et les grilles d'images, auxquelles s'ajoutent CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta).
Comment journaliser sans créer de risque RGPD ?
Ne collectez que ce qui sert au diagnostic : identifiant de tâche, URL cible, durée, code retour. Aucune adresse IP d'utilisateur final, aucun contenu de formulaire. Fixez une durée de rétention explicite et documentez-la : c'est la première chose qu'un auditeur demande.
Le type de défi change sur une page : faut-il réécrire le pipeline ?
Non. La boucle envoi/interrogation du résultat reste identique ; seul le type de tâche change. C'est l'intérêt d'isoler le résolveur dans son module : un changement de famille se traite en un paramètre, pas en refonte.
Guides connexes
- Le démarrage rapide CaptchaAI
- La résolution CAPTCHA en environnement autorisé
- Tester l'endpoint API sur vos formulaires
- Intégrer la gestion des défis en CI
- Résoudre reCAPTCHA v2 via l'API
Vos relevés méritent une série temporelle sans trous. – Ouvrez votre compte CaptchaAI.
