Résoudre des CAPTCHAs depuis une fonction Vercel Edge Runtime

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 décrit ni l'automatisation de sites tiers, ni le contournement de protections, ni l'évasion d'anti-bot.

Une fonction Vercel Edge Runtime s'exécute dans un moteur V8 restreint : pas de modules Node.js classiques, pas d'accès disque, et un budget d'exécution court. Résoudre un CAPTCHA depuis ce contexte tient alors en trois gestes. Vous appelez l'API CaptchaAI en HTTPS pour obtenir un token, vous l'injectez dans la même session que le défi, puis vous instrumentez chaque appel pour que le flux reste stable une fois déployé. Ce guide détaille comment structurer cette intégration pour qu'elle tienne en production, et pas seulement sur une démo qui passe du premier coup.

Ce que l'Edge Runtime change pour la résolution de CAPTCHAs

L'Edge Runtime n'est pas un environnement Node.js complet. Vous disposez de fetch nativement, mais pas de fs ni de sockets bruts, et les bibliothèques à binaires natifs ne s'y chargent pas. Trois contraintes en découlent :

• Tout passe par HTTP. L'API CaptchaAI étant une simple API REST, un appel fetch suffit pour envoyer la tâche et interroger le résultat, sans dépendance lourde.
• Le temps d'exécution est plafonné. Une résolution par token (reCAPTCHA, Turnstile) peut demander plusieurs secondes. Si la fonction Edge risque de dépasser sa limite, déportez l'interrogation du résultat vers une route serverless classique ou une file d'attente.
• Les secrets ne vivent pas dans le code. La clé API se lit dans une variable d'environnement injectée au déploiement, jamais dans le bundle expédié en périphérie.

CaptchaAI couvre les familles utiles à ce workflow : reCAPTCHA v2 et v3, Cloudflare Turnstile et Cloudflare Challenge, GeeTest v3, ainsi que les CAPTCHAs image/OCR et en grille ; CaptchaFox, Friendly Captcha et Lemin sont en bêta. Une seule API dessert toutes ces familles, ce qui vous évite de réécrire l'intégration à chaque changement de défi.

Architecture de l'appel

Votre composant interne appelle CaptchaAI en HTTPS pour récupérer un token, puis l'injecte dans votre formulaire ou votre route d'API. Tracez chaque étape — envoi de la tâche, identifiant renvoyé, interrogation du résultat, injection — pour repérer une régression après une montée de version. Sur Vercel, une région edge européenne (par exemple cdg1, Paris) rapproche la fonction de vos utilisateurs.

Où placer la clé API CaptchaAI

La clé CaptchaAI se stocke dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans les variables d'environnement chiffrées du projet Vercel. Le déploiement la monte au runtime ; elle n'apparaît jamais dans le dépôt Git ni dans les logs.

Côté conformité, l'appel de résolution ne doit transporter que les paramètres du défi (sitekey, URL de la page, action éventuelle). N'y ajoutez aucune donnée personnelle : c'est inutile pour la résolution et cohérent avec vos obligations RGPD de minimisation des données.

Exemple : déclencher une résolution côté serveur

Voici un appel HTTP côté serveur, dans votre propre service, qui crée une tâche Turnstile 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;
}

La logique reste identique quel que soit le langage : vous envoyez la tâche, vous récupérez un identifiant, puis vous interrogez le résultat jusqu'à obtenir le token. Vous pouvez donc transposer ce schéma vers Python, Go ou tout autre écosystème compatible HTTP sans en changer la structure.

Observabilité et journalisation par environnement

Instrumentez systématiquement les appels 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 déclenchent vos alertes avant que les utilisateurs ne remarquent l'incident.

Séparez les journaux par environnement — développement, préproduction, production — et corrélez les identifiants à votre traçage distribué (par exemple OpenTelemetry). Vous pourrez alors rejouer un scénario complet à partir d'un identifiant unique et accélérer nettement le diagnostic en cas d'incident.

Suivez surtout deux indicateurs distincts : le taux de réussite de la résolution (le token est renvoyé) et le taux d'acceptation en aval (la vérification côté serveur accepte ce token). Un écart entre les deux signale presque toujours un token appliqué dans une session différente de celle qui a déclenché le défi.

Coût et dimensionnement des threads

CaptchaAI facture par thread simultané, avec des résolutions illimitées par thread — pas de frais par CAPTCHA ni de surcoût selon le type. Un thread correspond à une résolution en cours : dès qu'elle se termine, il reprend la tâche suivante.

Pour un job planifié à faible concurrence, le plan BASIC ($15/mois, 5 threads) suffit. Une charge continue avec plusieurs workers en parallèle bascule vers STANDARD ($30/mois, 15 threads) ou ADVANCE ($90/mois, 50 threads). Le budget dépendant de la concurrence et non du volume brut, ce sont les boucles de retry mal bornées et les paramètres erronés qui gonflent la note.

Liste de contrôle avant mise en production

• Le périmètre est strictement limité à vos propres applications ou à des sources autorisées.
• La clé CaptchaAI est stockée dans un coffre ou un secret CI/Vercel, jamais dans le code source.
• 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.
• Le token est injecté dans la même session que le défi.
• Les tests sont rejouables depuis votre intégration continue.

FAQ

Le CAPTCHA se résout-il directement dans l'Edge Runtime ou faut-il un backend ?

Les deux approches fonctionnent. Un simple fetch vers l'API CaptchaAI s'exécute très bien dans une fonction Edge. Si la résolution risque de dépasser le budget d'exécution, déportez l'interrogation du résultat vers une route serverless classique ou une file d'attente, et réservez l'Edge à l'étape rapide.

Comment gérer le délai d'exécution limité d'une fonction Edge ?

Découpez le flux : la fonction Edge envoie la tâche et renvoie l'identifiant, un autre composant interroge le résultat. Bornez l'interrogation (par exemple 120 secondes par tâche) et prévoyez un retry avec backoff exponentiel pour ne pas rester bloqué sur une erreur transitoire.

Où stocker la clé API dans un déploiement Vercel ?

Dans les variables d'environnement chiffrées du projet Vercel, ou dans un coffre externe (Vault, AWS Secrets Manager) lu au runtime. Elle ne doit jamais figurer dans le bundle expédié en périphérie ni apparaître dans les logs applicatifs.

Que faire si le token est refusé après résolution ?

Vérifiez d'abord que le token est injecté dans la même session que celle qui a déclenché le défi : même contexte de navigateur, même client HTTP, même cookie jar. Une session dépareillée est la cause la plus fréquente d'un rejet. Contrôlez ensuite que le sitekey et l'URL de la page correspondent au défi affiché.

Guides connexes

• Le démarrage rapide CaptchaAI
• Tests 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

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