Périmètre sûr : ce guide s'applique uniquement à vos propres applications et à vos environnements de QA, de préproduction ou de production, ou à des sources pour lesquelles vous disposez d'une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni l'évasion de protections anti-bot.
Un agent de recherche type Perplexity enchaîne des requêtes automatisées ; tôt ou tard, l'une d'elles tombe sur un CAPTCHA et le pipeline se fige. La bonne réponse n'est pas de surveiller le job à la main, mais de déléguer ce défi à un service de résolution puis de reprendre le fil dans la même session. Ce guide montre comment brancher CaptchaAI sur un agent de recherche automatisé pour un flux qui tient en production, pas seulement le temps d'une démo.
Pourquoi un agent de recherche se bloque sur un CAPTCHA
En notebook, la résolution paraît triviale : une page, un défi, un token. Le problème surgit dès que le job tourne sans surveillance — la nuit, pendant une fenêtre de déploiement, ou quand la famille de CAPTCHA change sur la page. Il vous faut alors des délais prévisibles, moins d'interventions manuelles et un responsable clair en cas de panne. CaptchaAI répond à ce besoin avec une API unique pour les familles prises en charge, une latence prévisible et une facturation par thread qui ne pénalise pas la montée en charge. La facturation démarre au plan BASIC ($15/mois, 5 threads), résolutions illimitées par thread.
Le workflow recommandé, étape par étape
- Capturez le strict nécessaire. Ne récupérez que les paramètres attendus (sitekey, URL de la page, action, proxy éventuel) ; tout stocker au-delà crée de fausses pistes de débogage.
- Soumettez la tâche et conservez l'identifiant renvoyé. Traitez tout statut d'erreur comme un incident : journalisez la réponse et remontez-la.
- Interrogez le résultat à intervalle régulier : attendez environ 15 secondes, puis interrogez toutes les 5 secondes, plafond strict de 120 secondes par tâche.
- Appliquez le token dans la même session que le défi : même contexte de navigateur, même client HTTP, même cookie jar. Une session dépareillée est la première cause de rejet.
- Suivez la latence, les retries et l'acceptation en aval : la réussite du solveur et celle du workflow sont deux métriques distinctes.
Architecture
L'orchestrateur déclenche les étapes ; CaptchaAI n'intervient qu'à celles où un défi apparaît, les autres restant des appels HTTP standards vers votre backend. Cette séparation garde le pipeline lisible : un point d'intégration unique, facile à instrumenter et à remplacer.
Exemple de code
Exemple côté client, extrait de votre suite de tests : la fonction soumet une tâche et renvoie l'identifiant à interroger ensuite.
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;
}
Observabilité et journalisation
Instrumentez les appels CAPTCHA pour obtenir des métriques exploitables : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente interne. Ces signaux alimentent vos tableaux de bord de QA et vos alertes.
Séparez les journaux par environnement (développement, préproduction, production) et corrélez les identifiants à votre traçage distribué, par exemple via OpenTelemetry. Vous rejouez ainsi un scénario complet à partir d'un seul identifiant, ce qui accélère nettement le diagnostic.
Liste de contrôle opérationnelle
Passez ces points en revue avant de fusionner l'intégration :
- Le périmètre reste limité à vos propres applications ou à des sources autorisées.
- La clé CaptchaAI vit dans un secret CI ou un coffre, jamais dans le code source.
- Chaque exécution trace les durées d'appel et les codes retour.
- Une stratégie de retry idempotente couvre les erreurs transitoires.
- Les tests sont rejouables et reproductibles depuis votre intégration continue.
Mesurer la réussite
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. Câblez ces cibles dans le tableau de bord que vous utilisez déjà pour repérer les régressions avant vos utilisateurs.
Suivez cinq indicateurs : la latence de première résolution (cible p50 < 25 s pour les CAPTCHA à token, < 8 s pour l'OCR image ; p95 < 60 s), le taux de réussite du solveur (≥ 95 % par famille), l'acceptation de bout en bout après application du token (≥ 95 %) et le coût par résolution acceptée, stable sur la semaine.
Dépannage
Ces erreurs couvrent l'essentiel des tickets pour ce type d'intégration. Chaque ligne est un correctif applicable sans quitter votre éditeur.
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé mal copiée ou mauvais compte. | Recopiez la clé depuis le tableau de bord, en secret CI. |
ERROR_ZERO_BALANCE |
Solde sous le minimum par tâche. | Rechargez et ajoutez une alerte de solde. |
ERROR_BAD_PARAMETERS |
Entrée requise absente ou malformée. | Revalidez l'URL et le sitekey contre le HTML réel. |
CAPCHA_NOT_READY en boucle |
Interrogation trop précoce. | Attendez 15 s, plafond 120 s par tâche. |
| Token refusé après résolution | Token appliqué dans une autre session. | Gardez résolution et soumission dans la même session. |
Périmètre sûr et conformité RGPD
Ce guide suppose l'un de ces trois cadres : vous possédez l'application qui affiche le CAPTCHA, vous l'exploitez pour un client qui a autorisé l'intégration, ou vous opérez un accord de collecte autorisé avec la source. Dans tous les cas, minimisez les données personnelles présentes dans vos journaux et vérifiez vos obligations RGPD avant d'élargir le périmètre.
FAQ
Comment appliquer le token dans la même session que le défi ?
Utilisez le même contexte de navigateur ou le même client HTTP du début à la fin : même cookie jar, mêmes en-têtes. Un token appliqué dans une session neuve est presque toujours rejeté : la vérification aval attend la continuité de session qui a produit le défi.
CaptchaAI prend-il en charge hCaptcha pour un agent de recherche ?
Non — hCaptcha n'est pas pris en charge, pas plus que FunCaptcha (Arkose Labs) ou GeeTest v4. CaptchaAI résout reCAPTCHA v2 et v3, Cloudflare Turnstile et Cloudflare Challenge, GeeTest v3, l'image/OCR, les grilles d'images et le BLS ; CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta) complètent la couverture.
Comment rejouer un incident à partir des journaux ?
Corrélez chaque appel CAPTCHA à un identifiant de traçage unique, séparé par environnement. À partir de cet identifiant, vous reconstituez la séquence complète — soumission, interrogations, application du token — sans relancer tout le job.
Que faire si la famille de CAPTCHA change sur la page ?
Vous changez le type de tâche, gardez la même boucle de soumission et d'interrogation, puis déployez : CaptchaAI expose une API unique pour les familles prises en charge. La facturation par thread, à résolutions illimitées, garde la ligne de coût prévisible.
Guides connexes
- Le démarrage rapide CaptchaAI
- Tester les CAPTCHA en environnement autorisé
- Tester l'endpoint API sur vos formulaires
- Intégrer la résolution CAPTCHA dans votre CI
- Résoudre reCAPTCHA v2 via l'API
Branchez CaptchaAI sur votre agent de recherche sans toucher à votre architecture. — Obtenez votre clé CaptchaAI.
