Périmètre sûr : ce guide couvre uniquement vos propres applications et vos environnements de QA, de préproduction ou de production — ou des systèmes pour lesquels vous détenez une autorisation écrite. Il ne traite ni de l'automatisation de sites tiers, ni du contournement de protections, ni de l'évasion d'anti-bot.
Un CAPTCHA qui se résout en cinq minutes dans un notebook mais qui casse dès qu'il tourne sans surveillance : voilà le scénario que ce guide élimine. Pour résoudre un CAPTCHA de façon fiable dans une file d'attente ou un job planifié, trois réflexes suffisent :
- isoler l'appel à CaptchaAI dans un composant dédié ;
- tracer chaque étape, de la soumission à l'injection du token ;
- borner les nouvelles tentatives avec un backoff exponentiel.
Le reste de l'article détaille cette mécanique pour un worker censé tenir la charge en production, pas seulement sur un parcours idéal.
CaptchaAI expose une seule API pour toutes les familles de CAPTCHA — reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, image/OCR et grilles d'images. Votre code de file d'attente ne bouge pas quand le défi change sur la page : vous ajustez le type de tâche et vous conservez la même boucle.
Pourquoi le mode « sans surveillance » change tout
Une résolution manuelle pardonne beaucoup : vous voyez l'erreur, vous relancez. Dans une file d'attente, un cron ou un pool de workers, personne ne regarde. Il vous faut donc une latence prévisible, des modes d'échec propres et un code qu'un collègue relit en cinq minutes. Une intégration CaptchaAI doit être conçue pour ça : petite, observable et facile à transmettre.
L'architecture cible
Votre composant interne appelle CaptchaAI en HTTPS pour récupérer un token, puis l'injecte dans le formulaire ou la route d'API qui a déclenché le défi. Un point n'est pas négociable : le token doit être appliqué dans la même session — même contexte de navigateur, même client HTTP, même cookie jar — que celle qui a affiché le CAPTCHA. Une session dépareillée reste la première cause de rejet après résolution.
Tracez chaque étape (soumission, interrogation, injection) : c'est ce qui rend les régressions visibles lors des montées de version.
Isoler la clé API et les secrets
La clé CaptchaAI vit dans un coffre — HashiCorp Vault, AWS Secrets Manager, Azure Key Vault — ou dans un secret de votre chaîne CI, jamais dans le code source. Au déploiement, elle est montée en variable d'environnement au runtime. Sur un worker hébergé chez OVHcloud ou Scaleway, la même règle s'applique : le secret est injecté par la plateforme, pas écrit dans l'image.
Appeler CaptchaAI depuis votre service
L'appel côté serveur reste minimal. L'exemple ci-dessous crée une tâche Turnstile et renvoie l'identifiant à interroger :
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;
}
Le contrat reste toujours le même : vous soumettez la tâche, vous récupérez un identifiant, puis vous interrogez le résultat à intervalle régulier jusqu'à obtenir le token. Une règle de bon sens sur le polling : attendez avant la première interrogation, puis espacez les suivantes pour ne pas surcharger l'API.
Dépannage
Quatre erreurs concentrent l'essentiel des tickets sur ce type d'intégration. Chaque ligne se corrige sans quitter l'éditeur.
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace parasite ou rattachée au mauvais compte. | Recopiez la clé depuis le tableau de bord et stockez-la en secret CI. |
ERROR_ZERO_BALANCE |
Solde inférieur au minimum par tâche. | Rechargez avant de relancer et ajoutez une alerte de solde. |
ERROR_BAD_PARAMETERS |
Paramètre requis manquant ou mal formé. | Revalidez l'URL de page et le sitekey face au HTML réel de la cible. |
| Token refusé après résolution | Token appliqué dans une autre session que celle du défi. | Gardez la résolution et la soumission dans le même contexte HTTP ou navigateur. |
Observabilité : mesurer avant d'industrialiser
Quel que soit le langage, instrumentez les appels CAPTCHA pour obtenir des signaux exploitables : durée totale d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente interne. Ces métriques alimentent vos tableaux de bord de QA et vos alertes, et séparent deux choses trop souvent confondues — le taux de réussite du solveur et le taux de réussite du workflow complet.
Séparez les journaux par environnement et corrélez-les à votre traçage distribué (OpenTelemetry, par exemple) : vous rejouez alors un incident complet à partir d'un seul identifiant. Côté RGPD, gardez-les sobres — un identifiant de tâche et des métriques techniques suffisent au diagnostic, sans y verser de données personnelles issues du formulaire.
Liste de contrôle avant la mise en production
- Le périmètre se limite à vos applications ou à des sources explicitement autorisées.
- La clé CaptchaAI est stockée dans un coffre ou un secret CI, jamais en dur dans le code.
- Les durées d'appel et les codes retour sont tracés à chaque exécution.
- Une stratégie de retry idempotent, avec backoff exponentiel borné, couvre les erreurs transitoires.
- Le token est injecté dans la session qui a déclenché le défi.
- Les tests sont rejouables depuis votre intégration continue.
Côté dimensionnement, raisonnez en threads : le plan BASIC ($15/mois, 5 threads) couvre un worker unique. La facturation porte sur les threads concurrents, avec des résolutions illimitées par thread — un job continu n'entraîne aucun surcoût à la résolution.
FAQ
Faut-il conserver les tokens résolus pour les rejouer plus tard ?
Non. Un token CAPTCHA a une durée de vie courte et se résout à la demande : demandez-le au moment où votre workflow en a besoin, appliquez-le immédiatement, puis passez à la tâche suivante. Constituer une réserve de tokens ne fait qu'accumuler des jetons expirés et des rejets.
Où stocker la clé API dans une chaîne CI/CD ?
Dans le gestionnaire de secrets de votre plateforme (secret CI, Vault, Secrets Manager), injecté en variable d'environnement au moment de l'exécution. Ne la committez jamais et faites-la tourner si elle a pu fuiter ; un simple espace parasite lors d'un copier-coller suffit à déclencher un ERROR_WRONG_USER_KEY.
Pourquoi un token valide est-il refusé après résolution ?
Presque toujours parce qu'il est appliqué dans une session différente de celle qui a affiché le CAPTCHA. Conservez le même contexte de navigateur ou le même client HTTP entre la résolution et la soumission du formulaire, cookies compris, et le rejet disparaît.
Combien de threads prévoir pour un worker qui tourne en continu ?
Un thread correspond à un CAPTCHA en cours de résolution ; dès qu'il se termine, il enchaîne le suivant. Un worker séquentiel se contente donc de quelques threads, alors qu'un pool qui traite plusieurs files en parallèle en réclame davantage. Partez du plan BASIC, mesurez votre concurrence réelle, puis montez de palier si la file d'attente s'allonge.
Guides connexes
- le démarrage rapide CaptchaAI
- tester vos CAPTCHA en environnement autorisé
- tester l'endpoint API sur vos formulaires
- intégrer la résolution CAPTCHA à votre CI
- résoudre reCAPTCHA v2 via l'API
Passez d'un script fragile à une intégration reproductible et mesurée. – Obtenez votre clé CaptchaAI.
