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 la neutralisation de protections, ni l'évasion d'anti-bot.
Associer l'extension CaptchaAI à des proxys résidentiels tient la charge en production dès lors que vous traitez l'ensemble comme un workflow de navigateur reproductible, et non comme une case à cocher activée une fois. Quatre points font la différence : l'état du compte, l'isolation du profil, le choix du gestionnaire de CAPTCHA et le comportement après résolution.
Ce qui rend l'association stable
- État du compte sain : clé valide et solde suffisant, sinon chaque tâche échoue avant même d'atteindre le proxy.
- Profil de navigateur isolé et reproductible, monté depuis un répertoire figé.
- API unique, facturation par thread : les familles reCAPTCHA, Cloudflare Turnstile et GeeTest v3 passent par le même appel, sans surcoût par résolution.
Le flux de résolution, étape par étape
- Capturez uniquement les paramètres attendus : sitekey, URL de la page, action et proxy éventuel.
- Créez la tâche via l'API et journalisez tout statut différent du succès comme une erreur.
- Interrogez le résultat à intervalle régulier, avec un plafond de temps par tâche.
- Appliquez le token dans la même session que le défi : même contexte, mêmes cookies, même proxy.
- Mesurez latence, retries et acceptation en aval, séparément de la réussite de résolution.
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 de CI, jamais dans le code source ; le déploiement la monte en variable d'environnement. Prévoyez une alerte de solde bas : un compte vide fait échouer chaque tâche avec un ERROR_ZERO_BALANCE.
Exemple d'appel côté serveur
Appel HTTP côté serveur, dans votre propre service, pour créer une tâche Turnstile :
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;
}
Signaux à surveiller
- Durée d'obtention du token et code retour HTTP, par famille de CAPTCHA.
- Identifiant de tâche corrélé à votre traçage distribué (OpenTelemetry) pour rejouer un incident.
- Réussite de résolution et acceptation en aval suivies séparément : deux métriques distinctes.
Scénario concret
Prenons une équipe de collecte autorisée hébergée sur OVHcloud, avec des workers en région Paris (eu-west-3). L'extension tourne dans un profil de navigateur dédié et chaque worker sort par un proxy résidentiel distinct. Côté conformité, l'équipe applique une logique RGPD : elle minimise les données personnelles collectées et documente la base juridique de chaque source. Quand une page bascule d'un défi CAPTCHA à un autre, seul le type de tâche change dans l'appel API.
Liste de contrôle avant mise en production
| Contrôle | Pourquoi c'est important |
|---|---|
| Clé en coffre ou secret de CI | Une clé en clair fuit dans les logs et l'historique Git. |
| Même session, mêmes cookies, même proxy | Une session incohérente est la première cause de rejet du token. |
| Plafond de temps et retry idempotent | Les erreurs transitoires ne dégénèrent pas en boucles de retry. |
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé recopiée avec un espace parasite ou mauvais compte. | Recopiez la clé depuis le tableau de bord et stockez-la en secret de CI. |
ERROR_PAGEURL / ERROR_BAD_PARAMETERS |
Paramètre requis manquant ou mal formé. | Revalidez l'URL de page et le sitekey face au HTML réel. |
| Token refusé après résolution | Résolution appliquée dans une autre session que le défi. | Gardez résolution et soumission dans le même contexte de navigateur. |
FAQ
La résolution et le proxy résidentiel doivent-ils partager la même session ?
Oui. Token, cookies et sortie proxy doivent rester cohérents entre le moment où le défi apparaît et celui où vous soumettez le formulaire. Appliquez la résolution dans le même contexte de navigateur — ou le même client HTTP — que celui qui continue le parcours.
Comment isoler le profil de navigateur entre les exécutions ?
Montez l'extension depuis un répertoire de profil dédié et repartez d'un état connu à chaque exécution. Un profil partagé transforme un incident isolé en régression difficile à reproduire.
Le coût augmente-t-il avec le volume de résolutions ?
Non, pas au solve près : CaptchaAI facture par thread simultané, avec un nombre illimité de résolutions par thread. L'offre BASIC ($15/mois, 5 threads) suffit pour valider une intégration ; vous montez ensuite en threads selon votre débit.
Guides connexes
- le guide de démarrage rapide CaptchaAI
- la QA CAPTCHA en environnements autorisés
- tester l'endpoint API sur vos formulaires
- l'intégration des CAPTCHA en CI
- résoudre reCAPTCHA v2 via l'API
Fiabilisez vos workflows CAPTCHA avec une intégration méthodique et reproductible. – Obtenez votre clé CaptchaAI.
