Périmètre sûr : ce guide s'applique à vos propres applications, à vos environnements de QA, de préproduction ou de production, et aux sources pour lesquelles vous disposez d'une autorisation écrite. Il ne couvre ni l'automatisation de sites tiers, ni les techniques d'anti-détection.
Un flux de collecte planifié qui rencontre un défi CAPTCHA n'a pas besoin d'un opérateur humain à 3 h du matin : il a besoin d'une étape de résolution appelée comme n'importe quel autre service HTTP, avec son propre délai d'expiration, son propre budget de retry et ses propres alertes. C'est le rôle de CaptchaAI dans un pipeline type SEC EDGAR — agrégation de dépôts réglementaires ou de publications officielles — sur des sources que vous exploitez ou qui vous ont autorisé. Restent quatre sujets : l'architecture, la robustesse, l'observabilité et le dimensionnement des threads.
Ce qu'un défi CAPTCHA change dans un flux planifié
Une collecte manuelle absorbe un CAPTCHA sans difficulté : quelqu'un clique. Une collecte planifiée s'arrête net, et le coût réel n'est pas le défi lui-même mais la fenêtre de fraîcheur manquée en aval. Trois propriétés du job changent de statut, et votre orchestrateur doit savoir les exprimer.
| Propriété | Avant le défi CAPTCHA | Après |
|---|---|---|
| Durée d'exécution | Stable, prévisible | Variable, à borner par un timeout |
| Réussite | Binaire | Taux à suivre source par source |
| Échec | Global | Partiel : une source sur douze peut tomber sans faire échouer le job |
Scénario : un agrégateur de dépôts réglementaires
Prenons l'équipe data d'un éditeur fintech lyonnais. Chaque nuit à 2 h, des workers déployés sur des instances Scaleway en région parisienne interrogent une dizaine de portails de publication réglementaire, dont deux couverts par un contrat de licence de données. L'un des deux vient d'activer Cloudflare Turnstile sur son formulaire de recherche. Résultat : la source ne remonte plus, et personne ne le voit avant l'ouverture des bureaux.
La correction ne consiste pas à réécrire le pipeline : isolez l'étape de recherche derrière un appel de résolution, donnez-lui un budget de temps explicite, faites remonter son taux de réussite dans le tableau de bord de la collecte. Côté conformité, minimisez les données personnelles conservées et vérifiez vos obligations RGPD, journaux de débogage compris.
Architecture : où brancher la résolution CAPTCHA
L'orchestrateur — Airflow, Prefect, une simple entrée cron — reste maître du déroulé. CaptchaAI n'intervient qu'aux étapes où un défi apparaît ; toutes les autres restent des appels HTTP standards vers vos backends. Quatre gestes suffisent :
- Relevez les paramètres du défi sur la page concernée : le sitekey, l'URL, et rien de plus. Tout surplus stocké deviendra une fausse piste de débogage.
- Envoyez la tâche sur
in.phpavecjson=1, et traitez tout statut différent de1comme une erreur journalisée, pas comme un cas limite. - Interrogez le résultat sur
res.php: première interrogation après 15 s, puis toutes les 5 s, avec un plafond ferme par tâche. - Injectez le token dans la requête suivante, sans recréer la session.
Ce dernier point est le plus sensible : le token doit être appliqué dans le contexte qui a déclenché le défi, avec les mêmes cookies. Une session recréée entre la résolution et la soumission reste la cause la plus fréquente de token refusé. La boucle envoi puis interrogation reste identique pour tous les types ; seuls les paramètres d'entrée changent, et les guides listés en fin d'article détaillent chacun d'eux.
Exemple : créer une tâche Turnstile depuis un worker Node.js
Extrait tiré 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;
}
Robustesse : budget de retry et idempotence
Fixez un plafond, jamais un retry infini : trois tentatives, backoff exponentiel borné, plafond global par tâche. Rendez chaque étape idempotente — une source rejouée deux fois ne doit produire qu'une ligne en base. Distinguez enfin deux compteurs souvent confondus : réussite de la résolution et acceptation en aval. L'écart entre ces deux courbes est votre signal d'alerte le plus fiable.
Observabilité et journalisation
Instrumentez chaque appel CAPTCHA pour produire quatre métriques : durée d'obtention du token, code retour HTTP, identifiant de tâche et profondeur de la file d'attente. Séparez les journaux par environnement et propagez l'identifiant de trace de votre outillage distribué (OpenTelemetry, par exemple) jusqu'à l'appel de résolution : un incident complet se rejoue alors depuis un seul identifiant.
Dimensionner les threads pour une collecte nocturne
La facturation se fait par thread simultané, avec un nombre de résolutions illimité par thread : le volume nocturne ne fait pas dériver la facture, seule la concurrence compte. Un thread correspond à un défi en cours ; dès qu'il se termine, il enchaîne.
| Profil de collecte | Défis simultanés | Plan adapté |
|---|---|---|
| Une dizaine de sources traitées en séquence | 1 à 4 | BASIC ($15/mois, 5 threads) |
| Plusieurs dizaines de domaines en parallèle | 10 à 15 | STANDARD ($30/mois, 15 threads) |
Pour estimer votre fenêtre nocturne, comptez moins de 10 s par Cloudflare Turnstile et moins de 60 s par reCAPTCHA v2.
Liste de contrôle avant la mise en production
- La clé API est stockée dans un secret CI ou un coffre, jamais dans le dépôt.
- Durées, codes retour et identifiants de tâche sont tracés à chaque exécution.
- Le retry est borné, idempotent, et les échecs terminaux déclenchent une alerte.
- Résolution réussie et acceptation en aval sont mesurées séparément.
FAQ
CaptchaAI prend-il en charge hCaptcha sur ce type de flux ?
Non — hCaptcha n'est pas pris en charge, pas plus que FunCaptcha (Arkose Labs) ; GeeTest v4 est annoncé comme à venir. Les types couverts sont reCAPTCHA v2 et v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3, les CAPTCHA image/OCR et les grilles d'images, plus CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta).
Combien de threads faut-il prévoir pour une collecte nocturne ?
Comptez un thread par défi traité en parallèle, pas par source : si vos workers traitent quatre domaines à la fois, quatre threads suffisent. Mesurez la concurrence réelle sur une semaine avant de changer de plan.
Pourquoi mon token est-il refusé alors que la résolution a réussi ?
Le plus souvent, le token a été appliqué dans une session différente de celle qui a déclenché le défi. Vérifiez que le cookie jar, l'en-tête User-Agent et le contexte de navigateur sont identiques de bout en bout, et que le token est utilisé avant expiration.
Que dois-je conserver dans mes journaux au regard du RGPD ?
Gardez ce qui sert au diagnostic — identifiant de tâche, horodatage, durée, code retour — et rien de plus. Évitez d'archiver des payloads complets contenant des données personnelles, et alignez leur rétention sur celle du reste de votre pipeline.
Guides connexes
- Démarrage rapide CaptchaAI
- Tests CAPTCHA en environnement autorisé
- Tester l'endpoint API sur vos propres formulaires
- Intégrer la résolution CAPTCHA à votre CI
- Résoudre reCAPTCHA v2 via l'API
Votre collecte planifiée mérite mieux qu'une reprise manuelle le matin. – Obtenez votre clé CaptchaAI.
