Résoudre les CAPTCHA dans un microservice Quarkus

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 pas l'automatisation de sites tiers, ni le contournement de protections.

Un microservice Quarkus qui doit franchir un CAPTCHA fait toujours la même chose : il appelle l'API CaptchaAI en HTTP, récupère un token, puis l'injecte dans la session qui a déclenché le défi. Tout le reste — secrets, observabilité, retries — sert à rendre ce flux fiable une fois qu'il tourne sans surveillance, en CI, dans un cron ou derrière une file d'attente interne. Cet article montre comment câbler cette intégration pour qu'elle tienne en production, pas seulement sur une démo au premier essai.

L'architecture en une phrase

Votre service appelle CaptchaAI via HTTPS, obtient un token, puis le transmet à votre formulaire ou à votre route d'API dans la même session. Isolez cet appel dans un client dédié — un bean @ApplicationScoped, un client REST déclaratif Quarkus — plutôt que dans le code métier : un seul endroit à instrumenter, tester et faire évoluer.

Le flux de résolution en trois temps

Le contrat est court et se transpose vers tout langage doté d'un client HTTP. Gardez cette séquence quel que soit le type visé.

1. Créez la tâche. Envoyez à l'API le strict nécessaire pour la famille concernée (clé du site, URL de la page, éventuel proxy) et récupérez l'identifiant de tâche (taskId). Stocker davantage ne crée que de fausses pistes de débogage.
2. Interrogez le résultat. Patientez quelques secondes, puis interrogez le point de résultat jusqu'à ce que le token soit prêt, avec un plafond ferme par tâche.
3. Injectez le token dans la même session. Même contexte, même client HTTP, même cookie jar que l'appel qui a déclenché le défi — une session dépareillée est la première cause de rejet.

Gestion des secrets

La clé CaptchaAI n'a rien à faire dans le code source ni dans une image Docker. Placez-la dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou un secret de CI, et laissez le déploiement la monter en variable d'environnement. Sur Kubernetes, un Secret monté en variable suffit : Quarkus la lit via @ConfigProperty sans qu'elle apparaisse dans vos logs. Pensez RGPD au passage — ne journalisez jamais la clé et minimisez les données personnelles qui transitent par le formulaire.

Exemple : créer une tâche Turnstile

L'appel côté serveur reste trivial. Voici la création d'une tâche Cloudflare Turnstile, la clé étant lue depuis l'environnement :

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 se transpose vers reCAPTCHA v2, reCAPTCHA v3 ou GeeTest v3 en changeant le type de tâche : une seule boucle d'intégration couvre toutes les familles prises en charge.

Observabilité et journalisation

Instrumentez chaque appel CAPTCHA : durée totale d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file interne. Séparez les journaux par environnement et corrélez chaque identifiant à votre traçage distribué — OpenTelemetry s'intègre nativement à Quarkus. Vous rejouerez un scénario complet à partir d'un seul identifiant, ce qui réduit nettement le temps de diagnostic.

Les KPI à suivre

Câblez ces indicateurs dans le tableau de bord que vous utilisez déjà pour repérer une régression avant vos utilisateurs. Les valeurs cibles dépendent de votre contexte et de votre volume.

Dépannage

La plupart des tickets se ramènent à une poignée de causes.

Liste de contrôle avant mise en production

• Périmètre limité à vos propres applications ou à des sources autorisées.
• Clé CaptchaAI dans un coffre ou un secret de CI, jamais dans le code source.
• Durées d'appel et codes retour tracés à chaque exécution.
• Retry idempotent avec backoff exponentiel borné pour les erreurs transitoires.
• Tests rejouables depuis votre intégration continue.

Coût et montée en charge

CaptchaAI facture par thread simultané, pas par résolution : chaque plan inclut un nombre de threads et des résolutions illimitées par thread sur le mois. Le plan BASIC ($15/mois, 5 threads) suffit aux intégrations de départ ; vous passez à STANDARD ($30/mois, 15 threads) et au-delà quand votre débit augmente. Le coût suit les appels concurrents, pas le nombre de microservices.

FAQ

Où placer la clé API CaptchaAI dans un déploiement Quarkus ?

Dans un coffre de secrets ou un Secret Kubernetes monté en variable d'environnement, lu via @ConfigProperty. Ne la mettez ni dans un application.properties versionné, ni dans l'image Docker, ni dans les logs. En CI, injectez-la au déploiement.

Le token peut-il être refusé après une résolution réussie ?

Oui, et la cause est presque toujours la même : le token est appliqué dans une session différente de celle qui a déclenché le défi. Conservez le même contexte HTTP — mêmes cookies, même client — entre la résolution et la soumission, et vérifiez que l'URL et la clé du site correspondent à la page réelle.

Que se passe-t-il si le type de CAPTCHA change sur la page ?

L'API reste la même : vous changez le type de tâche (Turnstile, reCAPTCHA v2/v3, GeeTest v3…) en conservant la même boucle création/interrogation/injection. En revanche, hCaptcha et FunCaptcha ne sont pas pris en charge, et GeeTest v4 est annoncé mais pas encore disponible — prévoyez un fallback si votre page peut basculer vers eux.

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

Non. Tous les exemples portent sur vos propres applications ou sur des environnements de test pour lesquels vous disposez d'une autorisation écrite. Aucune technique de contournement ni d'anti-détection n'y est décrite. Si une source externe est en jeu, validez ses conditions d'utilisation et votre base juridique.

Guides connexes

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

Une intégration CAPTCHA propre tient à une méthode reproductible et à des métriques suivies. – Obtenez votre clé CaptchaAI.