Python BeautifulSoup + CaptchaAI pour des projets autorisés

Périmètre sûr : Ce guide s'applique exclusivement à vos propres applications, 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 le contournement de protections, ni l'évasion d'anti-bot.

Si la page que vous collectez est rendue côté serveur, vous n'avez pas besoin d'un navigateur : requests récupère le HTML, BeautifulSoup l'analyse, et CaptchaAI fournit le token quand un défi CAPTCHA s'intercale. Le gain est net : pas de démarrage de navigateur, pas de moteur de rendu, une empreinte mémoire minuscule.

La limite est tout aussi nette : dès que le contenu utile est injecté par JavaScript, ce pipeline ne voit qu'une coquille vide et il faut passer à Selenium ou Playwright.

Le rôle de chaque brique

Cette séparation explique la plupart des erreurs de départ : attendre de BeautifulSoup qu'il « voie » un widget monté par script, ou recréer un client HTTP à chaque étape.

Le pipeline, étape par étape

1. Récupérez la page avec une requests.Session() unique, User-Agent réaliste et Accept-Language cohérent.
2. Analysez le HTML avec BeautifulSoup et lxml, plus rapide et plus tolérant que l'analyseur intégré.
3. Extrayez les paramètres du défi : l'attribut data-sitekey, puis, en repli, les scripts inline qui portent la clé du site.
4. Collectez tous les champs cachés : les tokens CSRF y vivent, et leur absence renvoie le formulaire à la page de départ.
5. Envoyez la tâche à CaptchaAI et interrogez le résultat jusqu'à obtenir le token.
6. Réinjectez le token sous le nom de champ attendu, puis postez le formulaire avec la même session.
7. Analysez la page de résultat — la session reste authentifiée pour les appels suivants.

Le nom du champ de token dépend du type : g-recaptcha-response pour reCAPTCHA v2 et v3, cf-turnstile-response pour Cloudflare Turnstile. Se tromper de nom produit un échec silencieux côté serveur, sans message exploitable.

Envoyer la tâche depuis Python

L'envoi est un simple POST ; la subtilité est de conserver l'identifiant de tâche pour interroger le résultat.

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

La clé vient d'une variable d'environnement, jamais du code source : secret de projet sur un runner GitHub Actions ou GitLab CI, coffre sur une machine OVHcloud ou Scaleway.

Un cas concret : la préproduction d'un portail interne

Une équipe QA valide chaque nuit le parcours de connexion de son propre portail client, déployé sur une instance Scaleway à Paris. Le formulaire de préproduction porte un widget Turnstile, comme la production : sans résolution automatisée, la campagne s'arrête à la première page.

Le pipeline BeautifulSoup + CaptchaAI la débloque : une trentaine de scénarios, un token chacun, un rapport HTML comparé au précédent. Le plan BASIC ($15/mois, 5 threads) suffit à ce volume ; STANDARD ($30/mois, 15 threads) absorbe des campagnes horaires sur plusieurs environnements. Côté données, gardez le réflexe RGPD : identités fictives pour les comptes de test, aucune donnée réelle dans les journaux.

BeautifulSoup ou navigateur headless ?

Pour trancher : ouvrez la page avec curl. Si le sitekey figure dans la réponse brute, restez sur BeautifulSoup.

Observabilité et journalisation

Instrumentez les appels CAPTCHA dès la première version : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente interne. Ces quatre signaux distinguent une lenteur réseau d'une régression côté source.

Séparez les journaux par environnement et corrélez les identifiants avec votre traçage distribué, OpenTelemetry par exemple. Tracez aussi le nombre de lignes extraites : ce compteur révèle une refonte CSS côté source avant que le parsing ne renvoie des listes vides.

Dépannage

Liste de contrôle avant mise en production

• Périmètre limité à vos propres applications ou à des sources autorisées.
• Clé CaptchaAI en secret CI ou en coffre, jamais dans le code.
• Durées d'appel et codes retour tracés à chaque exécution.
• Retry idempotent avec backoff exponentiel borné sur les erreurs transitoires.
• Aucune donnée personnelle réelle dans les jeux de test.
• Exécutions reproductibles depuis votre intégration continue.

FAQ

Quel plan CaptchaAI prévoir pour un pipeline BeautifulSoup ?

Le plan BASIC ($15/mois, 5 threads) couvre la plupart des campagnes de QA nocturnes, la facturation portant sur les threads simultanés. Passez à STANDARD ($30/mois, 15 threads) quand plusieurs environnements tournent en parallèle.

Le sitekey est introuvable dans le HTML : que faire ?

Confirmez avec curl que la valeur est absente de la réponse brute. Si oui, le widget est monté côté client : aucun analyseur HTML ne le verra, et le scénario relève d'un navigateur headless.

CaptchaAI prend-il en charge hCaptcha ?

Non — hCaptcha et FunCaptcha ne sont pas pris en charge, et GeeTest v4 est à venir. Le pipeline couvre reCAPTCHA v2 et v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3 et les CAPTCHA image ou texte ; CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta) restent en évaluation.

Comment cadrer le parsing par rapport au RGPD ?

Minimisez les données collectées, n'extrayez que les champs utiles au contrôle qualité et purgez les journaux selon une durée définie à l'avance. Validez vos obligations RGPD avec votre référent conformité avant d'industrialiser une collecte.

Guides connexes

• Le démarrage rapide de l'API
• Tests CAPTCHA en environnement autorisé
• Vérifier l'endpoint API sur vos formulaires
• Brancher la résolution CAPTCHA dans votre CI
• Obtenir un token reCAPTCHA v2 via l'API
• Obtenir un token Cloudflare Turnstile via l'API

Gardez vos parcours de collecte autorisés reproductibles, mesurés et documentés. – Obtenez votre clé CaptchaAI.