Périmètre sûr : ce guide s'applique uniquement à vos propres applications, à vos environnements de QA et de préproduction, ou à des sources pour lesquelles vous disposez d'un mandat ou d'une autorisation écrite. Il ne décrit pas l'automatisation de sites tiers sans accord.
Un défi CAPTCHA sur un portail fiscal ne casse pas votre collecte : il la met en pause jusqu'au retour du token. Reste à savoir si ce token arrive en quelques secondes, dans la bonne session, sans réveiller personne à 3 h du matin. Voici où placer l'appel de résolution, quoi mesurer et quels garde-fous poser avant de laisser le job tourner seul.
Ce que recouvre un accès autorisé
Avant l'architecture, la base juridique. Trois cas justifient un tel pipeline : vous éditez l'application qui affiche le défi, vous l'exploitez pour un client qui a validé l'intégration, ou vous agissez sous mandat sur vos propres dossiers.
Côté données, le réflexe RGPD reste classique : ne collectez que les pièces nécessaires, fixez une durée de conservation, et n'écrivez jamais un identifiant fiscal en clair dans vos logs. Un hachage de la référence de dossier suffit à corréler une exécution. Faites relire ce périmètre avant la mise en production, pas après le premier incident.
Scénario : la collecte nocturne d'un cabinet comptable
Prenons un cabinet d'expertise comptable à Lyon. Chaque nuit, un worker hébergé chez OVHcloud parcourt les dossiers sous mandat, ouvre l'espace professionnel, télécharge les pièces de la période et les dépose dans le coffre documentaire. Deux cents dossiers, personne devant l'écran.
En pleine campagne déclarative, le portail ajoute un défi Cloudflare Turnstile à la connexion. Sans résolution automatisée, la collecte s'arrête et la reprise manuelle coûte une matinée. C'est là que CaptchaAI s'insère : une étape de plus dans la séquence, pas une réécriture du pipeline.
Architecture du pipeline d'extraction fiscale
L'orchestrateur pilote la séquence ; CaptchaAI n'intervient que sur les étapes où un défi apparaît.
| Étape | Point de rupture fréquent |
|---|---|
| Ouverture de session | Cookies non isolés entre dossiers |
| Résolution du défi | Token appliqué dans une autre session |
| Téléchargement des pièces | Fichier tronqué accepté comme valide |
| Dépôt dans le coffre | Reprise non idempotente après échec |
La deuxième ligne coûte le plus cher : le token doit être injecté dans le contexte exact qui a déclenché le défi, mêmes cookies, même client HTTP. La plupart des rejets après résolution viennent de là.
Enchaîner les appels de résolution CAPTCHA
La séquence tient en quatre gestes. Relevez dans le HTML réel les paramètres attendus par la famille de CAPTCHA présente sur la page (sitekey, URL, action éventuelle). Envoyez la tâche, puis interrogez le résultat sans saturer l'endpoint : 15 secondes d'attente initiale, un polling toutes les 5 secondes, un plafond dur par tâche. Injectez enfin le token dans la même session.
Voici le côté client, tel qu'il apparaît dans 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é API se lit depuis une variable d'environnement alimentée par un coffre ou un secret CI. Jamais depuis le dépôt.
Les signaux à instrumenter
Un pipeline nocturne se juge sur ses métriques, pas sur son dernier succès. 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.
| Indicateur | Ce qu'il révèle |
|---|---|
| Temps de résolution (Turnstile < 10 s, reCAPTCHA v2 < 60 s) | Aucune attente sur des retries |
| Taux de réussite | Les paramètres collent au défi réel |
| Acceptation en aval | Le token part dans la bonne session |
| Dossiers repris à la main | Le budget de retry tient |
Séparez les journaux par environnement et propagez un identifiant de corrélation compatible avec votre traçage distribué, OpenTelemetry par exemple. Rejouer une nuit entière depuis un seul identifiant divise le temps de diagnostic.
Robustesse et reprise
Trois mécanismes rendent le pipeline exploitable : un retry borné avec backoff exponentiel (trois tentatives, délai doublé, plafond à 30 secondes), une reprise idempotente qui ne retraite pas un dossier déjà déposé, et une alerte sur un écart durable plutôt que sur un échec isolé. Un retry infini masque les défauts et consomme vos threads.
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
| Token refusé après résolution | Session différente | Garder le même contexte navigateur jusqu'à la soumission |
| File d'attente qui s'allonge | Threads saturés en pic nocturne | Étaler le lot ou monter d'un palier |
| Paramètres rejetés à l'envoi | Sitekey pris sur une autre page | Réextraire le sitekey de la page ciblée |
| Collecte partielle sans erreur | Fichier tronqué accepté | Vérifier taille et type MIME avant dépôt |
Dimensionner les threads et le budget
La facturation CaptchaAI se fait au thread simultané, résolutions illimitées par thread. Ce qui compte n'est donc pas le nombre de dossiers mais le nombre de défis traités en parallèle. Un lot séquentiel de 200 dossiers reste confortable sur BASIC ($15/mois, 5 threads) ; une exécution répartie sur dix workers appelle STANDARD ($30/mois, 15 threads). Mesurez votre parallélisme réel avant de choisir le palier.
Liste de contrôle avant la mise en production
- Le mandat ou l'autorisation écrite couvre chaque source interrogée.
- La clé CaptchaAI vit dans un coffre ou un secret CI, jamais dans le code.
- Durées de résolution et codes retour sont tracés à chaque exécution.
- La reprise est idempotente, testée sur un lot interrompu volontairement.
- Aucun identifiant fiscal en clair dans les journaux.
FAQ
Quel plan CaptchaAI choisir pour une collecte nocturne ?
Regardez votre parallélisme, pas votre volume. BASIC ($15/mois, 5 threads) suffit à un lot séquentiel ; au-delà de dix workers simultanés, STANDARD ($30/mois, 15 threads) évite la file d'attente.
Le RGPD s'applique-t-il à ce type de pipeline ?
Oui, dès que les documents extraits contiennent des données personnelles. Limitez la collecte, fixez une durée de conservation, chiffrez le stockage et excluez les identifiants fiscaux des journaux. Ce guide ne remplace pas l'avis de votre référent conformité.
Pourquoi mon token est-il refusé alors que la résolution a réussi ?
Parce qu'il est presque toujours appliqué ailleurs que là où le défi est apparu. Vérifiez que contexte navigateur, cookies et adresse de sortie sont identiques entre résolution et soumission, puis que le token n'a pas expiré entre-temps.
CaptchaAI prend-il en charge hCaptcha sur ces portails ?
Non. hCaptcha n'est pas pris en charge, pas plus que FunCaptcha ; GeeTest v4 est annoncé à venir. Sont couverts reCAPTCHA v2 et v3, Cloudflare Turnstile et Cloudflare Challenge, GeeTest v3, les CAPTCHA image et OCR et les grilles d'images, plus CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta).
Guides connexes
- Démarrage rapide CaptchaAI
- CAPTCHA en environnement de test autorisé
- Tester l'endpoint sur vos formulaires
- Résolution des CAPTCHA en intégration continue
- Résoudre reCAPTCHA v2 via l'API
Votre collecte mérite mieux qu'une reprise manuelle. – Obtenez votre clé CaptchaAI.
