Périmètre sûr : ce guide couvre uniquement vos propres applications Nuxt 3 et les environnements pour lesquels vous détenez une autorisation écrite. Il ne traite ni de l'automatisation de sites tiers, ni du contournement de protections, ni de l'évasion de systèmes anti-bot.
Dans Nuxt 3, une server route s'exécute côté serveur, dans le moteur Nitro. C'est donc là que doit vivre l'appel à CaptchaAI pour obtenir un token, jamais dans le navigateur : la clé API reste privée et la logique de résolution ne fuite pas vers le client. Ce guide montre comment câbler cette intégration proprement — secrets, journalisation, dépannage — pour qu'elle tienne en production, pas seulement sur une démo.
L'écueil arrive plus tard : le flux tourne en cinq minutes dans un server/api/… isolé, puis échoue dès qu'il s'exécute sans surveillance. L'architecture ci-dessous absorbe les déploiements, les coupures réseau et les changements de famille de CAPTCHA sans intervention manuelle.
Pourquoi résoudre le CAPTCHA côté serveur dans Nuxt 3
Placer l'appel dans une server route apporte trois bénéfices. La clé API n'atteint jamais le navigateur, donc elle ne se retrouve ni dans le bundle client ni dans les outils de développement.
La résolution se centralise ensuite à un seul endroit, ce qui simplifie l'instrumentation et les tests. Enfin, elle tourne dans le même runtime que vos jobs CI et vos tâches cron.
Architecture cible
Votre server route appelle CaptchaAI via HTTPS pour récupérer un token, puis l'injecte dans le formulaire ou la route d'API qui poursuit le parcours. Un seul module côté serveur porte la clé, la soumission et le polling ; le reste de l'application ne voit qu'un token prêt à l'emploi.
Tracez chaque étape : une régression opaque après une montée de version devient alors un diagnostic de quelques secondes plutôt qu'une enquête à l'aveugle.
Le flux d'appel, étape par étape
L'enchaînement reste le même quelle que soit la famille de CAPTCHA ; seuls les paramètres d'entrée changent.
- Capturez les bons paramètres. Inspectez la page ou l'appel réseau réel et ne récupérez que ce que le solveur attend (sitekey, URL, action, proxy éventuel). Stocker davantage crée de fausses pistes de débogage.
- Soumettez la tâche et vérifiez le statut de la réponse. Tout statut inattendu est une erreur : journalisez la réponse complète et remontez-la vers votre supervision.
- Interrogez le résultat (polling) à intervalle régulier, avec un court délai initial et un plafond strict par tâche. N'interrogez ni trop vite (bruit, charge) ni trop lentement (workflow ralenti).
- Appliquez le token dans la même session que celle qui a déclenché le défi : même contexte, même client HTTP, même cookie jar. Une session dépareillée est la première cause de rejet après résolution.
- Mesurez la latence, les retries et l'acceptation en aval. Réussite du solveur et réussite du workflow sont deux métriques distinctes.
Exemple : appeler CaptchaAI depuis une server route Nuxt 3
Voici un appel HTTP côté serveur, tel qu'il vivrait dans une server route Nuxt 3 (server/api/solve.post.ts) ou dans un service dédié :
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 fonction renvoie un taskId que vous interrogez jusqu'à obtention du token. L'exemple cible Cloudflare Turnstile, mais le même contrat — soumettre puis interroger — vaut pour reCAPTCHA v2, reCAPTCHA v3, GeeTest v3 ou les CAPTCHA image.
Gérer les secrets et la configuration
La clé CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou un secret CI, jamais dans le code source ni dans un .env committé. Le déploiement la monte en variable d'environnement au runtime Nitro, où la server route la lit via process.env. Prévoyez une clé distincte par environnement pour la faire tourner sans toucher au code.
Observabilité et journalisation
Instrumentez chaque appel CAPTCHA : durée totale d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file interne. Ces signaux alimentent vos tableaux de bord de QA et vos alertes.
Séparez les journaux par environnement et conservez les identifiants corrélés à votre traçage distribué (OpenTelemetry, par exemple) pour rejouer un scénario complet à partir d'un identifiant unique. Côté RGPD, ne journalisez que les métadonnées techniques et évitez d'y écrire des données personnelles issues du formulaire résolu.
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
Clé refusée (ERROR_WRONG_USER_KEY) |
Espace parasite dans la clé ou mauvais compte | Recopiez la clé depuis le tableau de bord, stockez-la en secret CI |
ERROR_ZERO_BALANCE |
Solde sous le minimum par tâche | Rechargez le solde et ajoutez une alerte de seuil |
| Token refusé après résolution | Token appliqué dans une autre session que le défi | Gardez résolution et soumission dans la même session HTTP |
| Timeout systématique du polling | Interrogation trop précoce ou intervalle trop court | Attendez avant la première interrogation, plafonnez par tâche |
500 intermittent sur la server route |
Secret non monté dans le runtime Nitro | Vérifiez l'injection de la variable d'environnement au déploiement |
Mesurer la réussite
Suivez la latence d'obtention du token (médiane et p95), le taux de réussite du solveur par famille, l'acceptation en aval après injection, et le coût par résolution acceptée.
La distinction clé : une tâche résolue n'est pas un workflow réussi. Alertez sur l'écart entre les deux — c'est lui qui révèle une session dépareillée ou un paramètre erroné.
Liste de contrôle avant la mise en production
- Le périmètre est 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 ni dans le bundle client.
- L'appel de résolution vit dans une server route, pas dans du code exécuté par le navigateur.
- Les durées, codes retour et identifiants de tâche sont tracés à chaque exécution.
- Un retry idempotent avec backoff exponentiel borné couvre les erreurs transitoires.
- Les tests d'intégration sont rejouables depuis votre intégration continue.
FAQ
Où doit vivre l'appel CaptchaAI dans une application Nuxt 3 ?
Dans une server route (server/api/… ou server/routes/…), exécutée côté serveur via Nitro. C'est le seul endroit où la clé reste privée et où la journalisation se centralise. Le client ne reçoit que le token ou le résultat final.
Dois-je exposer ma clé API CaptchaAI au navigateur ?
Non. La clé ne doit jamais figurer dans le code client ni dans runtimeConfig.public. Placez-la dans un secret CI ou un coffre, montez-la en variable d'environnement, et lisez-la uniquement depuis la server route.
Quel plan CaptchaAI choisir pour une intégration Nuxt 3 ?
Le plus petit plan, BASIC ($15/mois, 5 threads), suffit pour démarrer. La facturation repose sur les threads simultanés (un thread = un CAPTCHA en cours), avec des résolutions illimitées par thread ; vous montez en gamme quand votre parallélisme augmente, pas à chaque résolution.
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 à la CI
- Résoudre reCAPTCHA v2 via l'API
Fiabilisez vos workflows CAPTCHA avec une approche méthodique et reproductible. – Obtenez votre clé CaptchaAI.
