Un job de veille qui démarre à 4 h du matin ne peut pas attendre qu'un humain clique sur une case. Dès qu'un défi CAPTCHA s'intercale dans le parcours, deux issues : suspendre le lot et perdre la fenêtre de collecte, ou résoudre le défi dans le flux. Cet article décrit la seconde, appliquée aux recherches de brevets et marques, avec l'API CaptchaAI.
L'appel API tient en vingt lignes : ce n'est pas là que ça casse. Le vrai travail est de délimiter un périmètre autorisé, d'injecter le token dans la bonne session et de borner les tentatives.
Périmètre sûr : ce guide vise vos propres applications, vos environnements de QA et de production, et les sources pour lesquelles vous détenez une autorisation écrite. Il ne décrit pas l'automatisation de sites tiers sans accord.
Le scénario : une veille brevets et marques qui tourne sans personne
Prenez un cabinet de propriété industrielle lyonnais qui surveille les dépôts de ses clients. Chaque nuit, un worker hébergé chez OVHcloud rejoue la même liste de requêtes. Une partie des sources répond via une API contractuelle ; l'autre passe par un formulaire dont les conditions d'utilisation autorisent l'accès automatisé du cabinet, avec un défi Cloudflare Turnstile une nuit sur trois.
Le cabinet édite aussi son propre portail client, protégé par un reCAPTCHA v2 : la suite de tests doit le franchir à chaque déploiement. Deux contextes, un seul contrat d'appel.
Cadrer le périmètre avant d'écrire la première ligne
Trois questions se règlent par écrit, jamais de mémoire :
- Qui possède l'application qui affiche le défi : vous, votre client, ou un tiers ?
- Si c'est un tiers, quel document autorise l'accès automatisé — conditions d'utilisation, licence de données, convention de service ?
- Quelles données personnelles la collecte touche-t-elle ? Les registres publient des noms de déposants et de mandataires : vos obligations RGPD s'appliquent.
La boucle d'intégration, étape par étape
- Relevez les paramètres réels. Ne gardez que ce que la famille de CAPTCHA attend : sitekey, URL de page, action, proxy éventuel. Le superflu crée de fausses pistes de diagnostic.
- Envoyez la tâche et traitez toute réponse dont le statut n'est pas
1comme une erreur : journalisez-la, remontez-la sur votre canal de supervision. - Interrogez le résultat. Attendez 15 s, puis toutes les 5 s, avec un plafond dur de 120 s par tâche. Un polling plus agressif n'accélère rien.
- Injectez le token dans la session qui a déclenché le défi — même contexte navigateur, même client HTTP, même cookie jar. Le décalage de session reste la première cause de rejet.
- Mesurez séparément résolution et acceptation. Taux de réussite d'un côté, code HTTP du formulaire de l'autre, alerte sur l'écart.
Exemple : créer une tâche Turnstile depuis votre suite de tests
Le fragment ci-dessous tourne dans la suite de tests du cabinet, contre son propre portail client.
import fetch from 'node-fetch';
const API_KEY = process.env.CAPTCHAAI_KEY;
export async function createTurnstileTask(siteKey, pageUrl) {
const res = await fetch('https://api.captchaai.com/createTask', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
clientKey: API_KEY,
task: {
type: 'TurnstileTaskProxyless',
websiteURL: pageUrl,
websiteKey: siteKey,
},
}),
});
const data = await res.json();
return data.taskId;
}
Rangez la clé dans un secret d'intégration continue, jamais dans le dépôt, et posez un plafond de durée sur le lot nocturne.
Les familles de CAPTCHA rencontrées sur les portails brevets et marques
Quatre familles reviennent : reCAPTCHA v2 et v3, Cloudflare Turnstile, Cloudflare Challenge, et les CAPTCHA image/OCR ou en grille d'images. CaptchaAI les prend toutes en charge, comme GeeTest v3 et les BLS CAPTCHA. CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta) restent en bêta : testez-les avant tout chemin critique.
hCaptcha et FunCaptcha (Arkose Labs), en revanche, ne sont pas pris en charge, et GeeTest v4 est annoncé comme à venir. Si l'une protège une source, prévoyez une étape manuelle.
Fiabilité : retry borné, idempotence, alertes
Bornez le retry à trois tentatives, avec un backoff exponentiel (5 s, 10 s, 20 s) plafonné à 30 s. Au-delà, vous ne corrigez plus une erreur transitoire : vous masquez un défaut de fond.
Donnez à chaque requête un identifiant stable, pour que rejouer un lot ne duplique ni les lignes en base ni les notifications. Alertez sur la dérive, pas sur l'échec unitaire : taux d'échec au-dessus du seuil sur une heure.
Dépannage des erreurs courantes
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Espace parasite dans la clé, ou mauvais compte. | Recopiez la clé et stockez-la comme secret. |
ERROR_ZERO_BALANCE |
Solde insuffisant. | Rechargez et posez une alerte de solde. |
ERROR_PAGEURL / ERROR_BAD_PARAMETERS |
Paramètre manquant ou mal formé. | Revalidez l'URL de page et le sitekey. |
CAPCHA_NOT_READY jusqu'au timeout |
Interrogation lancée trop tôt. | Attendez 15 s, puis toutes les 5 s. |
| Token refusé après résolution | Token injecté dans une autre session. | Gardez le même contexte navigateur jusqu'à la soumission. |
Journalisation, traçage et RGPD
Instrumentez chaque appel : durée d'obtention du token, code retour HTTP, identifiant de tâche, taille de la file d'attente. Propagez un identifiant de corrélation dans votre traçage distribué (OpenTelemetry, par exemple).
Côté RGPD, appliquez la minimisation : un registre de brevets contient des noms de déposants et des coordonnées de mandataires, qui n'ont pas leur place dans un journal technique. Fixez une durée de conservation courte.
Liste de contrôle avant la mise en production
- Le périmètre autorisé est écrit et validé pour chaque source.
- La clé API vit dans un coffre ou un secret d'intégration continue.
- Le token est injecté dans la session qui a déclenché le défi.
- Les tentatives sont bornées à trois et les échecs terminaux journalisés.
- Les journaux ne contiennent aucune donnée personnelle des registres consultés.
Questions fréquentes
Quel plan choisir pour une veille quotidienne ?
Raisonnez en threads, pas en résolutions : un thread correspond à un défi en cours de traitement. Une collecte nocturne de quelques centaines de requêtes tient dans BASIC ($15/mois, 5 threads) ; si vous parallélisez fortement, STANDARD ($30/mois, 15 threads) laisse de la marge. Les résolutions sont illimitées.
Pourquoi mon token est-il refusé alors que la résolution a réussi ?
Le plus souvent parce qu'il est injecté ailleurs que dans la session d'origine : nouveau contexte navigateur, ou cookie jar réinitialisé entre la résolution et la soumission. Vérifiez aussi le délai écoulé : la validité d'un token est courte, et une file d'attente saturée suffit à le périmer.
Comment journaliser sans exposer de données personnelles ?
Ne conservez que des identifiants techniques : identifiant de tâche, horodatage, durée, code retour. Les noms de déposants et les coordonnées de mandataires restent hors des journaux d'intégration.
Faut-il un navigateur headless ou un simple client HTTP ?
Un client HTTP suffit quand vous connaissez le sitekey et l'URL de page et que le formulaire accepte une soumission directe. Passez au navigateur headless (Playwright, Selenium) dès que la page dépend de JavaScript.
Guides connexes
- Le démarrage rapide CaptchaAI
- La QA CAPTCHA en environnement autorisé
- Tester vos formulaires web contre l'endpoint API
- Brancher la résolution sur votre intégration continue
- Résoudre reCAPTCHA v2 via l'API
Branchez la résolution sur votre pipeline et mesurez vos délais dès la première nuit. – Créez votre clé CaptchaAI.
