Périmètre sûr : Ce guide s'applique exclusivement à vos propres applications, à vos environnements de QA, de préproduction ou de production, et aux sources pour lesquelles vous disposez d'un accord de collecte écrit. Il ne décrit pas l'automatisation de sites tiers, ni aucune technique visant à neutraliser une protection.
Un agrégateur d'avis tombe rarement en panne à cause du parsing : il s'arrête parce qu'une étape protégée par un défi CAPTCHA attend une action humaine à 3 h du matin. La réponse tient en trois briques : un service de résolution isolé du pipeline, un token réinjecté dans la session qui a déclenché le défi, et des métriques qui séparent la résolution réussie de la collecte réussie.
Le cas concret : une collecte nocturne
Une enseigne belge de 40 points de vente consolide chaque nuit ses notes Google et Trustpilot sur une instance OVHcloud. Deux fois par semaine, un formulaire protégé par reCAPTCHA v2 interrompt le job : personne ne s'en aperçoit avant le lundi matin. Le correctif n'est pas de relancer plus souvent, mais de traiter le défi CAPTCHA comme une dépendance externe ordinaire — timeout, retry borné, métrique dédiée.
Architecture cible
Un composant interne appelle CaptchaAI en HTTPS, récupère un token, puis l'injecte dans le formulaire ou la route d'API qui poursuit le parcours. Ce composant ignore votre schéma d'avis et votre ordonnanceur : il reçoit des paramètres explicites et rend un token ou une erreur typée. Quand la famille de CAPTCHA change sur la page, vous modifiez une méthode d'API et rien d'autre.
Le déroulé de bout en bout
Cinq étapes suffisent, et leur ordre compte davantage que le langage employé.
- Relevez uniquement les paramètres attendus. Inspectez la page ou l'appel réseau et ne gardez que ce que la famille de CAPTCHA exige : sitekey, URL de la page, action éventuelle, proxy si vous en utilisez un. Tout paramètre superflu crée une fausse piste de diagnostic.
- Envoyez la tâche, puis traitez tout statut autre que la réussite comme une erreur : journalisez la réponse complète et remontez-la sur votre canal de supervision.
- Interrogez le résultat après une pause d'environ 15 s, puis toutes les 5 s, avec un plafond dur de 120 s par tâche.
- Appliquez le token dans la session qui a déclenché le défi — même contexte de navigateur, même client HTTP, mêmes cookies. Une session dépareillée reste la première cause de refus après résolution.
- Mesurez la latence, les retries et l'acceptation en aval. Une tâche résolue n'est pas un parcours réussi.
Configuration des secrets et budget
La clé CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret d'intégration continue, jamais dans le dépôt. Le déploiement la monte en variable d'environnement au runtime, ce qui permet une rotation sans redéployer le code.
La facturation est en dollars US, par thread simultané, avec des résolutions illimitées par thread. Un job nocturne à faible concurrence tient dans BASIC ($15/mois, 5 threads) ; une collecte continue sur plusieurs marchés francophones s'installe plutôt sur ADVANCE ($90/mois, 50 threads). Dimensionnez sur la concurrence mesurée, pas sur le volume mensuel.
Exemple de code
Exemple côté client, extrait 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 logique se transpose telle quelle en Python, Go ou Java. Pour les paramètres par type, voyez le guide de résolution de reCAPTCHA v2 via l'API.
Observabilité et journalisation
Instrumentez chaque appel : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente. Séparez les journaux par environnement et corrélez-les à votre traçage distribué (OpenTelemetry, par exemple). Surveillez surtout l'écart entre le taux de réussite de la résolution et le taux d'acceptation en aval : un token valide refusé signale presque toujours une session différente entre la résolution et l'envoi.
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec une espace parasite, ou mauvais compte. | Recopiez la clé depuis le tableau de bord et stockez-la comme secret CI. |
ERROR_ZERO_BALANCE |
Solde inférieur au minimum par tâche. | Rechargez, puis posez une alerte de solde avant la prochaine collecte nocturne. |
ERROR_BAD_PARAMETERS |
sitekey ou URL de page absent ou mal formé. | Revalidez les paramètres envoyés contre le HTML réellement servi. |
ERROR_CAPTCHA_UNSOLVABLE |
Le défi n'a pas pu être résolu de façon fiable. | Réessayez une fois ; si le cas persiste, capturez le HTML et ouvrez un ticket. |
| Token refusé après résolution | Token appliqué dans une autre session que celle du défi. | Gardez la résolution et l'envoi du formulaire dans le même contexte. |
Tests et conformité RGPD
Faites tourner des tests d'intégration sur vos endpoints critiques à chaque merge, comme décrit dans l'intégration des CAPTCHA en CI et dans le test d'endpoint sur vos formulaires.
Un agrégateur d'avis manipule des contenus rédigés par des personnes identifiables. Minimisez ce que vous conservez : la note, la date et un identifiant d'avis suffisent au tableau de bord ; le nom de l'auteur, rarement. Documentez votre base légale et votre durée de conservation (cadrage QA en environnements autorisés).
Liste de contrôle
- Le périmètre reste limité à vos applications ou à des sources sous accord écrit.
- La clé CaptchaAI est stockée dans un coffre ou un secret CI, jamais dans le code.
- Le token est appliqué dans la session qui a déclenché le défi.
- Le retry est borné à trois tentatives avec backoff exponentiel.
- Résolution et acceptation en aval sont mesurées séparément.
FAQ
Quel plan CaptchaAI choisir pour une collecte quotidienne ?
Dimensionnez sur la concurrence : chaque thread traite un défi à la fois, sans limite de résolutions. Un job à cinq tâches simultanées tient dans BASIC ($15/mois, 5 threads) ; passez à ADVANCE ($90/mois, 50 threads) quand plusieurs marchés tournent en parallèle.
Combien de temps attendre avant d'interroger le résultat ?
Laissez passer environ 15 s après l'envoi, puis interrogez le résultat toutes les 5 s, avec un plafond de 120 s par tâche. Un polling plus agressif ajoute du bruit sans accélérer la résolution.
CaptchaAI prend-il en charge hCaptcha ?
Non, hCaptcha n'est pas pris en charge, pas plus que FunCaptcha (Arkose Labs) ; GeeTest v4 est annoncé comme à venir. Sont couverts : reCAPTCHA v2 et v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3, les CAPTCHA image et les grilles d'images, plus CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta).
Que faire quand le token est refusé après une résolution réussie ?
Vérifiez la session : le token doit repartir depuis le même contexte de navigateur ou le même client HTTP, avec les mêmes cookies. Contrôlez ensuite l'expiration du token et la correspondance entre le sitekey envoyé et celui du HTML.
Guides connexes
- Le démarrage rapide CaptchaAI
- La QA CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- L'intégration des CAPTCHA en CI
- Résoudre reCAPTCHA v2 via l'API
Passez de la collecte fragile au pipeline reproductible. – Obtenez votre clé CaptchaAI.
