Gérer reCAPTCHA v2 dans des collectes autorisées

Périmètre sûr : ce guide vise uniquement vos propres applications, vos environnements de QA, de préproduction ou de production, ou toute source pour laquelle vous détenez une autorisation écrite. Il ne couvre ni l'automatisation de sites tiers, ni le contournement de protections, ni l'évasion de dispositifs anti-bot.

Dans une collecte de données autorisée, un reCAPTCHA v2 se gère en trois gestes : récupérez la sitekey et l'URL de la page, demandez un token à l'API CaptchaAI, puis injectez ce token dans le champ g-recaptcha-response. Aucune manipulation manuelle du widget n'est nécessaire — le token validé suffit à faire passer le formulaire côté serveur, et l'ensemble reste inscrit dans un cadre que vous maîtrisez.

Le reste de ce guide déroule ce parcours pas à pas, avec un exemple Python, les points d'instrumentation à prévoir et les garde-fous de conformité attendus sur un pipeline francophone.

Ce dont vous avez besoin : sitekey et URL de la page

Chaque widget reCAPTCHA v2 expose deux valeurs que votre client doit transmettre :

• la sitekey — la clé publique intégrée au HTML de la page, portée par l'attribut data-sitekey de l'élément .g-recaptcha ;
• l'URL de la page — l'adresse exacte où le défi apparaît.

Ces deux paramètres suffisent à décrire la tâche. CaptchaAI résout le défi sur sa propre infrastructure : vous n'avez pas à fournir votre proxy pour un reCAPTCHA v2 standard, ni à charger le widget vous-même. Gardez vos proxys pour les requêtes de collecte qui suivent la résolution, pas pour l'appel de résolution.

Soumettre la tâche reCAPTCHA v2 et récupérer le token

L'appel createTask renvoie un identifiant de tâche. Le client interroge ensuite getTaskResult à intervalle régulier jusqu'à obtenir le token, puis l'injecte dans le champ g-recaptcha-response. Cette interrogation (polling) doit rester mesurée : un intervalle de quelques secondes évite de saturer l'API sans allonger inutilement le délai global.

Exemple Python :

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']

Conservez la clé dans une variable d'environnement ou un coffre à secrets, jamais en clair dans le dépôt. Le timeout explicite sur la requête protège votre worker d'un appel qui resterait suspendu.

Injecter le token reCAPTCHA v2 dans le formulaire

Une fois le token récupéré, deux cas se présentent. Si la page attend une soumission classique, écrivez le token dans le champ caché g-recaptcha-response, puis envoyez le formulaire. Si le widget déclare un data-callback, appelez cette fonction avec le token en argument : certaines pages ne débloquent le bouton d'envoi qu'après l'exécution du callback. Un token reCAPTCHA v2 est à usage unique et sa durée de validité est courte (de l'ordre de deux minutes) ; injectez-le et soumettez sans attendre.

Concurrence et volumétrie : le modèle par threads

CaptchaAI facture par thread simultané, pas par résolution. L'offre BASIC ($15/mois, 5 threads) autorise cinq résolutions en parallèle, chaque thread enchaînant les tâches sans plafond mensuel ; STANDARD ($30/mois, 15 threads) et ADVANCE ($90/mois, 50 threads) élargissent ce parallélisme quand votre volume grimpe. Pour une collecte soutenue, la bonne question n'est donc pas « combien de résolutions par jour » mais « combien de défis en vol au même instant ».

Côté hébergement, un worker déployé sur OVHcloud, Scaleway ou une région AWS européenne comme eu-west-3 (Paris) réduit la latence réseau entre votre pipeline et les pages ciblées, ce qui rend vos mesures de temps de résolution plus stables et plus faciles à comparer d'une exécution à l'autre.

Observabilité et journalisation

Quel que soit le langage, instrumentez les appels CAPTCHA pour obtenir des métriques exploitables : durée totale d'obtention du token, code retour HTTP, identifiant de tâche et taille de votre file d'attente interne. Ces signaux alimentent vos tableaux de bord de QA et vos alertes.

Séparez les logs 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 identifiant unique. En cas d'incident, ces journaux réduisent nettement le temps de diagnostic.

Conformité RGPD des collectes autorisées

Une collecte autorisée reste une collecte de données : appliquez les principes du RGPD dès la conception. Minimisez les données personnelles récupérées, documentez la base juridique de chaque source et fixez une durée de conservation. Les tokens, sitekeys et URL n'ont pas à voisiner en clair avec des données identifiantes dans vos logs. En cas de doute sur une source externe, vérifiez d'abord les conditions d'utilisation et vos obligations avant d'automatiser quoi que ce soit — la question de conformité précède toujours la question technique.

Liste de contrôle avant la mise en production

• Le périmètre est strictement limité à vos propres applications ou à des sources dûment autorisées.
• La clé CaptchaAI est stockée dans un secret CI ou un coffre, 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 couvre les erreurs transitoires.
• Les tests sont rejouables et reproductibles depuis votre intégration continue.
• Les obligations RGPD de chaque source ont été vérifiées avant automatisation.

FAQ

Ce guide concerne-t-il l'automatisation de sites tiers ?

Non. Tous les exemples portent sur vos propres applications ou sur des environnements pour lesquels vous disposez d'une autorisation écrite. Aucune technique d'évasion ou d'anti-détection sur des sites publics que vous ne contrôlez pas n'y figure. Pour une source externe, validez les conditions d'utilisation et la base juridique avant toute automatisation.

Un token reCAPTCHA v2 peut-il être réutilisé ?

Non. Chaque token est à usage unique et sa validité est courte, de l'ordre de deux minutes. Vous devez demander une résolution fraîche pour chaque page protégée : mettre un token en cache mène à des refus côté serveur.

Comment adapter cette méthode à ma pile technique ?

Le déroulé reste identique quel que soit le langage : isolez l'environnement, tracez les appels CAPTCHA, mesurez les délais et le taux de réussite, puis automatisez la validation dans votre intégration continue. L'exemple ci-dessus est en Python, mais la logique se transpose sans difficulté vers Node.js, Go, Ruby, Java ou tout écosystème compatible HTTP.

Que faire en cas d'erreur transitoire de l'API ?

Mettez en place un retry avec backoff exponentiel borné (par exemple trois tentatives, délai doublé à chaque essai, plafond à 30 secondes). Tracez chaque échec avec son identifiant de tâche pour faciliter le diagnostic. Si l'erreur persiste, vérifiez la configuration réseau (DNS, certificats) et les quotas associés à votre clé.

Faut-il un navigateur pour injecter le token ?

Pas toujours. Si le site accepte g-recaptcha-response comme champ d'un POST, une approche HTTP suffit. S'il exige une injection du token par JavaScript ou l'exécution d'un callback, un navigateur piloté (Selenium, Puppeteer) devient nécessaire.

Guides connexes

• Le guide de démarrage rapide CaptchaAI
• La QA des 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
• Résoudre Cloudflare Turnstile via l'API

Fiabilisez vos workflows CAPTCHA dans vos propres environnements avec une méthode reproductible et mesurable. – Obtenez votre clé CaptchaAI.