Résoudre les CAPTCHA dans les Server Actions de Next.js App Router

Périmètre sûr : ce guide s'applique uniquement à vos propres applications — environnements de développement, de préproduction ou de production — ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne traite ni de l'automatisation de sites tiers, ni de la résolution de défis sur des services que vous ne contrôlez pas.

Une Server Action de Next.js s'exécute côté serveur : le token CAPTCHA doit donc être obtenu, transmis et vérifié sur le serveur, jamais dans le navigateur du visiteur. Ce guide montre comment résoudre un CAPTCHA depuis une Server Action de Next.js App Router avec CaptchaAI, jusqu'à une intégration stable en production et en CI.

Pourquoi la résolution côté serveur change l'intégration

Les Server Actions du App Router tournent exclusivement sur le serveur : votre clé API et l'appel à CaptchaAI restent invisibles pour le client, et le token circule dans le même contexte que la requête à protéger. La surface exposée au navigateur se réduit, ce qui simplifie aussi vos obligations RGPD sur la journalisation.

Architecture cible

Votre Server Action appelle CaptchaAI via HTTPS pour récupérer un token, puis l'injecte dans le formulaire ou la route d'API protégée. Gardez la résolution et la soumission dans la même session — même contexte, même client HTTP — pour éviter le rejet du token.

Gérer la clé API et les secrets

La clé CaptchaAI ne vit jamais dans le code source. Stockez-la et injectez-la ainsi :

• dans un coffre (HashiCorp Vault, AWS Secrets Manager) ou un secret de CI ;
• montée en variable d'environnement au runtime par le déploiement ;
• jamais préfixée par NEXT_PUBLIC_, sous peine d'exposition dans le bundle client.

Le workflow de résolution, étape par étape

1. Capturez ce dont le solveur a besoin : uniquement les paramètres attendus par le type de CAPTCHA (sitekey, URL de la page, action, proxy éventuel).
2. Envoyez la tâche à l'API CaptchaAI et récupérez son identifiant ; traitez tout statut inattendu comme une erreur.
3. Interrogez le résultat (polling) avec un intervalle raisonnable et un plafond ferme par tâche, sans boucle infinie.
4. Appliquez le token dans la même session que celle qui a déclenché le défi : les sessions dépareillées sont la première cause de rejet.
5. Mesurez la latence, les retries et l'acceptation en aval : réussite de la résolution et réussite du workflow sont deux métriques distinctes.

Exemple de code

Exemple d'appel HTTP côté serveur dans votre propre service :

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;
}

Observabilité et journalisation

Instrumentez chaque appel CAPTCHA pour obtenir des signaux exploitables :

• la durée d'obtention du token et le code retour HTTP ;
• l'identifiant de tâche et la taille de la file d'attente interne ;
• des journaux séparés par environnement, corrélés à votre traçage distribué (OpenTelemetry).

Côté RGPD, minimisez les données personnelles écrites dans les logs : un identifiant technique suffit au diagnostic.

Déployer les workers sur une infrastructure proche

Héberger le service qui appelle CaptchaAI près de vos utilisateurs réduit la latence : un worker sur OVHcloud, Scaleway ou une région AWS eu-west-3 (Paris) facilite aussi la résidence des données en Europe. La facturation CaptchaAI est au thread, pas à la résolution : le plan BASIC ($15/mois, 5 threads) suffit à valider une intégration, facturé en dollars US.

Dépannage

Ces erreurs couvrent l'essentiel des tickets de support pour ce type d'intégration.

Liste de contrôle

• Le périmètre reste limité à vos propres applications ou à des sources autorisées.
• La clé CaptchaAI est stockée dans un secret de CI ou un coffre, jamais dans le bundle client.
• Les durées d'appel et les codes retour sont tracés pour chaque exécution.
• Une stratégie de retry idempotent, avec backoff exponentiel borné, gère les erreurs transitoires.

FAQ

Faut-il valider le token côté serveur ou côté client ?

Côté serveur. Dans une Server Action, la vérification du token se fait sur le serveur avant d'accepter la soumission. C'est l'intérêt du modèle : le client n'a jamais accès à la clé ni à la logique de validation.

Comment stocker la clé API CaptchaAI dans un projet Next.js ?

Dans une variable d'environnement lue uniquement côté serveur, sans le préfixe NEXT_PUBLIC_. En production, injectez-la depuis un secret de CI ou un coffre. Ne l'exposez jamais dans un composant client.

Le polling ralentit-il ma Server Action ?

Pas si vous bornez la boucle. Fixez un intervalle d'interrogation raisonnable et un plafond ferme par tâche : la Server Action attend le token puis poursuit, sans jamais rester bloquée sur une tâche récalcitrante.

Quel plan CaptchaAI choisir pour démarrer ?

Le plan BASIC ($15/mois, 5 threads) couvre une phase de validation et un trafic modéré. La facturation étant au thread avec résolutions illimitées, vous ajustez le nombre de threads à la concurrence réelle de vos Server Actions, pas au nombre de résolutions.

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

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