Résoudre les CAPTCHA dans les fonctions serveur TanStack Start

Dans TanStack Start, le bon endroit pour appeler un service de résolution de CAPTCHA est une fonction serveur. La clé API reste côté serveur, elle n'atteint jamais le navigateur, et le token revient dans le même contexte que celui qui poursuivra le flux. C'est aussi la seule manière fiable de garder l'intégration stable quand elle tourne sans surveillance, en CI ou dans un cron. Ce guide montre comment la structurer avec CaptchaAI pour qu'elle tienne en production, pas seulement le temps d'une démo.

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 détenez une autorisation écrite. Il ne décrit pas l'automatisation de sites tiers ni la neutralisation de protections anti-bot que vous ne contrôlez pas.

Pourquoi résoudre le CAPTCHA côté serveur dans TanStack Start

Une fonction serveur s'exécute à l'abri du navigateur, l'emplacement naturel de l'appel CAPTCHA, pour trois raisons :

• Sécurité de la clé. La clé API CaptchaAI ne transite jamais par le client : elle reste dans une variable d'environnement lue au runtime.
• Cohérence de session. Le token est appliqué dans le même contexte que celui qui a déclenché le défi, ce qui évite les allers-retours qui cassent la corrélation cookies/session.
• Observabilité. Vous instrumentez l'appel au même endroit que le reste de votre logique métier.

CaptchaAI expose une API unique pour toutes les familles prises en charge — reCAPTCHA v2 et v3, Cloudflare Turnstile et Cloudflare Challenge, GeeTest v3, CAPTCHA image/OCR et grilles d'images : si la famille change sur la page, vous ajustez le type de tâche sans réécrire la boucle. La facturation par thread avec résolutions illimitées garde le coût prévisible à mesure que le volume augmente, à partir du plan BASIC ($15/mois, 5 threads).

Intégrer la résolution dans TanStack Start, étape par étape

Votre fonction serveur appelle CaptchaAI en HTTPS pour obtenir un token, puis l'injecte dans votre formulaire ou votre route d'API. Cinq étapes suffisent, et tracer chacune rend les régressions visibles lors des montées de version.

1. Capturez ce que le solveur attend. Ne récupérez que les paramètres exigés par la famille de CAPTCHA ; stocker davantage crée de fausses pistes de débogage.
2. Envoyez la tâche à CaptchaAI et traitez tout statut d'échec comme une erreur : journalisez la réponse complète et remontez-la vers votre supervision.
3. Interrogez le résultat régulièrement : attendez une quinzaine de secondes, puis toutes les 5 secondes, avec un plafond strict par tâche.
4. Appliquez le token dans la même session que celle du défi — même contexte de navigateur, même client HTTP, mêmes cookies. Une session incohérente est la première cause de rejet.
5. Suivez la latence, les retries et l'acceptation en aval. La réussite de la résolution et celle du workflow restent distinctes.

Exemple d'appel côté serveur

Voici un appel HTTP côté serveur, dans votre propre service. L'exemple crée une tâche Turnstile ; pour une autre famille, seul le type de tâche change, la logique reste identique.

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

Ce squelette renvoie un identifiant de tâche ; vous enchaînez avec une boucle d'interrogation bornée par un timeout, avant d'appliquer le token.

Gérer la clé API et les secrets

La clé CaptchaAI vit dans un coffre — HashiCorp Vault, AWS Secrets Manager, Azure Key Vault — ou dans un secret de CI, monté en variable d'environnement au runtime, jamais dans le code source ni un fichier versionné.

Si vous déployez chez un hébergeur européen (OVHcloud, Scaleway, ou une région AWS eu-west-3 à Paris), la clé passe par le gestionnaire de secrets de la plateforme, pas par une variable en clair du pipeline. Côté conformité, minimisez les données personnelles journalisées autour de l'appel et vérifiez vos obligations RGPD avant de conserver des identifiants de session.

Observabilité et journalisation

Instrumentez les appels CAPTCHA pour obtenir des métriques exploitables : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente interne. Séparez les journaux par environnement et corrélez les identifiants à votre traçage distribué (par exemple OpenTelemetry) : vous pourrez rejouer un scénario complet à partir d'un identifiant unique, ce qui réduit nettement le temps de diagnostic.

Mesurer la réussite de votre intégration

Quatre indicateurs suffisent à piloter l'intégration — des objectifs à ajuster, pas des garanties de service : la latence de première résolution (p50 sous 25 s pour un token, sous 8 s pour l'OCR), le taux de réussite du solveur (≥ 95 % par famille), l'acceptation de bout en bout après application du token (≥ 95 %) et un coût par résolution stable sur la semaine.

Dépannage

Ces quelques erreurs couvrent la majorité des tickets sur ce type d'intégration.

Avant la mise en production

Vérifiez trois garde-fous : la clé vit dans un coffre ou un secret de CI (jamais dans le code source), un retry idempotent avec backoff exponentiel borné gère les erreurs transitoires, et vos tests d'intégration restent rejouables depuis votre CI.

FAQ

Pourquoi appeler CaptchaAI depuis une fonction serveur plutôt que côté client ?

Pour protéger la clé API et préserver la cohérence de session. La fonction serveur garde la clé hors du navigateur et applique le token dans le même contexte que le défi, ce qui élimine la première cause de rejet.

Comment stocker la clé API CaptchaAI de façon sécurisée ?

Dans un gestionnaire de secrets — Vault, AWS Secrets Manager, Azure Key Vault — ou un secret de CI, monté en variable d'environnement au runtime. Jamais dans le code source, un fichier .env versionné ou une variable en clair.

CaptchaAI prend-il en charge hCaptcha ou FunCaptcha ?

Non — hCaptcha et FunCaptcha (Arkose Labs) ne sont pas pris en charge. CaptchaAI résout reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, les CAPTCHA image/OCR et les grilles ; GeeTest v4 est annoncé comme à venir.

Que faire lorsque le token est refusé après une résolution réussie ?

Vérifiez d'abord la session : le token doit être appliqué dans le même contexte que celui du défi. Contrôlez ensuite l'URL de la page et le sitekey envoyés, puis confirmez que le token n'a pas expiré entre son obtention et son application.

Guides connexes

• Démarrage rapide CaptchaAI
• QA CAPTCHA en environnements autorisés
• Tester l'endpoint d'API sur vos formulaires
• Intégrer la résolution de CAPTCHA en CI
• Résoudre reCAPTCHA v2 via l'API

Structurez vos intégrations CAPTCHA avec une méthode reproductible et mesurable. – Créez votre clé CaptchaAI.