Périmètre sûr : ce guide s'applique exclusivement à vos propres applications, à 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, ni la levée de protections, ni l'évasion d'anti-bot.
Un worker Fly Machines qui ne démarre qu'à la demande est la façon la plus économique de résoudre des CAPTCHAs en volume : la machine se réveille pour vider une file de tâches, appelle l'API CaptchaAI pour obtenir un token, puis s'éteint dès que la file est vide. Vous ne payez le calcul que pendant la résolution, et CaptchaAI facture au thread, pas au solve. Ce guide assemble l'architecture de bout en bout — secrets, code, observabilité — pour qu'elle tienne en production.
Pourquoi un pool de workers à la demande
Un service qui tourne 24 h/24 en attendant d'éventuelles tâches CAPTCHA gaspille du calcul et brouille le suivi des coûts. Les Fly Machines démarrent en quelques secondes, ce qui les rend idéales pour un traitement par lots déclenché par un cron, un webhook ou une file Redis.
Prenons un cas concret : un job planifié qui vérifie chaque nuit un formulaire protégé dans votre propre application. Déployé sur la région cdg (Paris) de Fly.io — ou sur une région européenne équivalente chez OVHcloud ou Scaleway — il reste proche de vos utilisateurs et de vos obligations RGPD sur la localisation des données. La première exécution fonctionne en cinq minutes ; le vrai enjeu est qu'elle continue de tourner à travers les fenêtres de déploiement, les aléas réseau et les changements de famille de CAPTCHA sur la page.
Le flux du token, de bout en bout
Votre worker interne appelle CaptchaAI en HTTPS pour récupérer un token, puis l'injecte dans le formulaire ou la route d'API concernée — dans la même session que celle qui a déclenché le défi. Cette contrainte de session est la première cause de rejet : un token valide appliqué dans un autre contexte navigateur ou client HTTP est refusé. Tracez chaque étape — soumission, interrogation, injection — pour repérer les régressions.
Gardez le worker sans état : les données de travail transitent par la file d'attente et les logs, jamais par le disque local de la machine, qui disparaît à l'arrêt.
Le déroulé d'une résolution
- Capturez le strict nécessaire. Ne conservez que les paramètres attendus par la famille de CAPTCHA : sitekey, URL de page, action, proxy éventuel. Le reste crée de fausses pistes de débogage.
- Soumettez puis interrogez le résultat à intervalle régulier, avec un plafond strict par tâche. Trop agressive, l'interrogation ajoute du bruit ; trop lente, elle ralentit le workflow.
- Appliquez le token dans la session d'origine, puis mesurez séparément la réussite du solveur et celle du workflow — deux métriques dont l'écart est votre meilleur signal d'alerte.
Où placer la clé API
La clé CaptchaAI ne doit jamais figurer dans le code source. Stockez-la dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou, sur Fly.io, via fly secrets set, qui l'expose en variable d'environnement au runtime. Le worker lit alors CAPTCHAAI_KEY au démarrage.
Faites tourner la clé régulièrement et gardez une clé distincte par environnement : ce cloisonnement limite le rayon d'impact en cas de fuite.
Créer une tâche Turnstile en Node.js
L'appel côté serveur reste minimal. Cet exemple Node.js crée une tâche Turnstile et renvoie son identifiant ; vous interrogez ensuite le résultat avec le même client HTTP :
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 même boucle vaut pour reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile ou GeeTest v3 : vous changez le type de tâche, le reste du worker ne bouge pas.
Journalisation et métriques
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. Vos tableaux de bord de QA doivent afficher la latence, le taux de réussite et la consommation de threads par environnement.
Corrélez chaque identifiant à votre traçage distribué (par exemple OpenTelemetry) pour rejouer un scénario complet et réduire le temps de diagnostic. Côté RGPD, minimisez les données personnelles dans les logs : un identifiant de tâche et un statut suffisent, inutile d'y stocker le contenu des formulaires.
Checklist avant mise en production
- Le périmètre est limité à vos propres applications ou à des sources autorisées.
- La clé CaptchaAI vit dans un coffre ou un secret Fly.io, jamais dans le code source.
- Les durées d'appel et les codes retour sont tracés à chaque exécution.
- Un retry idempotent avec backoff exponentiel borné couvre les erreurs transitoires.
- Le token est appliqué dans la même session que celle qui a déclenché le défi.
- Les tests sont rejouables depuis votre intégration continue.
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 en secret CI. |
ERROR_ZERO_BALANCE |
Solde inférieur au minimum par tâche. | Rechargez le compte et ajoutez une alerte de solde. |
ERROR_BAD_PARAMETERS |
Paramètre requis absent ou mal formé. | Revalidez l'URL de page et le sitekey face au HTML réel. |
| Token refusé après résolution | Token appliqué dans une autre session que celle du défi. | Gardez la résolution et l'envoi dans le même contexte navigateur. |
FAQ
Pourquoi lancer les workers à la demande plutôt que de les garder actifs en permanence ?
Parce que les Fly Machines démarrent en quelques secondes : vous ne consommez du calcul que pendant la résolution. Un pool à la demande absorbe les pics — cron nocturne, webhook, file qui se remplit — sans facturer les heures creuses. La facturation CaptchaAI étant au thread avec des solves illimités, votre coût suit le volume utile.
Combien de threads CaptchaAI faut-il pour un pool de workers ?
Un thread correspond à un CAPTCHA en cours de résolution : dimensionnez-les sur votre concurrence réelle, pas sur le nombre de machines. Le plan BASIC ($15/mois, 5 threads) suffit à un job planifié modeste ; passez à STANDARD ($30/mois, 15 threads) ou au-delà quand plusieurs workers résolvent en parallèle.
Où stocker la clé API sur Fly.io ?
Utilisez fly secrets set CAPTCHAAI_KEY=... : la clé est chiffrée et injectée en variable d'environnement au démarrage de la machine, jamais écrite dans l'image ni dans le dépôt.
Comment gérer une erreur transitoire pendant qu'une machine démarre ?
Appliquez un backoff exponentiel borné — par exemple trois tentatives, doublement du délai à chaque essai, plafond à 30 s — et tracez chaque échec avec son identifiant de tâche. Si l'erreur persiste, vérifiez le réseau (DNS, certificats) et le solde de votre clé avant de relancer.
Pour aller plus loin
- Le démarrage rapide CaptchaAI
- Tester vos CAPTCHAs en environnement autorisé
- Tester l'endpoint API sur vos formulaires
- Intégrer la résolution CAPTCHA en CI
- Résoudre reCAPTCHA v2 via l'API
Fiabilisez vos workflows CAPTCHA avec une approche reproductible. – Obtenez votre clé CaptchaAI.
