Périmètre sûr : Ce guide s'applique uniquement à vos propres applications et environnements (QA, préproduction, production) ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne traite ni de l'automatisation de sites tiers, ni de l'évasion de protections anti-bot.
Un microservice Encore.go qui doit franchir une étape protégée par CAPTCHA a besoin de trois garanties : une résolution fiable, un contrat d'API lisible et des métriques par environnement. Sans elles, l'intégration tient le temps d'une démonstration, puis échoue dès qu'elle tourne sans surveillance dans votre CI ou vos tâches planifiées. Ce guide montre comment structurer cet appel avec CaptchaAI pour qu'il reste stable en production, et pas seulement au premier essai.
Architecture : un service interne qui appelle CaptchaAI
Placez la logique CAPTCHA dans un service Encore.go dédié plutôt que de la disperser dans chaque handler. Ce service appelle CaptchaAI en HTTPS, récupère un token, puis le renvoie au code qui poursuit le formulaire ou la route d'API. Un point d'entrée unique facilite le traçage et rend les régressions visibles lors des montées de version. Encore.go y aide avec ses services typés et son système de secrets intégré.
Le contrat submit/poll, étape par étape
Le déroulé reste identique quel que soit le type de CAPTCHA. Gardez cette séquence en tête et vous pourrez la transposer à n'importe quel langage compatible HTTP :
- Rassemblez uniquement les paramètres attendus par le type de CAPTCHA : sitekey, URL de la page, action éventuelle, proxy si nécessaire.
- Envoyez la tâche à CaptchaAI et récupérez son identifiant ; traitez tout statut d'erreur comme un échec à journaliser immédiatement.
- Interrogez le résultat : attendez une quinzaine de secondes, puis toutes les 5 secondes, avec un plafond ferme par tâche.
- Appliquez le token dans la même session que celle qui a déclenché le défi — mêmes cookies, même client HTTP.
- Mesurez la latence, les retry et l'acceptation en aval : une résolution réussie n'est pas encore un workflow réussi.
Exemple : créer une tâche côté serveur
Voici un appel 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;
}
Gérer la clé API et les secrets
La clé API CaptchaAI ne doit jamais figurer dans le code source. Stockez-la à l'un de ces emplacements, monté en variable d'environnement au runtime :
- le système de secrets intégré d'Encore.go ;
- un coffre managé (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ;
- un secret de CI, injecté au moment du déploiement.
Sur un hébergement européen comme Scaleway ou une région AWS eu-west-3 (Paris), veillez également à ce que vos journaux ne recopient jamais la clé.
Observabilité et journalisation par environnement
Instrumentez chaque appel CAPTCHA pour obtenir des signaux exploitables :
- la durée totale d'obtention du token ;
- le code retour HTTP et l'identifiant de tâche ;
- la taille de la file d'attente interne ;
- le taux de réussite, par environnement.
Séparez les journaux par environnement — développement, préproduction, production — et corrélez chaque identifiant à votre traçage distribué (OpenTelemetry, par exemple) pour rejouer un scénario complet à partir d'un seul identifiant. Si vous journalisez des données liées à des utilisateurs, minimisez ce que vous conservez et vérifiez vos obligations RGPD.
Mesurer la réussite de l'intégration
Distinguez deux indicateurs souvent confondus : le taux de réussite du solveur et le taux d'acceptation en aval. Un token obtenu n'est pas un workflow réussi. Suivez la latence médiane, la latence de queue (p95) et le coût par résolution acceptée. Comme la facturation CaptchaAI se fait par thread — résolutions illimitées par thread —, ce coût reste prévisible tant que vos retry ne s'emballent pas. Le plan BASIC ($15/mois, 5 threads) suffit pour valider une intégration avant de monter en charge.
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 secret ou un coffre, jamais dans le dépôt.
- Les durées d'appel et les codes retour sont tracés à chaque exécution.
- Une stratégie de retry idempotent, plafonnée à trois tentatives avec backoff exponentiel, gère les erreurs transitoires.
- Les tests d'intégration sont rejouables depuis votre CI.
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace parasite ou mauvais compte. | Recopiez la clé depuis le tableau de bord et stockez-la comme secret. |
ERROR_ZERO_BALANCE |
Solde insuffisant pour la tâche. | Rechargez le solde et ajoutez une alerte de seuil. |
| Token refusé après résolution | Token appliqué dans une autre session que celle du défi. | Conservez la résolution et la soumission dans la même session HTTP. |
FAQ
Pourquoi isoler la résolution CAPTCHA dans un microservice dédié ?
Parce qu'un service unique centralise le traçage, les secrets et la gestion des erreurs. Chaque appel suit le même chemin, ce qui rend les régressions plus faciles à repérer et l'intégration plus simple à confier à un autre développeur.
Comment gérer la clé API CaptchaAI dans un service Go déployé en continu ?
Montez-la en variable d'environnement depuis le système de secrets d'Encore.go ou de votre CI, et lisez-la une seule fois au démarrage. Ne la journalisez jamais et faites-la tourner régulièrement depuis le tableau de bord.
Que faire si le token est refusé après une résolution réussie ?
Vérifiez d'abord la session : le token doit être appliqué dans le même contexte HTTP (mêmes cookies) que celui qui a déclenché le défi. Si le problème persiste, comparez les paramètres envoyés (sitekey, URL) avec le HTML réel de la page.
CaptchaAI prend-il en charge hCaptcha dans ce type d'intégration ?
Non — hCaptcha n'est pas pris en charge, pas plus que FunCaptcha. CaptchaAI couvre reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, ainsi que les CAPTCHA image et en grille. Le même contrat submit/poll s'applique à tous ces types.
Guides connexes
- Démarrage rapide CaptchaAI
- Tester vos CAPTCHA en environnement autorisé
- Tester l'endpoint API sur vos formulaires
- Intégrer la résolution CAPTCHA dans votre CI
- Résoudre reCAPTCHA v2 via l'API
Structurez vos workflows CAPTCHA de façon méthodique et reproductible. – Obtenez votre clé CaptchaAI.
