Périmètre sûr : ce guide s'applique à vos propres applications, à vos environnements de QA et aux sources pour lesquelles vous détenez une autorisation écrite — jamais à des portails tiers sans accord.
Une extraction de registres fonciers échoue rarement sur la donnée : elle échoue à 3 h du matin, sur un défi CAPTCHA que personne n'est là pour résoudre. La réponse tient en trois pièces : un appel vers l'API CaptchaAI, une journalisation qui pointe l'étape du blocage, un retry borné. Le reste du pipeline ne bouge pas.
Vérifiez d'abord votre périmètre d'accès
Les données foncières sont publiques dans plusieurs pays francophones, mais la consultation automatisée ne l'est pas toujours. Tranchez avant la première ligne de code : application interne, portail exploité pour un client, ou source assortie de conditions explicites ? Un dossier de publicité foncière contient noms et adresses : gardez les seuls champs utiles et fixez une durée de rétention, comme l'attend la CNIL.
Scénario type : une consultation cadastrale nocturne
Une agence immobilière lyonnaise rapproche chaque nuit son portefeuille avec un portail de registres fonciers auquel elle a un accès autorisé. Le job tourne à 2 h sur un worker OVHcloud ; trois requêtes sur dix déclenchent un Turnstile ou un reCAPTCHA v2, et la file se vide à moitié.
Architecture du pipeline
L'orchestrateur enchaîne les étapes en HTTP standard et n'intervient qu'à l'apparition d'un défi. Il extrait alors le sitekey et l'URL, envoie la tâche à CaptchaAI, attend le token, puis l'injecte dans la même session que celle qui a déclenché le défi — première cause de tokens refusés après une résolution réussie.
CaptchaAI couvre les familles rencontrées sur ces portails : reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, CAPTCHA image/OCR et grilles d'images.
Le déroulé, étape par étape
- Détectez le défi au bon endroit. Ce n'est pas au chargement de la page d'accueil qu'il apparaît, mais à la soumission du formulaire de recherche. Placez la détection là, sinon vous résolvez des défis inutiles.
- Relevez le strict nécessaire. Le sitekey, l'URL réellement chargée par le worker, l'action éventuelle, et un proxy si le portail filtre par IP. Tout champ superflu crée une fausse piste le jour où ça casse.
- Envoyez la tâche à l'API CaptchaAI et gardez l'identifiant retourné dans vos logs : c'est votre seule clé de corrélation avec le support.
- Interrogez le résultat à intervalle espacé plutôt qu'en boucle serrée — une attente initiale, puis un polling régulier avec un plafond par tâche. Une interrogation trop agressive n'accélère rien et bruite vos métriques.
- Injectez le token dans la session d'origine, puis soumettez le formulaire sans changer de client HTTP.
- Enregistrez l'issue : accepté, refusé, expiré. Ces trois états alimentent tout ce qui suit.
Exemple de code
Extrait côté client de votre 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;
}
Journalisation et métriques à instrumenter
Instrumentez chaque appel CAPTCHA : durée d'obtention du token, code retour HTTP, identifiant de tâche, longueur de la file. Séparez les journaux par environnement et corrélez-les à votre traçage distribué (OpenTelemetry) pour rejouer un scénario entier depuis un identifiant.
Distinguez deux taux de réussite : la résolution et l'acceptation par le portail. L'écart entre les deux est votre signal d'alerte le plus fiable.
Retry, timeout et idempotence
Bornez les tentatives : trois essais, backoff exponentiel, plafond à 30 secondes. Rendez l'étape idempotente pour qu'un rejeu ne crée pas de doublon. Alertez sur la tendance, pas sur l'incident isolé.
Dépannage
Cinq symptômes couvrent la quasi-totalité des nuits blanches sur ce type de pipeline.
| Symptôme | Cause probable | Correctif |
|---|---|---|
| Clé refusée dès l'envoi | Clé copiée avec une espace parasite, ou compte différent de celui du tableau de bord. | Recopiez la clé et stockez-la comme secret CI, jamais en dur. |
| Solde épuisé en pleine nuit | Aucun seuil de rechargement surveillé avant la fenêtre nocturne. | Posez une alerte de solde et un plancher de rechargement automatique. |
| Paramètres rejetés | Sitekey ou URL relevés sur une autre page que celle qui affiche le défi. | Re-relevez le sitekey sur la page exacte chargée par le worker. |
| Token résolu puis rejeté par le portail | La session a changé entre la résolution et la soumission. | Gardez le même cookie jar et le même contexte HTTP de bout en bout. |
| Résolutions correctes mais file qui s'allonge | Threads saturés au pic de concurrence. | Mesurez la concurrence réelle au pic et montez de palier. |
Dimensionner les threads
La facturation CaptchaAI est au thread simultané, en dollars US, résolutions illimitées par thread. Un job nocturne de quelques centaines de consultations tient sur BASIC ($15/mois, 5 threads) ; une extraction parallélisée passe sur ADVANCE ($90/mois, 50 threads). Dimensionnez sur le pic de concurrence, pas sur le volume mensuel.
Liste de contrôle avant mise en production
- Périmètre documenté : application interne, mandat client ou conditions acceptées.
- Clé API dans un secret CI ou un coffre, jamais dans le dépôt.
- Token injecté dans la session qui a déclenché le défi.
- Durées et codes retour tracés à chaque exécution.
- Retry borné, idempotent et journalisé.
- Rétention des données personnelles définie.
FAQ
Quels types de CAPTCHA sont pris en charge sur ce type de portail ?
reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, CAPTCHA image et grilles ; CaptchaFox, Friendly Captcha et Lemin en bêta. hCaptcha et FunCaptcha (Arkose Labs) ne sont pas pris en charge ; GeeTest v4 est à venir.
Le RGPD s'applique-t-il aux données extraites d'un registre foncier ?
Oui, dès qu'un nom ou une adresse est conservé. Le caractère public de la source ne dispense ni de la base légale, ni de la minimisation, ni d'une durée de rétention.
Combien de threads prévoir pour une extraction nocturne ?
Comptez les défis résolus en parallèle au pic, pas le total de la nuit. Cinq threads absorbent une file séquentielle ; au-delà de dix workers, montez de palier.
Le token est accepté par l'API mais refusé par le portail : pourquoi ?
La session a presque toujours changé entre résolution et soumission : nouveau contexte de navigateur, nouveau client HTTP, cookies perdus. Gardez le même cookie jar de bout en bout.
Guides connexes
- Le démarrage rapide CaptchaAI
- La résolution CAPTCHA en test autorisé
- Tester l'endpoint API sur vos formulaires
- Intégrer la résolution CAPTCHA à la CI
- Résoudre reCAPTCHA v2 via l'API
Passez d'une reprise manuelle le matin à une extraction qui va au bout. – Obtenez votre clé CaptchaAI.
