Périmètre sûr : ce guide s'applique uniquement à vos propres applications et environnements (QA, préproduction, production) ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne porte pas sur l'automatisation de sites tiers que vous ne contrôlez pas, ni sur la résolution de protections sans accord préalable.
Pour intégrer la résolution de CAPTCHA dans un workflow ToolJet, un nœud de votre application appelle l'API CaptchaAI, récupère un token, puis l'injecte dans le formulaire ou la requête qui déclenche le défi. Le point délicat n'est pas d'obtenir un token la première fois, mais de garder ce flux stable une fois qu'il tourne sans surveillance, sous les runbooks d'une autre équipe. Ce guide s'adresse aux agences et intégrateurs qui livrent cette brique chez un client, et décrit l'architecture qui tient en production.
Architecture d'intégration recommandée
Gardez l'appel CAPTCHA isolé dans un seul composant, invoqué depuis votre workflow ToolJet, plutôt que dispersé dans plusieurs requêtes. Il reçoit les paramètres du défi (sitekey, URL, action éventuelle), appelle CaptchaAI en HTTPS, attend le résultat, puis renvoie le token au reste du workflow. Deux règles le rendent robuste :
- Une seule responsabilité. Il résout un défi et rend un token, sans connaître la logique métier ni le formulaire final. Vous pouvez ainsi le rejouer, le mocker et le remplacer sans toucher au reste.
- La même session de bout en bout. Le token doit être appliqué dans le contexte qui a déclenché le défi : même client HTTP, mêmes cookies, même navigateur. Une session dépareillée est la première cause de rejet après résolution.
CaptchaAI expose une API unique sur l'ensemble des familles prises en charge (reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, image/OCR, grilles). Si la famille change sur la page, vous ajustez le type de tâche et conservez la même boucle.
Étapes du workflow de résolution
Respectez cet ordre dans votre composant, quel que soit le type de défi :
- Capturez uniquement les paramètres utiles (sitekey, URL, action, proxy éventuel), relevés sur la page ou l'appel réseau réel. Stocker davantage crée de fausses pistes de débogage.
- Soumettez la tâche à l'API CaptchaAI et récupérez son identifiant. Traitez tout statut d'échec comme une erreur : journalisez la réponse et remontez-la vers votre supervision.
- Interrogez le résultat à cadence fixe, avec un premier délai d'attente et un plafond dur par tâche, pour éviter la surcharge comme les workflows qui traînent.
- Injectez le token dans la même session que celle qui a affiché le défi, puis poursuivez le parcours.
- Mesurez la latence, les retries et l'acceptation en aval. La réussite de la résolution et celle du workflow sont deux métriques distinctes : suivez les deux.
Gestion des secrets et de la clé API
La clé CaptchaAI ne vit jamais dans le code source ni dans un composant ToolJet exporté. Rangez-la dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret CI, monté en variable d'environnement au runtime. Prévoyez une rotation : si la clé fuite dans un log ou un export, vous devez pouvoir la révoquer sans réécrire l'intégration.
Exemple : appel côté serveur
Voici un appel HTTP côté serveur qui crée une tâche Turnstile et renvoie son identifiant, la clé étant lue depuis l'environnement, jamais codée en dur :
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 est identique dans les autres langages : soumettre, récupérer un identifiant, interroger le résultat, puis transposer la boucle vers Python, Go, Ruby ou Java sans surprise.
Observabilité et journalisation
Instrumentez chaque appel CAPTCHA pour obtenir des signaux exploitables : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file interne. Séparez les journaux par environnement et corrélez chaque identifiant à votre traçage distribué (par exemple OpenTelemetry) pour rejouer un scénario complet à partir d'un seul identifiant. Si vous journalisez des données liées à un utilisateur final, appliquez la minimisation du RGPD : ne conservez que l'utile au débogage, avec une durée de rétention fixée.
Indicateurs à suivre
Trois indicateurs suffisent à défendre l'intégration, câblés dans le tableau de bord que vous utilisez déjà : la latence de première résolution (sa médiane reste basse tant qu'il n'y a pas de retries), le taux de réussite par famille de CAPTCHA (une chute signale des paramètres erronés ou un défi qui a changé) et l'acceptation de bout en bout après token, ce que le client voit réellement.
Dépannage
Les erreurs ci-dessous couvrent la plupart des tickets de support.
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace parasite ou mauvais compte. | Recopiez la clé depuis le tableau de bord et stockez-la en secret CI. |
ERROR_ZERO_BALANCE |
Solde en dessous du minimum par tâche. | Rechargez le solde et ajoutez une alerte de seuil sur le tableau de bord. |
ERROR_PAGEURL / ERROR_BAD_PARAMETERS |
Paramètre manquant ou mal formé. | Revalidez l'URL, 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 qui a affiché le défi. | Gardez la résolution et l'envoi du formulaire dans le même contexte HTTP ou navigateur. |
Liste de contrôle avant mise en production
- Le périmètre est strictement limité à vos propres applications ou à des sources autorisées.
- La clé CaptchaAI est stockée dans un coffre ou un secret CI, jamais dans le code source.
- 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.
- Les tests d'intégration sont rejouables depuis votre intégration continue.
FAQ
Comment injecter un token CAPTCHA depuis un composant ToolJet ?
Faites appeler l'API CaptchaAI par un nœud serveur, récupérez le token, puis passez-le à l'action qui soumet le formulaire ou la requête protégée. L'injection doit se faire dans la même session que celle qui a déclenché le défi, sinon le token est rejeté.
CaptchaAI prend-il en charge hCaptcha depuis un workflow ToolJet ?
Non — hCaptcha n'est pas pris en charge, pas plus que FunCaptcha (Arkose Labs). CaptchaAI couvre reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, l'image/OCR et les grilles ; GeeTest v4 est à venir, et CaptchaFox, Friendly Captcha et Lemin sont en bêta.
Quel plan CaptchaAI choisir pour un workflow ToolJet en production ?
La facturation est basée sur les threads (défis simultanés), avec un nombre illimité de résolutions par thread. Un workflow séquentiel ou faiblement concurrent tient sur BASIC ($15/mois, 5 threads) ; montez en gamme selon votre concurrence mesurée, pas selon le volume total.
Guides connexes
- Le guide de démarrage rapide CaptchaAI
- Tester les CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- Intégrer la résolution de CAPTCHA dans la CI
- Résoudre reCAPTCHA v2 via l'API
Fiabilisez vos workflows CAPTCHA avec une approche méthodique et reproductible. – Obtenez votre clé CaptchaAI.
