Retool + CaptchaAI : outil interne de gestion des formulaires CAPTCHA

Une application Retool ne sait pas cocher une case « Je ne suis pas un robot » : elle parle en requêtes HTTP, pas en clics. Le montage tient en trois objets Retool — une ressource API REST pointée sur CaptchaAI, deux requêtes vers /in.php et /res.php, et une requête JavaScript qui interroge le résultat — au bout desquels votre outil interne récupère un token g-recaptcha-response prêt à être posté.

Aucun composant sur mesure : uniquement des requêtes natives et le Secrets Store, sur Retool Cloud comme en auto-hébergé.

Ce qu'il faut avoir sous la main

Le scénario type : un back-office qui dépose un dossier

Une équipe administrative dépose depuis Retool des dossiers sur un portail public protégé par reCAPTCHA v2, jusqu'ici résolu à la main. L'application prend le relais :

1. Elle reçoit le sitekey et l'URL de la page en entrée
2. Elle envoie la tâche à CaptchaAI
3. Elle interroge régulièrement le résultat
4. Elle affiche le token résolu, réutilisé dans la soumission du formulaire

Côté RGPD, la séparation est simple à documenter : seuls le sitekey et l'URL publique transitent vers CaptchaAI, jamais les données personnelles du dossier.

Quel plan pour un outil interne

La facturation se fait au thread simultané : chaque plan inclut des résolutions illimitées par thread, et c'est le pic de résolutions en parallèle qui dimensionne l'abonnement, pas le volume mensuel. Un back-office de deux ou trois opérateurs tient dans BASIC ($15/mois, 5 threads) ; une application partagée entre agences se traite en STANDARD ($30/mois, 15 threads). Facturation en dollars US.

Étape 1 : déclarer CaptchaAI comme ressource API REST

Dans Retool, ouvrez Resources → Create New → REST API, puis enregistrez : toutes les requêtes suivantes s'y rattacheront.

Étape 2 : la requête submitCaptcha qui envoie la tâche

Sur la ressource CaptchaAI, créez une requête GET submitCaptcha pointée sur /in.php, puis renseignez ses paramètres :

Placez la clé API dans le Secrets Store de Retool (Settings → Secrets) plutôt qu'en dur : les créateurs d'applications voient la référence, pas la valeur. Un transformateur facultatif normalise ensuite la réponse :

// Parse the response
const data = {{ submitCaptcha.data }};
if (data.status === 1) {
  return { taskId: data.request, status: 'submitted' };
}
return { error: data.request, status: 'failed' };

Étape 3 : la requête pollResult qui interroge le résultat

Sur la même ressource, pollResult est aussi une requête GET, cette fois sur /res.php :

CAPCHA_NOT_READY n'est pas une erreur : le transformateur le distingue d'un vrai échec et laisse la boucle continuer.

const data = {{ pollResult.data }};
if (data.status === 1) {
  return { token: data.request, status: 'solved' };
}
if (data.request === 'CAPCHA_NOT_READY') {
  return { status: 'pending' };
}
return { error: data.request, status: 'error' };

Étape 4 : la boucle de polling en JavaScript

Une requête JavaScript nommée solveCaptcha orchestre l'ensemble. Le premier appel est différé de 15 secondes : un reCAPTCHA v2 se résout en moins de 60 secondes.

// solveCaptcha — JavaScript Query
async function solve() {
  // Submit the CAPTCHA task
  await submitCaptcha.trigger();
  const submitResult = submitCaptcha.data;

  if (submitResult.status !== 1) {
    return { error: submitResult.request, status: 'submit_failed' };
  }

  const taskId = submitResult.request;

  // Wait 15 seconds before first poll
  await new Promise(r => setTimeout(r, 15000));

  // Poll up to 20 times (100 seconds max)
  for (let i = 0; i < 20; i++) {
    await pollResult.trigger({
      additionalScope: { taskId: taskId }
    });

    const result = pollResult.data;

    if (result.status === 1) {
      return { token: result.request, status: 'solved' };
    }

    if (result.request !== 'CAPCHA_NOT_READY') {
      return { error: result.request, status: 'error' };
    }

    // Wait 5 seconds before next poll
    await new Promise(r => setTimeout(r, 5000));
  }

  return { error: 'Polling timeout', status: 'timeout' };
}

return solve();

Le budget tient sous la limite de 120 secondes de Retool sur les requêtes JavaScript :

• 15 s d'attente avant la première interrogation
• 20 itérations espacées de 5 s
• 115 s au pire, avant l'abandon contrôlé

Étape 5 : l'interface, en trois zones

Étape 6 : injecter le token dans la requête aval

Une dernière requête submitForm poste le dossier vers votre API cible : un POST dont le corps reprend les champs du formulaire et ajoute g-recaptcha-response: {{solveCaptcha.data.token}}.

Reliez-la à un bouton « Soumettre le formulaire » activé uniquement lorsque {{ solveCaptcha.data?.status === 'solved' }}. La durée de vie du token est courte : enchaînez la soumission.

Dépannage

Configuration et authentification

Timing et durée de vie du token

FAQ

Quel plan CaptchaAI faut-il pour un outil Retool utilisé par une dizaine de personnes ?

Comptez en résolutions simultanées : dix utilisateurs dispersés dans la journée dépassent rarement 5 threads. BASIC ($15/mois, 5 threads) suffit, STANDARD ($30/mois, 15 threads) absorbe les pics.

CaptchaAI prend-il en charge hCaptcha ou FunCaptcha depuis Retool ?

Non — ces deux types ne sont pas pris en charge. L'API couvre reCAPTCHA v2 et v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3, les CAPTCHA image et OCR et les grilles d'images ; GeeTest v4 est à venir. CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta) restent en phase bêta.

Comment tenir la limite de 120 secondes des requêtes JavaScript Retool ?

15 s d'attente puis 20 itérations de 5 s laissent une marge confortable. Au-delà, découpez le cycle avec un timer plutôt que d'allonger la boucle.

Comment empêcher les créateurs d'applications de lire la clé API ?

Stockez-la dans le Secrets Store et référencez-la via {{secretsStore.CAPTCHAAI_API_KEY}} : la requête n'expose que le nom du secret. Prévoyez une rotation à chaque révocation d'accès Retool.

Le token résolu peut-il être réutilisé plus tard ?

Non. Un token reCAPTCHA v2 est à usage unique et de courte validité. Déclenchez la résolution au moment de la soumission plutôt qu'en amont.

Articles connexes

• Résoudre le callback reCAPTCHA v2 via l'API
• Gérer reCAPTCHA v2 et Turnstile sur un même site
• Comprendre le mécanisme de callback reCAPTCHA v2
• Zapier + CaptchaAI : résoudre un CAPTCHA sans écrire de code
• Make (Integromat) + CaptchaAI : automatiser la résolution
• Extraire les paramètres reCAPTCHA depuis le code source

Prochaines étapes

Ouvrez votre compte CaptchaAI, récupérez votre clé API et déclarez la ressource API REST : votre première application Retool rendra un token le jour même.