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.
Dans une application Micronaut, un CAPTCHA se gère côté serveur : votre service appelle CaptchaAI en HTTPS, récupère un token, puis l'injecte dans le formulaire ou la route protégée qui a déclenché le défi. Aucun humain dans la boucle, aucun navigateur à piloter pour la plupart des types. C'est exactement ce dont ont besoin les jobs planifiés, les workers internes et les pipelines d'intégration continue.
Micronaut se prête bien à ce rôle : démarrage en quelques millisecondes, empreinte mémoire réduite, image native GraalVM et client HTTP déclaratif intégré. Un service qui appelle CaptchaAI depuis Micronaut reste léger, testable et facile à déployer en fonction serverless ou en worker.
Comment CaptchaAI s'intègre à une application Micronaut
Le composant qui a besoin d'un token appelle CaptchaAI via HTTPS, attend la résolution, puis réinjecte la valeur dans la requête d'origine. Dans Micronaut, c'est naturellement un client HTTP déclaratif (@Client) encapsulé dans un service injectable : vous le testez comme n'importe quel autre bean. Tracez chaque étape — soumission, attente, réponse — dès la conception, pour rendre visibles les régressions au fil des montées de version.
Le flux de résolution CAPTCHA dans Micronaut
Le déroulé reste identique quel que soit le type de CAPTCHA ; seuls les paramètres envoyés changent.
- Collectez uniquement les paramètres utiles : sitekey, URL de la page, action, proxy éventuel. Stocker davantage crée de fausses pistes de débogage.
- Envoyez la tâche et vérifiez le statut de la réponse. Tout statut autre qu'un succès est une erreur : journalisez la réponse complète et remontez-la vers votre supervision.
- Interrogez le résultat régulièrement : un court délai avant la première interrogation, puis un intervalle fixe avec un plafond ferme par tâche pour éviter les boucles infinies.
- Injectez le token dans la même session que celle qui a déclenché le défi (même contexte HTTP, mêmes cookies). Une session désynchronisée est la première cause de rejet après résolution.
- Mesurez la latence, les tentatives et l'acceptation en aval. Une tâche résolue et un workflow réussi sont deux métriques distinctes ; suivez les deux.
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 d'intégration continue, jamais dans le code source. Au runtime, le déploiement la monte en variable d'environnement, que Micronaut lit via sa configuration (@Value ou @Property). Si vos workers tournent chez OVHcloud, Scaleway ou dans une région AWS européenne comme eu-west-3 (Paris), gardez la clé dans le gestionnaire de secrets du même environnement.
Exemple de code
Exemple d'appel HTTP côté serveur dans votre propre service :
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 contrat est le même dans tout langage compatible HTTP : soumettre la tâche, récupérer un identifiant, interroger le résultat. Le transposer vers le client déclaratif de Micronaut, en Java ou Kotlin, ne change ni la logique ni les paramètres.
Observabilité et journalisation
Instrumentez chaque appel 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. Ces signaux alimentent vos tableaux de bord de QA et vos alertes.
Séparez les journaux par environnement (développement, préproduction, production) et corrélez les identifiants à votre traçage distribué, par exemple via OpenTelemetry. Vous pourrez ainsi rejouer un scénario complet à partir d'un seul identifiant. Côté conformité, appliquez le principe de minimisation du RGPD : ne journalisez aucune donnée personnelle inutile.
Mesurer la réussite de l'intégration
Les chiffres reposent sur des mesures observées et des retours d'utilisateurs. Les résultats varient selon l'environnement, le volume et le moment de la journée ; fixez vos propres cibles internes.
| Indicateur | Cible interne | Ce qu'il révèle |
|---|---|---|
| Latence de résolution (médiane) | Selon le type | L'intégration est saine, sans attente de retry. |
| Latence de résolution (p95) | Queue maîtrisée | Vos timeouts sont bien dimensionnés. |
| Taux de réussite | Par famille de CAPTCHA | Vos paramètres correspondent au défi réel. |
| Acceptation de bout en bout | Après injection | La vérification en aval accepte le token. |
| Coût par résolution acceptée | Stable sur la semaine | Le volume n'érode pas la marge via des retrys. |
Liste de contrôle avant mise en production
- Le périmètre reste limité à vos propres applications ou à des sources autorisées.
- La clé CaptchaAI est stockée dans un secret CI ou un coffre, jamais dans le code.
- Les durées d'appel et les codes retour sont tracés à chaque exécution.
- Un retry idempotent avec backoff exponentiel borné couvre les erreurs transitoires.
- Les tests d'intégration sont rejouables depuis votre intégration continue.
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace parasite ou mauvais compte. | Recopiez la clé et stockez-la en secret CI. |
ERROR_ZERO_BALANCE |
Solde insuffisant pour lancer la tâche. | Rechargez le solde ; ajoutez une alerte de seuil. |
ERROR_PAGEURL / ERROR_BAD_PARAMETERS |
Paramètre manquant ou mal formé. | Revalidez l'URL et le sitekey contre le HTML réel. |
CAPCHA_NOT_READY en boucle |
Résolution encore en cours. | Interrogez à intervalle fixe avec un plafond par tâche. |
| Token refusé après résolution | Token injecté dans une session différente. | Résolvez et soumettez dans le même contexte HTTP. |
FAQ
Pourquoi appeler CaptchaAI depuis Micronaut plutôt que côté navigateur ?
Un service Micronaut tourne sans interface : jobs planifiés, workers, fonctions serverless. Un appel HTTPS serveur-à-serveur reste plus léger et plus simple à superviser qu'un navigateur piloté, tout en s'intégrant à votre injection de dépendances et à vos tests.
Faut-il un client HTTP particulier dans Micronaut ?
Non. Le client HTTP déclaratif (@Client) suffit : vous décrivez l'appel dans une interface, Micronaut génère l'implémentation. Tout client HTTP compatible convient aussi, tant que vous respectez le contrat soumission puis interrogation du résultat.
Comment injecter le token une fois la résolution terminée ?
Réutilisez la session qui a déclenché le défi (mêmes cookies, même contexte HTTP) et placez la valeur reçue dans le champ attendu par le type — par exemple cf-turnstile-response pour Cloudflare Turnstile — avant de soumettre le formulaire.
CaptchaAI prend-il en charge hCaptcha dans ce flux ?
Non — hCaptcha et FunCaptcha (Arkose Labs) ne sont pas pris en charge, et GeeTest v4 est à venir. Le flux couvre reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, ainsi que les CAPTCHA image/OCR et en grille.
Guides connexes
- Le démarrage rapide CaptchaAI
- La 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
Structurez vos workflows CAPTCHA de façon méthodique et reproductible. – Créez votre compte CaptchaAI.
