Configurer le score minimum reCAPTCHA v3 dans l'extension CaptchaAI

Périmètre sûr : ce guide s'applique à vos propres applications, à vos environnements de QA ou de préproduction, ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni l'évasion d'anti-bot.

Le champ « score minimum » affiché dans l'extension CaptchaAI ne modifie pas la requête envoyée au solveur : c'est un repère local pour vos tableaux de bord, pas un paramètre transmis à l'API. Le score reste celui que Google attribue en fonction des signaux attachés à la résolution. Comprendre cette distinction est le point de départ pour fiabiliser une automatisation reCAPTCHA v3 qui tourne sans surveillance, en CI ou derrière une file interne.

Ce que le score minimum contrôle vraiment

L'API HTTP de CaptchaAI — celle que l'extension utilise en coulisses — n'accepte aucun paramètre de score cible, ni pour le reCAPTCHA v3 standard (grecaptcha.execute), ni pour le reCAPTCHA v3 Enterprise (grecaptcha.enterprise.execute). Vous ne « demandez » pas un score de 0,7 : vous recevez celui que Google calcule d'après le comportement observé. Le seuil affiché dans l'extension est donc un indicateur pour vos métriques, jamais un filtre côté API.

Les étapes d'une intégration fiable

Le même enchaînement fonctionne quel que soit votre langage. Une tâche planifiée qui valide chaque nuit un parcours d'inscription sur votre application chez OVHcloud ou Scaleway suit ces cinq étapes :

1. Isolez l'environnement. Séparez la QA de la production, stockez la clé CaptchaAI dans un coffre ou un secret CI, et vérifiez que vos endpoints internes acceptent les requêtes de test.
2. Encapsulez l'appel à CaptchaAI dans une fonction unique qui prend la sitekey et l'URL de la page, retourne un identifiant de tâche, et trace la durée et le code retour.
3. Interrogez le résultat régulièrement plutôt qu'en une fois, avec un délai borné et un plafond par tâche pour éviter les boucles sans fin.
4. Appliquez le token dans la même session que celle qui a déclenché le défi — même contexte de navigateur, même cookie jar.
5. Vérifiez le token côté backend, via l'endpoint de vérification de Google, avant toute opération métier.

Exemple de code réutilisable

Cette fonction Python illustre l'étape 2 : un appel unique renvoyant un identifiant de tâche, réutilisable dans tous vos tests.

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

Agir sur les signaux qui font monter le score

Puisque le score dépend de Google et non d'un seuil local, agissez sur les entrées que l'API accepte réellement dans le profil de l'extension :

• un userAgent réaliste et cohérent ;
• des cookies déjà « chauffés » par une navigation normale ;
• un proxy résidentiel plutôt qu'une IP de datacenter ;
• le même profil de navigateur d'une exécution à l'autre, pour des scores plus stables.

Observabilité et journalisation

Instrumentez chaque appel CAPTCHA pour obtenir des métriques exploitables : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file interne. Séparez les journaux par environnement et corrélez les identifiants à votre traçage distribué, par exemple via OpenTelemetry. Vous pourrez ainsi rejouer un scénario complet depuis un identifiant unique.

Dépannage

FAQ

Le champ « score minimum » de l'extension change-t-il la requête envoyée ?

Non. Il n'est transmis à aucun moment à l'API : il sert uniquement de repère dans vos propres tableaux de bord. Le score reçu est celui que Google attribue à la résolution, indépendamment de la valeur affichée localement.

Comment obtenir un score reCAPTCHA v3 plus élevé ?

Travaillez les signaux joints à la tâche, pas un seuil : un userAgent réaliste, des cookies cohérents et un proxy résidentiel, avec le même profil de navigateur d'une exécution à l'autre.

CaptchaAI prend-il en charge reCAPTCHA v3 Enterprise ?

Oui, reCAPTCHA v3 et reCAPTCHA v3 Enterprise sont pris en charge : vous conservez la même fonction et changez seulement la variante ciblée. La facturation par thread ne change pas — la formule BASIC ($15/mois, 5 threads) suffit pour valider un premier flux.

Que faire si le token est refusé après résolution ?

Vérifiez qu'il est appliqué dans la même session que celle qui a déclenché le défi, puis contrôlez la validation côté serveur. Un token appliqué dans un autre contexte ou après expiration est presque toujours en cause.

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 en CI
• Résoudre reCAPTCHA v2 via l'API

Passez d'un réglage approximatif à une automatisation reCAPTCHA v3 mesurée. — Créez votre compte CaptchaAI.