Périmètre sûr : ce guide porte sur vos propres applications et environnements, ou des systèmes pour lesquels vous détenez une autorisation écrite. Il n'aborde pas l'automatisation de sites tiers.
cap.js se joue en trois temps : le navigateur reçoit un défi, le client le résout, puis votre serveur valide le token produit. Gardez ces trois acteurs en tête et l'intégration devient lisible. En production, ce qui casse n'est presque jamais le widget : c'est un token appliqué dans la mauvaise session ou un manque de métriques.
cap.js en bref
cap.js (aussi appelé Cap) se présente comme une alternative CAPTCHA open source et auto-hébergeable. Plutôt que le pistage comportemental, il repose sur une preuve de travail (proof of work) : le navigateur calcule la réponse à un problème cryptographique, transparente pour l'utilisateur mais coûteuse à grande échelle. Le token est émis côté client et ne vaut rien tant que votre backend ne l'a pas vérifié.
Le modèle mental : trois acteurs
Avant d'écrire une ligne, identifiez qui fait quoi :
- Le front-end déclenche le défi et affiche le widget.
- Le fournisseur du CAPTCHA (ici cap.js, auto-hébergé ou distant) produit le token.
- Votre backend vérifie le token avant d'accepter la requête.
Gardez ce trio en tête et vous saurez toujours où chercher en cas de problème.
Ce que vous maîtrisez côté application
Trois leviers, et eux seuls, font la qualité de l'intégration :
- la configuration du widget côté page ;
- la vérification du token côté serveur ;
- la décision appliquée selon le résultat.
Le calcul de la preuve et le rendu du défi vous échappent, et c'est très bien ainsi.
La boucle d'intégration, étape par étape
Quelle que soit la famille de CAPTCHA, la boucle reste la même ; l'ordre compte plus que le langage.
- Capturez les paramètres attendus (sitekey, URL, action, proxy) depuis la page réelle.
- Envoyez la tâche au service de résolution et journalisez tout statut inattendu.
- Interrogez le résultat : 15 s d'attente, puis toutes les 5 s, plafond de 120 s par tâche.
- Appliquez le token dans la session qui a déclenché le défi — même contexte, même cookie jar.
- Mesurez latence, retries et acceptation en aval : réussite du solveur et du workflow sont distinctes.
Exemple de code
L'intégration commence par un contrôle indispensable : vérifier le solde avant de lancer un lot. Cet extrait échoue tôt si la clé ou le solde pose problème :
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 : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de file. Fixez deux cibles — une latence de première résolution sous un seuil acceptable et un taux de réussite d'au moins 95 % par famille — mais mesurez les vôtres, car elles varient selon le volume.
Côté RGPD, ne conservez ni adresse IP ni données personnelles au-delà du nécessaire, surtout pour des workers en Union européenne (eu-west-3, Paris).
Dépannage
Quelques causes reviennent souvent :
| Symptôme | Cause probable | Correctif |
|---|---|---|
| Token refusé après résolution | Session différente de celle du défi | Gardez résolution et soumission dans la même session. |
ERROR_WRONG_USER_KEY |
Clé mal copiée ou mauvais compte | Recopiez la clé, stockez-la en secret CI. |
ERROR_BAD_PARAMETERS |
Paramètre manquant ou mal formé | Revalidez URL et sitekey contre le HTML réel. |
Liste de contrôle
- Le périmètre reste limité à vos applications ou sources autorisées.
- La clé CaptchaAI vit dans un secret CI ou un coffre, jamais dans le code.
- Les durées et codes retour sont tracés ; le retry est borné (trois tentatives, backoff exponentiel).
FAQ
cap.js repose-t-il sur une preuve de travail ?
Oui. cap.js appartient à la famille des CAPTCHA à preuve de travail : le coût du calcul dissuade les envois massifs. Côté serveur, la logique ne change pas : vous vérifiez le token reçu.
Pourquoi mon token cap.js est-il refusé après résolution ?
Presque toujours parce qu'il est appliqué dans une autre session que celle du défi. Conservez le même contexte navigateur et le même cookie jar, puis vérifiez que le token n'a pas expiré.
Faut-il un vrai navigateur pour gérer cap.js ?
Si votre flux passe déjà par un navigateur headless (Selenium, Puppeteer, Playwright), gardez-le : la preuve s'y exécute nativement. Pour un flux purement HTTP, isolez la résolution derrière la même boucle.
Guides connexes
- le démarrage rapide CaptchaAI
- la résolution de CAPTCHA en QA autorisée
- tester l'endpoint API sur vos formulaires
- intégrer les CAPTCHA dans votre CI
- résoudre reCAPTCHA v2 via l'API
D'un flux fragile à une intégration que vous pouvez surveiller. — Créez votre clé CaptchaAI.
