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 porte ni sur l'automatisation de sites tiers, ni sur les techniques anti-détection.
Deno Deploy exécute vos fonctions à la périphérie, sans système de fichiers persistant et sans processus longue durée : la résolution d'un CAPTCHA doit donc passer par un simple appel HTTPS. Concrètement, vous appelez l'API CaptchaAI avec fetch, vous récupérez un token, puis vous l'injectez dans la requête qui poursuit votre parcours. Tout le reste — clé stockée en secret, appels tracés, métriques par environnement — sert à rendre l'intégration stable une fois qu'elle tourne sans surveillance.
Ce que Deno Deploy impose à votre intégration
Deno Deploy est un environnement serverless : pas de disque, pas d'état conservé entre deux requêtes, et une API réseau conforme aux standards du Web. C'est une bonne nouvelle, car fetch est disponible nativement, sans dépendance à installer. Mais cela fixe deux règles. D'abord, aucune clé en clair dans le code : le secret se déclare dans le tableau de bord Deno Deploy et se lit via les variables d'environnement. Ensuite, chaque appel doit être borné dans le temps, car une fonction edge n'a pas vocation à attendre indéfiniment un résultat.
Pour les équipes francophones qui hébergent déjà sur OVHcloud ou Scaleway, la logique reste identique : seule change la manière de monter le secret. La résolution, elle, passe toujours par le même endpoint HTTPS.
Architecture cible
Votre fonction Deno Deploy appelle CaptchaAI via HTTPS pour obtenir un token, puis l'injecte dans le formulaire ou la route d'API qui déclenche le défi. Tracez chaque étape — envoi de la tâche, obtention du token, acceptation en aval — pour repérer immédiatement une régression après une montée de version.
Gardez surtout la résolution et la soumission dans la même session : un token appliqué dans un contexte différent de celui qui a déclenché le défi (autre client HTTP, autre jar de cookies) est la cause la plus fréquente de rejet après résolution.
Gérer la clé API comme un secret
La clé CaptchaAI ne vit jamais dans le dépôt. Sur Deno Deploy, déclarez-la comme variable d'environnement de projet ; en CI ou sur un hébergeur classique, utilisez un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) et montez la valeur au runtime. Le code se contente de lire process.env.CAPTCHAAI_KEY, sans jamais connaître la valeur réelle : une rotation de clé se fait alors sans toucher au code.
Exemple d'appel côté serveur
Voici un appel HTTP côté serveur, dans votre propre service, qui crée une tâche et renvoie 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;
}
L'appel reste volontairement minimal : il envoie les seuls paramètres attendus (clé, type de tâche, URL et sitekey) et renvoie l'identifiant de tâche. L'interrogation du résultat se fait ensuite dans une boucle bornée, avec un plafond de temps par tâche pour ne jamais bloquer une fonction edge.
Observabilité et journalisation
Instrumentez chaque appel 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 chaque identifiant à votre traçage distribué, par exemple via OpenTelemetry. Vous pourrez ainsi rejouer un scénario complet à partir d'un seul identifiant ; en cas d'incident, ces journaux réduisent nettement le temps de diagnostic.
Les métriques à suivre
Quatre indicateurs suffisent à savoir si l'intégration se porte bien :
- La latence de résolution (médiane et p95) : elle révèle si vous attendez des tentatives supplémentaires.
- Le taux de réussite par famille de CAPTCHA : un paramètre d'entrée erroné se voit d'abord ici.
- L'acceptation en aval : une tâche résolue n'est pas une tâche acceptée ; suivez le statut HTTP qui suit l'injection du token.
- Le coût par résolution acceptée : stable sur la semaine, il confirme que les nouvelles tentatives ne grignotent pas votre budget.
La facturation CaptchaAI repose sur des threads simultanés, avec des résolutions illimitées par thread : le plan BASIC ($15/mois, 5 threads) suffit à un worker unique, et vous montez en threads quand le volume augmente.
Liste de contrôle avant la mise en production
- Le périmètre reste strictement limité à vos propres applications ou à des sources autorisées.
- La clé CaptchaAI est stockée en secret (variable Deno Deploy, coffre ou secret CI), jamais dans le code.
- Les durées d'appel et les codes retour sont tracés à chaque exécution.
- Une stratégie de retry idempotent, avec backoff exponentiel borné, couvre les erreurs transitoires.
- Les tests d'intégration sont rejouables depuis votre intégration continue.
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace parasite ou mauvais compte. | Recopiez la clé depuis le tableau de bord et stockez-la en secret. |
ERROR_KEY_DOES_NOT_EXIST |
Clé de projet erronée ou clé ayant fait l'objet d'une rotation. | Vérifiez la clé active dans le tableau de bord et régénérez le secret. |
ERROR_ZERO_BALANCE |
Solde inférieur au minimum requis par tâche. | Rechargez le solde et ajoutez une alerte de solde bas. |
| 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 la soumission dans la même session HTTP. |
FAQ
Comment stocker la clé API CaptchaAI sur Deno Deploy ?
Déclarez-la comme variable d'environnement de projet dans le tableau de bord Deno Deploy, puis lisez-la via process.env.CAPTCHAAI_KEY. La clé n'apparaît jamais dans le dépôt ni dans les logs. En CI ou sur un hébergeur classique, montez la même valeur depuis un coffre au runtime.
Une seule intégration suffit-elle pour plusieurs types de CAPTCHA ?
Oui. CaptchaAI expose un endpoint unique pour les principales familles — reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, image/OCR et grilles d'images. Vous changez le type de tâche et conservez la même boucle d'envoi et d'interrogation, sans réécrire votre intégration.
Comment tracer un incident de résolution en production ?
Corrélez l'identifiant de tâche à votre traçage distribué et journalisez, pour chaque appel, la durée, le code retour et l'environnement. À partir d'un seul identifiant, vous rejouez le scénario complet et distinguez un échec de résolution d'un rejet en aval.
Cette approche est-elle compatible avec le RGPD ?
Oui, à condition de minimiser les données personnelles collectées et de ne journaliser que les métadonnées techniques (identifiants de tâche, durées, codes retour), jamais le contenu des formulaires. Vérifiez vos obligations RGPD dès que le parcours touche des données d'utilisateurs.
Guides connexes
- le guide de démarrage rapide CaptchaAI
- la résolution de CAPTCHA en environnement de test autorisé
- tester l'endpoint API sur vos formulaires
- intégrer la résolution CAPTCHA à votre CI
- résoudre reCAPTCHA v2 via l'API
Passez d'un prototype à une intégration reproductible et surveillée. – Obtenez votre clé CaptchaAI.
