Appeler CaptchaAI depuis une Cloud Function FlutterFlow

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 décrit ni l'automatisation de sites tiers, ni la résolution de protections que vous n'avez pas mandat de gérer.

FlutterFlow ne doit pas appeler un service de résolution de CAPTCHA directement depuis l'application : votre clé API se retrouverait exposée dans le client, et la boucle d'interrogation du résultat n'a rien à faire côté interface. La réponse propre est une Cloud Function : elle reçoit la demande de votre app FlutterFlow, appelle CaptchaAI côté serveur, récupère un token, puis le renvoie sans jamais divulguer votre clé.

Pourquoi centraliser l'appel dans une Cloud Function

Une Cloud Function (déployée sur Firebase ou Google Cloud Functions) sert de point de passage unique entre votre app FlutterFlow et l'API CaptchaAI. Ce choix apporte trois bénéfices concrets :

• Le secret reste serveur. La clé API n'est jamais compilée dans le bundle Flutter distribué aux appareils ; elle vit dans la configuration de la fonction, hors du dépôt.
• La logique est observable. Un seul endroit émet les appels, mesure les durées et journalise les codes retour : un incident se rattache à un identifiant unique plutôt qu'à des logs éparpillés dans le client.
• La conformité est plus simple. Concentrer le traitement côté serveur minimise les données personnelles qui transitent, un point utile pour documenter vos obligations RGPD.

Côté facturation, le modèle reste économique quand le trafic monte : CaptchaAI facture au thread (par exemple BASIC à $15/mois, 5 threads), avec des résolutions illimitées par thread. C'est votre allocation de threads qui borne le débit, pas un tarif au CAPTCHA résolu.

De la requête au token : le flux côté serveur

À l'intérieur de la fonction, le déroulé est toujours le même, quel que soit le type de défi (reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile ou image/OCR) :

1. Ne capturez que le strict nécessaire : le sitekey, l'URL de la page et, le cas échéant, l'action ou le proxy.
2. Soumettez la tâche à l'API CaptchaAI et traitez tout statut non conforme comme une erreur : journalisez la réponse et alertez votre supervision.
3. Interrogez le résultat à intervalle régulier plutôt qu'en boucle serrée : un délai avant la première interrogation, des appels espacés et un plafond par tâche.
4. Renvoyez le token à l'app, qui l'injecte dans la même session que celle ayant déclenché le défi. Une session dépareillée est la première cause de rejet après résolution.

Sécuriser la clé API et les données

La clé CaptchaAI se stocke dans la configuration d'environnement de la fonction (variables Firebase, Google Secret Manager) ou dans un secret d'intégration continue, jamais dans le code source. Le déploiement la monte en variable au runtime, et la rotation se fait sans toucher au code.

Pour la latence, hébergez la fonction dans une région proche de vos utilisateurs — europe-west9 (Paris) convient à une audience francophone.

Exemple : créer une tâche Turnstile depuis Node.js

L'appel côté serveur reste minimal : la fonction reçoit un siteKey et une pageUrl, soumet la tâche et récupère un identifiant à interroger ensuite :

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 taskId retourné alimente une seconde requête qui interroge le résultat. Isolez cette logique dans une fonction dédiée : elle reste identique quel que soit le type de CAPTCHA, seul le champ type de la tâche change.

Mesurer la réussite de l'intégration

Ce que vous ne mesurez pas, vous ne pouvez pas le défendre devant un client. Branchez ces indicateurs sur le tableau de bord de l'application :

• Latence d'obtention du token (médiane et P95), pour vérifier que la file n'attend pas sur des retries.
• Taux de réussite de résolution par type de CAPTCHA, cible ≥ 95 %, signe que vos paramètres correspondent au défi.
• Acceptation de bout en bout après injection du token, à suivre séparément : elle confirme que la même session accepte le token.
• Coût par résolution acceptée, stable sur la semaine tant que les boucles de mauvais paramètres restent maîtrisées.

Ces seuils dépendent de votre environnement et de votre volume : mesurez les vôtres avant d'en faire un engagement client.

Liste de contrôle avant la mise en production

• Le périmètre est strictement limité à vos propres applications ou à des sources autorisées.
• La clé CaptchaAI vit dans un secret CI ou un coffre, jamais dans le bundle Flutter ni dans le dépôt.
• Chaque appel trace sa durée, son code retour HTTP et son identifiant de tâche.
• Une stratégie de 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, et les tests d'intégration sont rejouables depuis votre CI.

Dépannage

FAQ

Pourquoi passer par une Cloud Function plutôt qu'un appel direct depuis FlutterFlow ?

Parce qu'un appel direct exposerait votre clé API dans l'application distribuée. La Cloud Function garde le secret côté serveur, centralise la journalisation et simplifie vos obligations RGPD.

Où stocker ma clé API CaptchaAI dans un projet Firebase ?

Dans la configuration d'environnement de la fonction ou dans Google Secret Manager, montée en variable au runtime — jamais dans le code du client Flutter ni dans un fichier suivi par Git. La rotation se fait en changeant le secret, sans redéployer de code.

Le token est refusé après la résolution : que vérifier en premier ?

Vérifiez d'abord la cohérence de session. Le token doit être injecté dans le même contexte (mêmes cookies, même client HTTP) que celui qui a affiché le défi. Contrôlez ensuite que le sitekey et l'URL correspondent à la page réelle.

Cette intégration fonctionne-t-elle avec d'autres types de CAPTCHA ?

Oui. Le contrat submit/poll reste identique pour reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3 et les CAPTCHA image/OCR. Vous changez le type de tâche envoyé, pas la structure de la fonction.

Guides connexes

• Démarrage rapide CaptchaAI
• QA CAPTCHA en environnements autorisés
• Tester l'endpoint API sur vos formulaires
• Intégration CAPTCHA dans votre CI
• Résoudre reCAPTCHA v2 via l'API

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