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 systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers que vous ne contrôlez pas, ni l'évasion de dispositifs anti-bot.
Windmill exécute vos scripts et vos workflows de façon planifiée, sans surveillance humaine. Dès qu'une de ces étapes rencontre un formulaire ou une route protégés par un CAPTCHA, elle s'arrête net : c'est le rôle d'une étape CaptchaAI que de débloquer ce passage. Ce guide montre comment intégrer un appel CaptchaAI dans un workflow Windmill de manière stable, traçable et reproductible — pas seulement à la première exécution, mais aussi après les déploiements et les incidents réseau.
Pourquoi une étape CaptchaAI a sa place dans Windmill
Windmill excelle à orchestrer des tâches internes : jobs cron, files d'attente, scripts Python ou TypeScript déclenchés par événement. La friction apparaît quand l'une doit franchir un CAPTCHA sur votre propre application : une résolution manuelle y est impossible. Il vous faut une résolution programmatique, avec une latence prévisible et des modes d'échec propres. CaptchaAI répond à ce besoin avec une API unique couvrant les principales familles — reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, image/OCR et grilles d'images — et une facturation par thread qui ne pénalise pas la montée en charge : l'offre BASIC ($15/mois, 5 threads) suffit pour démarrer.
Scénario type : une collecte planifiée sur votre propre portail
Imaginez un workflow Windmill déclenché chaque nuit sur un worker hébergé chez OVHcloud ou Scaleway. Il se connecte à votre propre portail client, franchit une page protégée par Turnstile, puis produit un rapport interne. La première exécution fonctionne en cinq minutes ; ensuite, le flux doit survivre aux déploiements et aux changements de famille de CAPTCHA. Comme vous manipulez des données, limitez la collecte au strict nécessaire et vérifiez vos obligations RGPD avant d'industrialiser le flux.
Architecture de l'intégration
Le principe reste simple : votre étape Windmill appelle CaptchaAI en HTTPS pour obtenir un token, puis l'injecte dans le formulaire ou la route d'API qui a déclenché le défi. Isolez cette logique dans un script réutilisable plutôt que de la dupliquer dans chaque flow : vous n'aurez qu'un endroit à corriger si un paramètre change.
Traiter la clé API comme un secret Windmill
Ne codez jamais la clé CaptchaAI en dur. Windmill fournit un magasin de variables et de ressources chiffrées : déclarez-y la clé comme variable secrète, puis référencez-la au runtime. Sur une infrastructure plus large, elle peut vivre dans HashiCorp Vault, AWS Secrets Manager ou Azure Key Vault, montée en variable d'environnement par le worker. Dans tous les cas, elle ne doit apparaître ni dans le code, ni dans les logs.
Exemple d'appel côté serveur
L'exemple ci-dessous crée une tâche Turnstile depuis un service Node.js et renvoie l'identifiant de tâche. Vous l'appelez depuis votre étape Windmill, interrogez le résultat, puis injectez le token dans la session qui a déclenché le défi.
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
Quel que soit le langage, 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. Ces signaux alimentent vos tableaux de bord de QA et vos alertes.
Séparez les journaux par environnement et corrélez les identifiants à votre traçage distribué (OpenTelemetry). Vous pourrez rejouer un scénario complet depuis un identifiant unique, ce qui divise par deux le temps de diagnostic.
Liste de contrôle avant la mise en production
Chaque ligne correspond à un incident classique en exécution non surveillée.
| Contrôle | Pourquoi | Réglage recommandé |
|---|---|---|
| Périmètre autorisé | Sécurise l'usage du flux. | Vos applications ou sources autorisées uniquement. |
| Clé en secret | Une clé en clair fuit dans les logs. | Variable secrète Windmill ou coffre, jamais dans le code. |
| Même session | Un token appliqué ailleurs est rejeté. | Même contexte navigateur ou client HTTP pour résoudre et envoyer. |
| Budget de retry | Les retries infinis masquent les défauts. | Trois tentatives, backoff borné, échec journalisé. |
| Traçabilité | Un incident sans trace ralentit le diagnostic. | Durée, code retour et identifiant de tâche loggés. |
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Espace parasite ou mauvais compte. | Recopiez la clé et stockez-la en variable secrète. |
ERROR_ZERO_BALANCE |
Solde sous le minimum par tâche. | Rechargez le solde et ajoutez une alerte. |
ERROR_PAGEURL / ERROR_BAD_PARAMETERS |
Paramètre manquant ou mal formé. | Revalidez l'URL et le sitekey face au HTML réel. |
CAPCHA_NOT_READY en boucle |
Polling trop tôt ou trop long. | Attendez 15 s, puis toutes les 5 s, plafond 120 s. |
| Token refusé après résolution | Session différente de celle du défi. | Gardez résolution et envoi dans le même contexte. |
Mesurer la réussite de l'intégration
Distinguez deux métriques que l'on confond souvent : le taux de réussite du solveur (la tâche renvoie un token) et le taux d'acceptation en aval (le token est validé par votre application). Suivez les deux séparément et alertez sur l'écart. Fixez-vous des objectifs internes, à adapter à votre contexte : une latence médiane sous 25 s pour un CAPTCHA à token, un taux de réussite du solveur d'au moins 95 % par famille et un coût par résolution acceptée stable sur la semaine.
FAQ
Où placer ma clé API CaptchaAI dans un workflow Windmill ?
Dans le magasin de variables et de ressources de Windmill, déclarée comme variable secrète puis référencée au runtime. Un coffre externe monté en variable d'environnement convient aussi. La règle : la clé ne doit jamais apparaître dans le code ni dans les logs.
Quels types de CAPTCHA puis-je résoudre depuis Windmill ?
CaptchaAI prend en charge reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, les CAPTCHA image/OCR et en grille d'images, ainsi que BLS. CaptchaFox, Friendly Captcha et Lemin sont en bêta. L'API étant unique, vous changez le type de tâche sans réécrire votre boucle d'envoi et d'interrogation.
Comment éviter qu'une erreur transitoire bloque tout le workflow ?
Encadrez l'appel d'une stratégie de retry avec backoff exponentiel borné : trois tentatives, doublement du délai à chaque essai, plafond à 30 secondes. Si l'erreur persiste, vérifiez la configuration réseau (DNS, certificats) et le solde de votre clé.
Faut-il un environnement dédié pour exécuter ces étapes ?
Ce n'est pas obligatoire, mais séparer les workers par environnement évite qu'un test ne consomme le solde de production. Windmill permet d'assigner des workers à des groupes distincts, ce qui rend cette séparation simple.
Guides connexes
- Le démarrage rapide CaptchaAI
- La QA CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires web
- Intégrer la résolution CAPTCHA dans votre CI
- Résoudre reCAPTCHA v2 via l'API
Structurez vos workflows CAPTCHA une bonne fois. – Créez votre compte CaptchaAI et ajoutez votre première étape de résolution à Windmill.
