Périmètre sûr : ce guide couvre uniquement vos propres applications et vos environnements de QA, de préproduction ou de production — ou des systèmes pour lesquels vous détenez une autorisation écrite. Il ne traite pas l'automatisation de sites tiers que vous ne contrôlez pas.
Encapsuler un appel CaptchaAI dans une étape Restate revient à confier la résolution du défi CAPTCHA au moteur d'exécution durable : l'étape est journalisée, rejouable et idempotente, si bien qu'un redémarrage du worker ou un incident réseau ne relance jamais deux fois le même token. C'est exactement ce qu'il faut quand la résolution tourne sans surveillance : en CI, dans un cron ou derrière une file d'attente interne.
Pourquoi une étape de workflow durable
Une résolution de CAPTCHA est un appel réseau lent et faillible : la latence varie, l'API peut renvoyer une erreur transitoire, le token a une durée de vie courte. Dans un script classique, chacun de ces aléas vous oblige à écrire à la main la reprise et la déduplication. En confiant l'appel à une étape Restate, vous héritez de ce comportement sans l'écrire : le moteur mémorise le résultat obtenu, ne rejoue pas un appel déjà terminé après un redémarrage et applique votre politique de retry de façon déterministe.
Architecture cible
Votre étape Restate appelle CaptchaAI en HTTPS pour obtenir un token, puis l'injecte dans le formulaire ou la route d'API de l'étape suivante. Deux principes rendent l'ensemble prévisible : ne capturer que les paramètres attendus par la famille de CAPTCHA (sitekey, URL de page, action, proxy éventuel) et appliquer le token dans la même session que celle qui a déclenché le défi.
Le déroulé, étape par étape
- Capturez les entrées exactes. Inspectez la page ou l'appel réseau réel et n'extrayez que ce que la famille de CAPTCHA attend. Stocker davantage crée de fausses pistes de débogage.
- Soumettez la tâche à l'API et récupérez l'identifiant renvoyé. Traitez toute erreur comme telle : journalisez la réponse complète et remontez-la vers votre supervision.
- Interrogez le résultat. Patientez une quinzaine de secondes avant la première interrogation, puis interrogez toutes les 5 secondes, avec un plafond ferme de 120 secondes par tâche.
- Appliquez le token 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 jar de cookies. Une session dépareillée est la première cause de rejet après résolution.
- Mesurez latence, retries et acceptation en aval. La réussite de la résolution et la réussite du workflow sont deux métriques distinctes : suivez les deux.
Configuration des secrets
La clé CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret de CI — jamais dans le code source. Le déploiement la monte en variable d'environnement au runtime, comme la variable CAPTCHAAI_KEY de l'exemple ci-dessous. Sur un worker OVHcloud ou Scaleway, injectez-la via le gestionnaire de secrets de votre orchestrateur, pas dans l'image.
Exemple de code
Voici l'appel HTTP côté serveur, à l'intérieur de votre propre service. La fonction soumet une tâche Turnstile et renvoie l'identifiant de tâche que l'étape suivante interrogera :
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;
}
Observabilité et journalisation
Instrumentez chaque appel 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. Séparez les journaux par environnement et corrélez-les à votre traçage distribué, par exemple via OpenTelemetry : vous rejouez alors un scénario complet à partir d'un identifiant unique, ce qui accélère le diagnostic.
Côté conformité, ne journalisez pas de données personnelles inutiles : restez sur les identifiants techniques et vérifiez vos obligations RGPD avant de conserver le moindre payload.
Mesurer la réussite
Suivez quatre indicateurs : la latence d'obtention du token (médiane et p95), le taux de réussite par famille de CAPTCHA, l'acceptation en aval et le coût par résolution acceptée. L'écart entre résolution réussie et acceptation en aval est votre meilleur signal d'alerte : il révèle les tokens appliqués dans une session différente de celle du défi.
Coût et montée en charge
La facturation de CaptchaAI se fait par thread concurrent, pas à la résolution : chaque plan inclut des résolutions illimitées par thread sur le mois. Le plan BASIC ($15/mois, 5 threads) suffit pour un worker unique ; passez à STANDARD ($30/mois, 15 threads) quand plusieurs étapes Restate résolvent en parallèle. Les boucles de mauvais paramètres et les tempêtes de retry sont ce qui fait déraper le coût.
Liste de contrôle
- Le périmètre reste limité à vos propres applications ou à des sources autorisées.
- La clé CaptchaAI est stockée dans un coffre ou un secret de CI, 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é est en place.
- Le token est appliqué dans la même session que celle ayant déclenché le défi.
- Les tests sont rejouables et reproductibles 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é depuis le tableau de bord et stockez-la comme secret de CI. |
ERROR_ZERO_BALANCE |
Solde inférieur au minimum par tâche. | Rechargez avant de réessayer et ajoutez une alerte de solde. |
ERROR_PAGEURL / ERROR_BAD_PARAMETERS |
Entrée requise manquante ou mal formée. | Revalidez l'URL de page et le sitekey contre le HTML réel. |
| Token refusé après résolution | Token appliqué dans une session différente de celle du défi. | Gardez la résolution et l'envoi du formulaire dans la même session. |
FAQ
Pourquoi utiliser Restate plutôt qu'un retry écrit à la main ?
Restate journalise chaque étape terminée : après un redémarrage du worker, il ne rejoue pas un appel CaptchaAI déjà résolu et n'applique pas deux fois le même token. Un retry maison peut le faire dès que vous oubliez un cas limite.
Le token expire-t-il pendant l'attente du polling ?
Oui, les tokens ont une durée de vie courte. Interrogez le résultat rapidement et appliquez le token immédiatement dans la session d'origine. Ne stockez pas de tokens à l'avance : résolvez à la demande.
Comment tester cette étape sans appeler l'API en continu ?
Encapsulez l'appel derrière une interface que vous pouvez remplacer par un bouchon en test. En intégration continue, injectez un token factice pour valider le câblage de l'étape sans consommer de solde, puis lancez un test réel planifié sur un environnement autorisé.
Ce guide couvre-t-il l'automatisation de sites tiers ?
Non. Tous les exemples portent sur vos propres applications ou des environnements de test autorisés par écrit. Pour une source externe, vérifiez les conditions d'utilisation et la base juridique au préalable.
Guides connexes
- Démarrage rapide CaptchaAI
- QA CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- Intégration CAPTCHA en intégration continue
- Résoudre reCAPTCHA v2 via l'API
Passez de la démo à la production : une étape de résolution durable, mesurée et rejouable. – Créez votre compte CaptchaAI.
