Un outil interne de résolution CAPTCHA en 50 lignes avec Bun et Hono

Périmètre sûr : ce guide s'applique uniquement à vos propres applications et à vos environnements de QA, de préproduction ou de production, ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne concerne pas les sites tiers que vous n'exploitez pas.

Un bon outil interne de résolution CAPTCHA tient effectivement en une cinquantaine de lignes, mais ce qui le rend fiable, ce n'est pas le code : c'est tout ce qui l'entoure. L'endpoint qui appelle CaptchaAI, récupère un token et le renvoie à votre formulaire s'écrit en quelques minutes ; le faire tenir sous CI ou dans un cron demande une structure claire. Ce guide le construit de bout en bout, avec Bun et Hono comme runtime léger.

L'architecture du service interne

Le principe est simple : votre composant reçoit une demande (sitekey, URL, type de défi), appelle CaptchaAI en HTTPS pour obtenir un token, puis le renvoie à l'appelant qui l'injecte dans son formulaire. Une seule responsabilité à surveiller.

Le flux, étape par étape

1. Capturez les bons paramètres attendus par le type de défi : sitekey, URL, action, proxy éventuel. En stocker plus crée des pistes trompeuses.
2. Créez la tâche auprès de CaptchaAI et journalisez toute réponse non conforme.
3. Récupérez le token en interrogeant le résultat, avec un plafond par tâche plutôt qu'une attente infinie.
4. Injectez le token dans la même session que celle du défi : même navigateur, même client HTTP, même cookie jar.
5. Mesurez la latence, les retries et l'acceptation : résolution et workflow restent deux métriques distinctes.

Le cœur du service : le code

Voici l'appel de votre suite de tests : il crée une tâche Turnstile et renvoie l'identifiant à interroger.

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

L'API reste identique d'un type de défi à l'autre : vous changez le type de tâche (reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile, GeeTest v3, image/OCR), la boucle de récupération ne bouge pas. Un service de 50 lignes couvre ainsi plusieurs familles.

Sécuriser la clé et maîtriser le coût

La clé CaptchaAI ne vit jamais dans le code source. Stockez-la dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou un secret CI, monté au runtime. Pensez aussi RGPD : les journaux autour de cette clé ne doivent jamais capturer d'identifiants réels. Côté coût, la facturation est basée sur les threads (BASIC à $15/mois, 5 threads) avec des résolutions illimitées par thread : vous dimensionnez selon les tâches simultanées.

Observabilité et budget de retry

Instrumentez chaque appel : durée d'obtention du token, code retour HTTP et identifiant de tâche. Suivez la latence médiane et le 95e centile, le taux de réussite et la consommation, et corrélez les identifiants à votre traçage distribué. Pour les erreurs transitoires, appliquez un backoff exponentiel borné (trois tentatives, plafond à 30 secondes) : un retry infini masque les vrais défauts et consomme votre solde.

Checklist avant la mise en production

• Le périmètre reste limité à vos propres applications ou à des sources autorisées.
• La clé CaptchaAI vit dans un coffre ou un secret CI, jamais dans le code source.
• Durées d'appel, codes retour et identifiants de tâche sont tracés à chaque exécution.
• Le token est injecté dans la même session que celle du défi.
• Les tests sont rejouables depuis votre CI.

Dépannage

FAQ

Bun et Hono sont-ils obligatoires ?

Non. Ils offrent un runtime léger, pratique pour un microservice interne, mais le contrat est le même partout : créer une tâche, récupérer un token, l'injecter. La logique se transpose vers n'importe quel langage HTTP.

Où stocker la clé API en toute sécurité ?

Dans un coffre (Vault, AWS Secrets Manager, Azure Key Vault) ou un secret CI, jamais en dur ni dans les journaux.

Ce guide couvre-t-il l'automatisation de sites tiers ?

Non. Tous les exemples portent sur vos propres applications ou des environnements autorisés par écrit. Pour une source externe, validez d'abord les conditions d'utilisation.

Guides connexes

• Démarrage rapide CaptchaAI
• QA CAPTCHA en environnements autorisés
• Tester l'endpoint API sur vos formulaires
• Intégration CAPTCHA en CI
• Résoudre reCAPTCHA v2 via l'API

Passez d'un script fragile à un service interne fiable et mesurable. — Obtenez votre clé CaptchaAI.