Résolution de CAPTCHAs depuis un Softr Custom Action

Périmètre sûr : ce guide s'applique uniquement à 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 couvre ni l'automatisation de sites tiers, ni l'évasion d'anti-bot.

Une Custom Action Softr déclenche du code côté serveur quand l'utilisateur valide un formulaire ou une étape du parcours. C'est là qu'un appel à CaptchaAI s'insère : l'action récupère un token, puis le transmet à la route protégée avant de laisser le workflow continuer. Pour une agence qui livre cette intégration à un client, l'enjeu n'est pas de faire tourner le flux une fois en démo, mais de le rendre assez stable pour survivre à la reprise par une autre équipe.

Où CaptchaAI s'insère dans le parcours Softr

Votre composant interne appelle CaptchaAI en HTTPS pour obtenir un token, puis l'injecte dans le formulaire ou la route d'API qui attend la validation. Gardez la frontière nette : la Custom Action orchestre, CaptchaAI résout, votre backend vérifie. Tracer chaque étape — envoi, interrogation du résultat, injection du token — facilite la détection des régressions quand Softr ou le fournisseur du CAPTCHA change de version.

Une seule API couvre les familles rencontrées le plus souvent sur ce type de page :

• reCAPTCHA v2 et v3 ;
• Cloudflare Turnstile et Cloudflare Challenge ;
• GeeTest v3 ;
• CAPTCHA image/OCR et en grille.

Seul le type de tâche change d'une famille à l'autre ; la boucle d'envoi et d'interrogation reste la même.

Le flux, étape par étape

1. Collectez les paramètres du défi. Relevez sur la page uniquement ce que la famille de CAPTCHA attend : sitekey, URL de la page, et éventuellement une action ou un proxy.
2. Envoyez la tâche à CaptchaAI depuis la Custom Action et contrôlez le statut de la réponse ; journalisez toute réponse inattendue.
3. Interrogez le résultat jusqu'à obtenir le token, avec un plafond de tentatives pour éviter les boucles infinies.
4. Injectez le token dans la même session que celle qui a déclenché le défi, puis laissez le backend vérifier.

Gérer la clé API sans la coder en dur

Dans un projet no-code, coller la clé directement dans la configuration est tentant — et c'est exactement ce qu'il faut éviter. La clé CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret de votre CI ; le déploiement la monte en variable d'environnement au runtime, et la Custom Action la lit depuis cet environnement, jamais depuis le code versionné.

Prévoyez une clé distincte par environnement : vous la ferez tourner sans redéployer et limiterez la surface exposée. Côté conformité, minimisez les données personnelles transmises dans ces appels et vérifiez vos obligations RGPD avant de journaliser des charges utiles complètes.

Exemple : appel côté serveur

Appel HTTP côté serveur, dans votre propre service, pour créer une tâche Turnstile :

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;
}

Cette fonction renvoie un identifiant de tâche ; la Custom Action interroge ensuite le résultat, puis injecte le token dans la même session que celle qui a déclenché le défi. Un token appliqué dans une session différente est la cause la plus fréquente de rejet après résolution.

Observabilité et journalisation

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 interne. Ces signaux alimentent vos tableaux de bord de QA et séparent deux mesures qu'on confond souvent : la réussite de la résolution et celle du workflow en aval.

Isolez les journaux par environnement (développement, préproduction, production) et corrélez chaque identifiant à votre traçage distribué, par exemple via OpenTelemetry. Vous pourrez alors rejouer un scénario complet depuis un identifiant unique, ce qui réduit nettement le temps de diagnostic.

Liste de contrôle avant la mise en production

• Le périmètre reste 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.
• Un retry idempotent, avec backoff exponentiel borné, couvre les erreurs transitoires.
• Le token est toujours injecté dans la session qui a déclenché le défi.
• Les tests sont rejouables depuis votre intégration continue.

Dépannage

Les erreurs ci-dessous couvrent l'essentiel des tickets sur ce type d'intégration. Chaque ligne se corrige sans quitter votre éditeur.

FAQ

Comment appeler CaptchaAI depuis une Custom Action Softr ?

Faites l'appel côté serveur, jamais depuis le navigateur. L'action envoie la tâche à l'API CaptchaAI, interroge le résultat jusqu'à obtention du token, puis le transmet à la route qui attend la validation. La clé API n'est ainsi jamais exposée côté client.

Quels CAPTCHA cette approche permet-elle de résoudre ?

Les familles prises en charge par CaptchaAI : reCAPTCHA v2 et v3, Cloudflare Turnstile et Cloudflare Challenge, GeeTest v3, ainsi que les CAPTCHA image/OCR et en grille. Seul le type de tâche change selon le défi présent sur la page.

Faut-il un navigateur headless pour cette intégration ?

Non. La Custom Action dialogue avec l'API CaptchaAI en HTTP, sans piloter de navigateur : elle envoie les paramètres du défi et récupère un token. Un navigateur headless n'entre en jeu que si votre propre parcours en dépend déjà par ailleurs, jamais pour l'appel à CaptchaAI lui-même.

Guides connexes

• le guide de démarrage rapide CaptchaAI
• la QA CAPTCHA en environnements autorisés
• tester l'endpoint API sur vos formulaires
• l'intégration CAPTCHA en CI
• résoudre reCAPTCHA v2 via l'API

Fiabilisez vos workflows CAPTCHA avec une approche méthodique et reproductible. – Obtenez votre clé CaptchaAI.