Périmètre sûr : ce guide vise vos propres applications, vos environnements de QA ou de production, ou des systèmes pour lesquels vous disposez d'une autorisation écrite — pas l'automatisation de sites tiers que vous ne contrôlez pas.
Yandex SmartCaptcha est le service anti-bot de Yandex Cloud. Il agit d'abord en mode proactif — il observe la session et laisse passer sans friction les utilisateurs jugés fiables — puis n'affiche un défi visuel qu'en cas de suspicion. Le navigateur obtient alors un token que votre serveur doit valider auprès de l'API Yandex avant d'accepter la requête. Comprendre ce cycle — déclenchement, token, vérification — suffit à intégrer un formulaire protégé. Vous le rencontrez surtout sur Yandex Cloud et les services russophones, à la place de reCAPTCHA ou Cloudflare Turnstile ailleurs.
Les trois acteurs du dispositif
Le dispositif se partage en trois rôles ; tant que chacun garde le sien, l'intégration se raisonne sans surprise.
| Acteur | Rôle |
|---|---|
| Front-end | Affiche le widget à partir du sitekey (clé publique). |
| Service SmartCaptcha | Évalue la session et produit le token. |
| Backend | Vérifie le token avec la clé privée avant d'agir. |
Le cycle de vie d'un défi
- Le widget se charge avec le sitekey.
- SmartCaptcha évalue la session : passage invisible ou défi visuel.
- L'épreuve franchie, un token à durée de vie courte revient dans la page.
- Le token accompagne l'envoi du formulaire vers votre backend.
- Votre serveur le valide auprès de Yandex, puis accepte ou rejette la requête.
La validation côté serveur
C'est ici que se joue l'essentiel. Votre backend transmet le token reçu, avec votre clé serveur privée, au point de validation de Yandex, puis lit le verdict avant d'autoriser l'action. Ne faites jamais confiance à un token validé côté client : il se falsifie trivialement. Côté conformité, restez sobre sur les journaux — l'identifiant de session et l'horodatage suffisent, dans l'esprit du RGPD.
Intégrer la résolution CAPTCHA dans vos tests autorisés
Pour valider un parcours protégé dans votre suite de tests, une API de résolution évite de mobiliser un opérateur humain. CaptchaAI expose une interface unique pour les familles qu'il prend en charge : reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, CAPTCHA image/OCR et grilles. La facturation repose sur les threads (BASIC à $15/mois, 5 threads), résolutions illimitées par thread. Commencez simplement, par la lecture du solde :
import os
import requests
API_KEY = os.environ['CAPTCHAAI_KEY']
def get_balance() -> float:
resp = requests.post(
'https://api.captchaai.com/getBalance',
json={'clientKey': API_KEY},
timeout=15,
)
resp.raise_for_status()
return float(resp.json().get('balance', 0))
Observabilité et journalisation
Instrumentez chaque appel CAPTCHA pour des métriques exploitables : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente. Corrélez ces journaux, séparés par environnement, à votre traçage distribué (OpenTelemetry, région eu-west-3 à Paris) : vous rejouez alors un incident complet depuis un identifiant unique.
Dépannage
| Problème | Cause probable | Correctif |
|---|---|---|
| Token toujours refusé | Vérification serveur absente ou mauvaise clé | Validez le token via l'API Yandex avec la clé privée. |
| Défi visuel trop fréquent | Sensibilité de la clé trop élevée | Abaissez le niveau ; vérifiez la réputation réseau. |
| Token expiré à l'envoi | Délai trop long avant l'envoi | Soumettez le formulaire dès l'obtention du token. |
Liste de contrôle
- Le périmètre reste limité à vos propres applications ou à des sources autorisées.
- Le token est vérifié côté serveur avec la clé privée, jamais sur la seule foi du navigateur.
- La clé CaptchaAI vit dans un secret CI ou un coffre, jamais dans le code source.
- Les durées d'appel et les codes retour sont tracés, avec un retry idempotent sur les erreurs transitoires.
FAQ
Qu'est-ce qui déclenche un défi visuel dans SmartCaptcha ?
Le score de risque calculé en amont. Si les signaux paraissent fiables, l'utilisateur passe sans épreuve ; sinon, un défi image s'affiche. Le seuil relève de Yandex ; vous réglez la sensibilité de la clé à sa création.
Comment valider un token SmartCaptcha côté serveur ?
Envoyez le token reçu et votre clé serveur privée au point de validation de Yandex, puis lisez le verdict avant d'autoriser l'action. Un token accepté côté client ne prouve rien.
Quelle différence entre Yandex SmartCaptcha et reCAPTCHA ?
Le principe est proche — scoring silencieux, défi visuel en secours, token à valider côté serveur — mais l'écosystème diffère : SmartCaptcha s'ancre dans Yandex Cloud et le marché russophone, là où reCAPTCHA relève de Google.
Guides connexes
- Le guide de démarrage rapide CaptchaAI
- La QA CAPTCHA en environnement autorisé
- Tester l'endpoint API sur vos formulaires
- L'intégration CAPTCHA en CI
- Résoudre reCAPTCHA v2 via l'API
Passez du modèle mental à une intégration mesurée et reproductible. – Obtenez votre clé CaptchaAI.
