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 le fait de déjouer des protections anti-bot.
Un CAPTCHA au milieu d'un workflow Retool bloque toute la chaîne dès qu'il apparaît : le job planifié s'arrête, la synchronisation échoue et personne ne le voit avant le lundi matin. La parade tient en trois briques : un composant serveur qui appelle CaptchaAI pour obtenir un token, une boucle envoi/interrogation instrumentée et des métriques par environnement. Cet article montre comment les assembler pour résoudre un CAPTCHA depuis un workflow Retool, de façon assez stable pour la production et transmissible à un client.
Pourquoi un CAPTCHA fait tomber un workflow Retool
Le premier essai fonctionne en cinq minutes dans un carnet de test, puis le même flux doit survivre aux fenêtres de déploiement, aux à-coups réseau et aux changements de famille de CAPTCHA sur la page — c'est là que les intégrations bricolées cèdent. CaptchaAI y répond avec une API unique couvrant les familles reCAPTCHA, Cloudflare, GeeTest v3 et les CAPTCHA image, et une facturation par thread qui ne vous pénalise pas quand le volume monte.
Architecture cible
Votre composant interne appelle CaptchaAI en HTTPS pour récupérer un token, puis l'injecte dans votre formulaire ou votre route d'API. Chaque étape est tracée : vous repérez ainsi une régression dès la première montée de version, plutôt qu'au premier incident client. Gardez la résolution côté serveur, jamais dans le navigateur exposé.
Gestion des secrets
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 code source ni dans un bloc de configuration Retool en clair. Le déploiement la monte en variable d'environnement au runtime. Prévoyez la rotation : le jour où vous régénérez la clé, seul le secret change, pas le code.
La boucle envoi puis interrogation du résultat
La logique reste identique quelle que soit la famille de CAPTCHA. Conservez cet ordre :
- Capturez uniquement les paramètres utiles (sitekey, URL de la page, action, proxy éventuel). Stocker plus crée de fausses pistes de débogage.
- Envoyez la tâche à
https://ocr.captchaai.com/in.phpavecjson=1. Tout statut différent de1est une erreur : journalisez la réponse et remontez-la vers votre supervision. - Interrogez le résultat sur
https://ocr.captchaai.com/res.php. Attendez 15 s, puis interrogez toutes les 5 s avec un plafond strict de 120 s 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êmes cookies. Une session dépareillée est la première cause de rejet.
- Mesurez la latence, les retries et l'acceptation en aval. Réussite de la résolution et réussite du workflow sont deux métriques distinctes ; suivez les deux.
Exemple de code côté serveur
Appel HTTP côté serveur, dans votre propre service :
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 chaque appel CAPTCHA pour obtenir des métriques exploitables : durée totale d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente interne. Affichez la latence, le taux de réussite par famille et la consommation, puis déclenchez une alerte sur l'écart entre résolution réussie et acceptation en aval : un token accepté par le solveur mais refusé par votre formulaire signale presque toujours un problème de session.
Séparez les journaux par environnement et corrélez les identifiants à votre traçage distribué, par exemple OpenTelemetry, pour rejouer un scénario complet à partir d'un seul identifiant. Côté conformité, minimisez les données personnelles présentes dans les logs : bonne pratique RGPD, et surface à protéger réduite.
Scénario : une agence qui livre pour un client
Prenons une agence lyonnaise qui exploite un workflow Retool pour la plateforme e-commerce d'un client. Le job planifié tourne sur un worker OVHcloud, et l'appel à CaptchaAI part depuis la région eu-west-3 (Paris) pour garder la latence basse. L'intégration doit survivre au transfert : le client reprend l'exploitation avec ses propres runbooks. L'agence livre donc un composant serveur documenté, des seuils d'alerte (alerter si le taux de réussite passe sous 95 %) et la clé stockée en secret. Le renouvellement se joue sur cette lisibilité, pas sur une démo qui marche une fois.
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 d'intégration continue. |
ERROR_ZERO_BALANCE |
Solde inférieur au minimum par tâche. | Rechargez le solde et ajoutez une alerte de solde bas au tableau de bord. |
ERROR_PAGEURL / ERROR_BAD_PARAMETERS |
Un paramètre requis est manquant ou mal formé. | Revalidez l'URL de la page, le sitekey et les champs propres à la famille face au HTML réel. |
| Token refusé après résolution | Token appliqué dans une session différente de celle du défi. | Gardez résolution et soumission dans le même contexte de navigateur ou la même session HTTP. |
FAQ
Comment injecter le token dans une action Retool ?
Récupérez le token côté serveur, renvoyez-le à votre workflow, puis passez-le au champ attendu par la page (g-recaptcha-response pour reCAPTCHA, cf-turnstile-response pour Turnstile) dans la session qui a déclenché le défi. C'est ce partage de session qui conditionne l'acceptation en aval.
Combien de threads faut-il prévoir pour un workflow planifié ?
Un job planifié modéré tient largement dans le plan BASIC ($15/mois, 5 threads). La facturation se fait par thread simultané, résolutions illimitées : un thread traite un CAPTCHA à la fois, puis enchaîne. Montez de palier seulement quand plusieurs workflows tournent en parallèle.
Que faire quand le token est refusé après résolution ?
Vérifiez d'abord la session : le token doit être appliqué dans le contexte, le client HTTP et les cookies qui ont produit le défi. Contrôlez ensuite que le sitekey et l'URL envoyés correspondent au HTML réel. Ces deux points couvrent la grande majorité des rejets post-résolution.
CaptchaAI prend-il en charge hCaptcha dans ce workflow ?
Non — hCaptcha et FunCaptcha (Arkose Labs) ne sont pas pris en charge. CaptchaAI couvre reCAPTCHA v2/v3, Cloudflare Turnstile et Challenge, GeeTest v3, ainsi que les CAPTCHA image/OCR et en grille. CaptchaFox, Friendly Captcha et Lemin sont disponibles en bêta.
Liste de contrôle avant livraison
- Périmètre limité à vos propres applications ou à des sources autorisées.
- Clé CaptchaAI stockée dans un coffre ou un secret d'intégration continue, jamais dans le code.
- Durées d'appel et codes retour tracés à chaque exécution.
- Token appliqué dans la session qui a déclenché le défi.
- Retry idempotent plafonné à trois tentatives pour les erreurs transitoires.
- Tests rejouables depuis votre intégration continue.
Guides connexes
- Le démarrage rapide CaptchaAI
- La QA CAPTCHA en environnements autorisés
- 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 méthodique. – Obtenez votre clé CaptchaAI.
