Périmètre sûr : Ce guide s'applique à 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 couvre ni les sites tiers que vous ne contrôlez pas, ni les techniques d'anti-détection.
Dans un parcours login → formulaire → validation, ce n'est presque jamais la première étape qui casse : c'est la troisième, quand la session a expiré ou que le token CAPTCHA obtenu au départ n'est plus accepté. La règle tient en une phrase : traitez la résolution CAPTCHA comme une dépendance réseau ordinaire — une étape qui prend du temps, qui peut échouer, et qui doit donc être isolée, mesurée et réessayable.
Où un workflow multi-étapes lâche réellement
Trois causes reviennent dans la plupart des incidents :
- La durée de vie du token. Un token reCAPTCHA v2 ou Cloudflare Turnstile a une TTL courte. Obtenu trop tôt, il est refusé à la soumission — et l'erreur ressemble à un problème d'identifiants.
- L'état implicite entre étapes. Cookies, jeton CSRF, en-tête d'authentification : dès qu'une étape lit un état global au lieu de le recevoir en paramètre, le scénario n'est plus rejouable.
- Le retry non borné. Une boucle sans plafond ni backoff transforme une erreur transitoire de l'API en saturation de vos threads.
Modéliser le workflow en étapes explicites
Isolez chaque étape dans une fonction qui reçoit ce dont elle a besoin et renvoie ce que la suivante consommera : cookies, token, identifiant de corrélation. Aucune variable globale, aucun singleton de session partagé.
Une étape ressemble donc à run_step(context) -> context, où le contexte est un dictionnaire sérialisable : journalisable, rejouable, comparable d'une exécution à l'autre. Placez la résolution CAPTCHA au plus tard, juste avant l'envoi du formulaire, pour réduire l'écart entre l'obtention du token et sa validation.
Rendre chaque étape idempotente
Une étape idempotente se rejoue sans effet de bord : elle vérifie d'abord si son résultat existe déjà (session valide, formulaire soumis, token encore dans sa TTL) et ne refait le travail que si nécessaire. C'est ce qui autorise un retry avec backoff exponentiel borné — trois tentatives, délai doublé, plafond à 30 s — sans risquer une double soumission.
Exemple Python pour l'envoi d'une tâche reCAPTCHA v2 :
import os
import requests
API_KEY = os.environ['CAPTCHAAI_KEY']
def submit_recaptcha_v2(sitekey: str, page_url: str) -> str:
payload = {
'clientKey': API_KEY,
'task': {
'type': 'NoCaptchaTaskProxyless',
'websiteURL': page_url,
'websiteKey': sitekey,
},
}
resp = requests.post('https://api.captchaai.com/createTask', json=payload, timeout=30)
resp.raise_for_status()
return resp.json()['taskId']
Notez le timeout=30 : sans lui, une étape bloquée retient un worker indéfiniment. Le polling du résultat est détaillé dans résoudre reCAPTCHA v2 via l'API, et son équivalent dans la prise en charge de Turnstile.
Dimensionner les threads quand les scénarios tournent en parallèle
La facturation CaptchaAI se fait par thread simultané, résolutions illimitées par thread : un thread correspond à une résolution en cours. Comptez donc les scénarios que vous voulez voir progresser en même temps, pas le volume mensuel.
- 5 parcours en parallèle la nuit : BASIC ($15/mois, 5 threads).
- Plusieurs équipes qui déclenchent des recettes en journée : STANDARD ($30/mois, 15 threads).
- Une matrice de navigateurs et de locales rejouée chaque nuit : ADVANCE ($90/mois, 50 threads).
La facturation est en dollars US. Si vos workers tournent chez OVHcloud, Scaleway ou en région AWS eu-west-3, chronométrez la latence réseau séparément du temps de résolution.
Instrumenter les appels et conserver les journaux utiles
Pour chaque résolution, tracez quatre valeurs : durée d'obtention du token, code retour HTTP, identifiant de tâche et profondeur de votre file d'attente interne. Elles suffisent à distinguer une lenteur côté service d'une saturation côté client. Séparez les journaux par environnement et propagez un identifiant de corrélation unique, par exemple via OpenTelemetry : vous rejouez alors un parcours complet à partir de ce seul identifiant.
Côté RGPD, un parcours de login manipule des identifiants et parfois des données personnelles de comptes de test : journalisez les métadonnées techniques, pas les valeurs de formulaire, et purgez les traces selon la durée de conservation retenue avec votre équipe conformité.
Exemple : la recette nocturne d'un éditeur SaaS
Une équipe produit rejoue chaque nuit un parcours d'inscription sur sa préproduction européenne : création de compte, formulaire protégé par Cloudflare Turnstile, puis vérification d'un e-mail transactionnel.
Trois étapes indépendantes, chacune écrivant son contexte dans un fichier JSON horodaté. Quand la troisième échoue, l'équipe ne relance qu'elle, à partir du contexte sauvegardé. Le gain n'est pas la vitesse : ce sont des échecs interprétables sans rejouer le parcours entier.
Dépannage
| Problème | Cause probable | Correctif |
|---|---|---|
| Token refusé à la soumission | TTL dépassée entre obtention et envoi | Déplacez la résolution juste avant l'envoi du formulaire |
| Étape rejouée qui duplique une soumission | Étape non idempotente | Ajoutez une vérification d'état avant l'action |
| Workers bloqués, file d'attente qui monte | Appel HTTP sans timeout | Fixez un timeout explicite et un plafond de retry |
| Échecs concentrés aux heures de pointe | Threads du plan saturés | Réduisez le parallélisme ou passez au palier supérieur |
Liste de contrôle avant mise en production
- Le périmètre reste limité à vos applications ou à des sources autorisées.
- La clé CaptchaAI vit dans un secret CI ou un coffre, jamais dans le code source.
- Chaque étape reçoit son contexte en paramètre et renvoie un contexte sérialisable.
- Le retry est borné : nombre de tentatives, backoff exponentiel, plafond de délai.
- Durées, codes retour et identifiants de tâche sont tracés, sans donnée personnelle inutile.
FAQ
Combien de temps un token CAPTCHA reste-t-il exploitable ?
Quelques minutes seulement, selon le type. Obtenez-le dans l'étape qui va l'envoyer, jamais en début de parcours : si votre scénario comporte une pause (attente d'un e-mail, d'un webhook), placez la résolution après la pause.
CaptchaAI prend-il en charge hCaptcha pour mes étapes de login ?
Non — hCaptcha n'est pas pris en charge, pas plus que FunCaptcha (Arkose Labs) ; GeeTest v4 est annoncé comme à venir. Pour un parcours de login, appuyez-vous sur reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3 et les CAPTCHA image/OCR. CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta) restent expérimentaux.
Quel plan choisir pour un workflow qui s'exécute en parallèle ?
Comptez vos résolutions simultanées, pas votre volume mensuel : chaque plan inclut des résolutions illimitées par thread. Cinq scénarios en parallèle tiennent sur BASIC ($15/mois, 5 threads) ; une matrice plus large justifie ADVANCE ($90/mois, 50 threads).
Ce guide couvre-t-il l'automatisation de sites que je ne contrôle pas ?
Non. Tous les exemples portent sur vos propres applications ou sur des environnements de test autorisés par écrit. Pour une source externe, vérifiez d'abord les conditions d'utilisation et la base juridique applicable.
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 à votre chaîne CI
- Résoudre reCAPTCHA v2 via l'API
- Prendre en charge Cloudflare Turnstile via l'API
Découpez, mesurez, rejouez : c'est ce qui rend un parcours automatisé fiable. – Obtenez votre clé CaptchaAI.
