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 les techniques d'évasion des protections anti-bot.
Une fonction Appwrite s'exécute en quelques secondes puis s'arrête : c'est précisément ce qui rend la résolution d'un CAPTCHA délicate dans un environnement serverless. Obtenir un token prend généralement de l'ordre de 10 à 30 secondes, soit souvent plus que le délai d'exécution laissé à une fonction par défaut. Ce guide montre comment appeler l'API CaptchaAI depuis une fonction Appwrite sans que celle-ci n'expire, où ranger la clé API, et comment tracer chaque appel pour garder l'intégration stable en production.
Pourquoi résoudre un CAPTCHA depuis une fonction Appwrite demande un peu de méthode
Trois contraintes propres au serverless expliquent pourquoi un script qui marche sur votre poste casse une fois déployé :
- Le timeout d'exécution. Si la résolution dépasse le budget de temps de la fonction, celle-ci est tuée avant d'avoir récupéré le token. Alignez le timeout sur le temps de résolution réel, plus une marge (par exemple 60 s), au lieu de garder la valeur par défaut.
- L'absence d'état. Chaque invocation part d'un contexte vierge. Le token obtenu doit être utilisé immédiatement, dans la même exécution, par le client qui poursuit le flux.
- Les démarrages à froid. Un conteneur froid ajoute une latence en tête d'exécution : comptez-la dans votre budget de temps et mesurez-la séparément de celle du solveur.
Une fois ces trois points anticipés, le reste de l'intégration est standard : un appel HTTPS, un token, une injection dans votre formulaire ou votre route d'API.
Architecture recommandée pour une fonction Appwrite
Le schéma reste simple. Votre fonction reçoit une requête, appelle CaptchaAI en HTTPS pour récupérer un token, puis l'injecte dans le formulaire ou la route protégée que vous contrôlez. Tracez chaque étape : c'est ce qui vous permettra de repérer une régression lors d'une montée de version.
Gardez la résolution et l'usage du token dans la même invocation. Un token réutilisé plus tard, dans un autre contexte, est la cause la plus fréquente de rejet après résolution. Si votre parcours comporte plusieurs étapes, faites-le porter par une seule fonction plutôt que d'enchaîner des invocations qui perdraient le contexte.
Stocker la clé API CaptchaAI dans Appwrite
La clé ne doit jamais vivre dans le code source ni dans le dépôt Git. Deux options propres :
- Les variables d'environnement de la fonction Appwrite, chiffrées côté plateforme et montées au runtime.
- Un coffre externe (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) dont la valeur est injectée au déploiement, si votre équipe centralise déjà ses secrets.
Côté budget, CaptchaAI facture au thread, pas à la résolution : le plan BASIC ($15/mois, 5 threads) suffit pour une première intégration, et chaque thread traite un nombre illimité de résolutions dans le mois. Vous montez de palier uniquement quand votre concurrence réelle l'exige.
Exemple : créer une tâche Turnstile depuis la fonction
L'appel ci-dessous, côté serveur, crée une tâche Cloudflare Turnstile et renvoie l'identifiant de tâche. Vous interrogerez ensuite le résultat pour récupérer le token, puis vous l'appliquerez dans la même exécution.
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;
}
La même logique vaut pour reCAPTCHA v2, reCAPTCHA v3, Cloudflare Challenge ou GeeTest v3 : vous changez le type de tâche, vous gardez la boucle création puis interrogation du résultat. L'API étant identique d'un type à l'autre, le code que vous écrivez ici reste valable quand vous ajoutez de nouvelles familles de CAPTCHA.
Gérer le timeout et les nouvelles tentatives
Bornez chaque tentative : un backoff exponentiel plafonné (par exemple trois essais, doublement du délai à chaque tour, plafond à 30 s) vaut mieux qu'une boucle infinie qui consomme vos threads. Au-delà du plafond, échouez proprement et alertez.
Distinguez enfin deux métriques souvent confondues : la réussite de la résolution et celle du parcours. Un token obtenu ne garantit pas que la route en aval l'accepte. Suivez le code retour HTTP du service protégé séparément de la réponse du solveur, et alertez sur l'écart entre les deux.
Observabilité, journalisation et RGPD
Quel que soit le langage, instrumentez les appels CAPTCHA pour obtenir des signaux exploitables : durée totale d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente interne. Ces mesures alimentent vos tableaux de bord de QA et vos alertes.
Séparez les journaux par environnement (développement, préproduction, production) et corrélez-les à votre traçage distribué, par exemple via OpenTelemetry : en repartant d'un identifiant unique, vous rejouez un scénario complet et accélérez le diagnostic. Côté conformité, appliquez les principes du RGPD : ne journalisez que le strict nécessaire, évitez d'écrire des données personnelles dans les logs et vérifiez vos durées de conservation.
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 une variable d'environnement chiffrée ou un coffre, jamais dans le code.
- Le timeout de la fonction est aligné sur le temps de résolution réel, marge comprise.
- Le token est produit et utilisé dans la même invocation.
- Les durées d'appel et les codes retour sont tracés à chaque exécution.
- Une stratégie de retry idempotent couvre les erreurs transitoires.
- Les tests sont rejouables depuis votre intégration continue.
FAQ
Comment éviter que ma fonction Appwrite n'expire pendant la résolution ?
Augmentez le timeout de la fonction pour couvrir le temps de résolution du token, qui est de l'ordre de plusieurs dizaines de secondes selon le type, plus une marge pour le démarrage à froid. Bornez aussi vos tentatives côté code afin d'échouer proprement au lieu de laisser la plateforme tuer l'exécution.
Où stocker la clé API CaptchaAI dans Appwrite ?
Dans les variables d'environnement chiffrées de la fonction, ou dans un coffre externe injecté au déploiement si vous centralisez déjà vos secrets. Jamais en clair dans le code ni dans le dépôt Git : une clé qui fuit dans l'historique doit être révoquée immédiatement.
CaptchaAI prend-il en charge hCaptcha depuis une fonction serverless ?
Non, hCaptcha n'est pas pris en charge, pas plus que FunCaptcha (Arkose Labs). En revanche, reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3 ainsi que les CAPTCHA image/OCR et en grille le sont, avec la même boucle d'appel décrite plus haut.
Puis-je réutiliser ce schéma avec un autre fournisseur serverless ?
Oui. La logique création de tâche, interrogation du résultat, injection du token dans la même exécution est indépendante de la plateforme. Vous la transposez tel quel vers AWS Lambda, Azure Functions ou Google Cloud Functions, à condition de gérer partout le timeout et les secrets de la même façon.
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
Renforcez la qualité de vos workflows CAPTCHA avec une approche méthodique et reproductible. – Obtenez votre clé CaptchaAI.
