Résoudre les CAPTCHA dans les form actions SvelteKit

Périmètre sûr : Ce guide couvre uniquement vos propres applications SvelteKit et 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 résolution de CAPTCHA sur des services que vous ne contrôlez pas.

Dans SvelteKit, une form action s'exécute entièrement côté serveur — et c'est précisément là que doit se faire la résolution d'un CAPTCHA. L'action obtient un token auprès de CaptchaAI, le vérifie, puis poursuit le traitement, sans jamais exposer votre clé API au navigateur. Ce guide montre comment bâtir cette intégration pour qu'elle tienne en production, pas seulement le temps d'une démonstration.

Pourquoi résoudre le CAPTCHA dans la form action

Le runtime serveur de SvelteKit (adapter Node ou fonction serverless) réunit trois propriétés qui comptent pour un CAPTCHA : il garde votre clé hors de portée du client, il s'exécute de façon reproductible en CI comme en cron, et il vous laisse tracer chaque appel. Résoudre le défi côté client reviendrait à publier votre clé. Placez l'appel dans l'action ou dans une route +server.js, jamais dans un composant .svelte.

Architecture de l'intégration

Le flux reste court et se déroule entièrement côté serveur :

1. Le composant +page.svelte envoie le formulaire à l'action.
2. L'action de +page.server.js extrait le sitekey et l'URL de la page.
3. Elle appelle CaptchaAI en HTTPS et attend le token.
4. Le token est injecté dans la vérification en aval de l'application que vous contrôlez.

Tracez chaque étape : vous repérerez une régression dès la prochaine montée de version, plutôt qu'en production.

Gérer la clé et les secrets

Lisez la clé CaptchaAI via $env/dynamic/private ou $env/static/private, jamais via $env/static/public, qui l'exposerait dans le bundle client. En production, montez-la depuis un coffre (HashiCorp Vault, AWS Secrets Manager) ou un secret CI. Sur OVHcloud ou Scaleway, une variable chiffrée au niveau du service suffit ; ne committez jamais la clé dans le dépôt.

Appeler CaptchaAI depuis votre service

L'appel serveur se résume à un POST HTTPS. L'exemple Node.js ci-dessous crée une tâche Turnstile et renvoie l'identifiant à interroger ensuite :

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 — envoyer la tâche, puis interroger le résultat — se transpose vers Python, Go ou tout autre client HTTP.

Observabilité et journalisation

Instrumentez chaque appel 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 alimentent vos tableaux de bord de QA et vos alertes.

Séparez les journaux par environnement et corrélez les identifiants à votre traçage distribué (par exemple OpenTelemetry) pour rejouer un scénario complet. Côté conformité, ne journalisez que le strict nécessaire : un identifiant de tâche et un horodatage suffisent au diagnostic et vous évitent de conserver des données personnelles au regard du RGPD.

Liste de contrôle avant la mise en production

Dépannage

La plupart des incidents se ramènent à une poignée de codes d'erreur renvoyés par l'API.

FAQ

Faut-il appeler CaptchaAI dans la form action ou dans une route +server.js ?

Les deux conviennent, tant que l'appel reste côté serveur. Une form action est naturelle pour un formulaire avec amélioration progressive ; une route +server.js est préférable quand plusieurs pages partagent la même logique de résolution.

Comment protéger ma clé CaptchaAI dans SvelteKit ?

Lisez-la uniquement via $env/dynamic/private ou $env/static/private. Toute variable préfixée PUBLIC_ finit dans le bundle client, visible par n'importe quel visiteur. En production, injectez la clé depuis un coffre ou un secret CI.

Pourquoi mon token est-il refusé après résolution ?

Presque toujours à cause d'un décalage de session ou d'un token expiré. Vérifiez que le token est appliqué dans la même session serveur que celle qui a reçu le formulaire, et que le sitekey correspond exactement à celui de la page.

Que faire en cas d'erreur transitoire de l'API ?

Mettez en place un retry avec backoff exponentiel borné (trois tentatives, délai doublé, plafond à 30 secondes) et journalisez chaque échec. Si l'erreur persiste, vérifiez la configuration réseau et le solde de votre clé.

Guides connexes

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

Passez d'une intégration fragile à un flux CAPTCHA reproductible et observable. – Créez votre compte CaptchaAI.