Périmètre sûr : ce guide s'applique exclusivement à 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 le contournement de protections, ni l'évasion d'anti-bot.
Une Supabase Edge Function s'exécute côté serveur, sur l'infrastructure Deno de Supabase, sans navigateur ni interface graphique. Pour franchir une étape protégée par un CAPTCHA depuis ce contexte, vous n'automatisez donc pas un navigateur : vous appelez l'API CaptchaAI en HTTPS, vous récupérez un token, puis vous le transmettez à votre formulaire ou à votre route d'API. Reste à rendre cet appel stable en production, pas seulement lors d'une première démonstration.
Ce qui se joue dans une Edge Function
Le piège classique : la résolution paraît triviale dans un notebook local, puis se casse dès qu'elle tourne sans surveillance. Une Edge Function ajoute deux contraintes propres au serverless : la durée d'exécution est bornée, et l'environnement est éphémère — pas de disque persistant, pas d'état entre deux invocations. Votre intégration doit donc rester courte et observable. C'est ce que vise l'API CaptchaAI : un contrat unique pour l'ensemble des types pris en charge (reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, image/OCR et grilles), une latence prévisible, et une facturation par thread qui ne vous pénalise pas quand le volume monte.
Gérer les secrets avant tout
La clé CaptchaAI ne vit jamais dans le code source. Dans une Edge Function, stockez-la comme secret de projet Supabase, puis lisez-la au runtime via Deno.env.get. Hors Supabase, la même logique s'applique avec un coffre (HashiCorp Vault, AWS Secrets Manager) ou un secret de CI monté en variable d'environnement. Attention au copier-coller : une clé récupérée avec un espace résiduel produit une erreur ERROR_WRONG_USER_KEY difficile à diagnostiquer.
Architecture cible
Le schéma reste simple. Votre Edge Function appelle CaptchaAI pour créer une tâche, récupère un identifiant de tâche, interroge le résultat jusqu'à obtenir le token, puis injecte ce token dans la requête qui poursuit votre flux — même session, même client HTTP. Tracez chaque étape : vous repérez ainsi une régression avant qu'une alerte utilisateur ne la signale.
Un point d'attention propre au serverless : le polling doit tenir dans le budget de temps de la fonction. Prévoyez un délai avant la première interrogation, un intervalle régulier ensuite, et un plafond dur par tâche pour ne jamais dépasser la durée maximale. Si votre flux tolère l'asynchrone, déportez le polling vers un second appel ou une tâche planifiée plutôt que de bloquer une seule invocation.
Exemple de code
Appel HTTP côté serveur pour créer une tâche Turnstile et récupérer son identifiant :
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 même contrat vaut pour les autres types : vous changez le type de la tâche et vous conservez la boucle de création et d'interrogation. L'intégration reste ainsi portable vers Python, Go ou Java.
Observabilité et journalisation
Instrumentez les appels CAPTCHA pour obtenir des métriques exploitables : durée totale d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente interne. Ces signaux vous permettent de distinguer deux réussites bien différentes : la résolution du CAPTCHA d'un côté, l'acceptation du token par votre système en aval de l'autre.
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 identifiant unique. Côté conformité, appliquez la sobriété que le RGPD encourage : ne journalisez pas de données personnelles superflues et vérifiez vos obligations avant de conserver des charges utiles complètes.
Dépannage
La plupart des incidents se ramènent à une poignée de causes. Gardez ce tableau à portée de code review.
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace résiduel ou mauvais compte. | Recopiez la clé depuis le tableau de bord et stockez-la comme secret. |
ERROR_ZERO_BALANCE |
Solde inférieur au minimum par tâche. | Rechargez le solde et ajoutez une alerte de seuil. |
ERROR_PAGEURL / ERROR_BAD_PARAMETERS |
Un paramètre requis est absent ou mal formé. | Revalidez l'URL de la page et le sitekey face au HTML réel. |
| Token refusé après résolution | Token appliqué dans une session différente de celle qui a déclenché le défi. | Conservez la résolution et l'envoi dans la même session HTTP. |
| Délai dépassé dans l'Edge Function | Polling non borné qui bloque l'invocation. | Fixez un plafond dur par tâche ou déportez l'attente en asynchrone. |
Tester avant de déployer
Ajoutez des tests d'intégration sur vos endpoints critiques. Une équipe hébergée près de Paris mesurera une latence différente d'une équipe nord-américaine : figez ces attentes dans des seuils par environnement, pas dans une valeur unique. Le test de l'endpoint API sur vos propres formulaires et l'intégration CAPTCHA dans votre CI transforment ces vérifications en garde-fous rejouables à chaque merge.
Liste de contrôle avant fusion
| Contrôle | Réglage recommandé |
|---|---|
| Périmètre | Strictement vos applications ou des sources autorisées. |
| Clé API | Secret de projet ou coffre, jamais dans le code source. |
| Budget de polling | Délai initial, intervalle régulier, plafond dur par tâche. |
| Traçabilité | Durées d'appel et codes retour tracés à chaque exécution. |
| Retry | Backoff exponentiel borné sur les erreurs transitoires. |
| Tests | Rejouables depuis votre intégration continue. |
FAQ
Comment stocker la clé API CaptchaAI dans une Supabase Edge Function ?
Comme un secret de projet, jamais en dur. Déclarez le secret côté Supabase, puis lisez-le au runtime via Deno.env.get ; hors Supabase, montez-le en variable d'environnement depuis un coffre. Ne le commitez jamais et prévoyez une rotation en cas de fuite.
La limite de durée d'une Edge Function pose-t-elle problème pour le polling ?
Elle peut le devenir si vous bloquez une seule invocation en attendant un token lent. Bornez le polling — délai initial, intervalle régulier, plafond dur par tâche — pour rester sous la durée maximale, et déportez l'attente vers une tâche planifiée quand le flux le permet.
CaptchaAI prend-il en charge hCaptcha depuis une Edge Function ?
Non — hCaptcha n'est pas encore pris en charge, pas plus que FunCaptcha (Arkose Labs). L'API couvre reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, l'image/OCR et les grilles, avec CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta). GeeTest v4 est annoncé à venir.
Quel plan CaptchaAI choisir pour un worker planifié ?
Cela dépend de votre concurrence, pas de votre volume total : la facturation se fait par thread, avec un nombre de résolutions illimité par thread. Un job planifié à faible parallélisme démarre confortablement sur BASIC ($15/mois, 5 threads) ; passez au palier supérieur quand plusieurs tâches se chevauchent.
Guides connexes
- Le démarrage rapide CaptchaAI
- La QA des CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- Intégrer la résolution 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.
