Périmètre sûr : Ce guide s'applique exclusivement à vos propres applications et environnements (QA, préproduction, production), ou à des sources pour lesquelles 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.
Un crawler de backlinks qui tourne sans surveillance finit toujours par croiser un CAPTCHA : un reCAPTCHA sur un formulaire de contact, un Turnstile devant un annuaire, une image OCR sur un vieux répertoire. Sans traitement propre, le job s'arrête ou, pire, remonte des données incomplètes que personne ne remarque avant le reporting. Ce guide montre comment brancher la résolution de CAPTCHA via l'API CaptchaAI sur votre outil de découverte de backlinks, pour que les crawls autorisés aillent au bout sans intervention manuelle.
Pourquoi les CAPTCHA faussent un crawl de backlinks
L'enjeu d'un audit de netlinking n'est pas qu'un script « fonctionne une fois », mais d'obtenir des crawls complets et des rapports fiables. Un défi CAPTCHA rencontré à mi-parcours brise cette continuité : la page protégée n'est pas indexée, le domaine référent disparaît du jeu de données, et l'écart passe inaperçu tant que le volume reste faible.
CaptchaAI répond à ce besoin avec une seule API pour les familles reCAPTCHA v2/v3, Cloudflare Turnstile, GeeTest v3, image/OCR et grille, et une facturation par thread qui ne vous pénalise pas quand le volume monte. Vous branchez le solveur là où le crawl bloque, sans réécrire votre pipeline.
Architecture : un composant de résolution isolé
Gardez la résolution de CAPTCHA dans un composant dédié plutôt que de la disperser dans votre crawler. Ce module appelle CaptchaAI en HTTPS, récupère un token, puis le renvoie à l'étape qui continue la navigation. L'isoler vous permet de le tester indépendamment du crawl, de tracer chaque appel au même endroit, et de détecter une régression dès la montée de version.
En pratique, votre worker reçoit les paramètres du défi (sitekey, URL de la page, action éventuelle, proxy optionnel), délègue la résolution, puis injecte le token dans la même session que celle qui a déclenché le défi. Appliquer un token dans un autre contexte navigateur est la première cause de rejet après résolution.
Le contrat soumission / interrogation
Le flux se résume à deux appels, dans cet ordre :
- Soumettez la tâche à
in.phpavecjson=1et traitez tout statut différent de1comme une erreur à journaliser. - Interrogez le résultat sur
res.php: attendez 15 s avant la première interrogation, puis interrogez toutes les 5 s, avec un plafond strict de 120 s par tâche. Tant que la réponse vautCAPCHA_NOT_READY, la boucle continue ; toute autre valeur interrompt le traitement.
Distinguez enfin la réussite du solveur (le token est renvoyé) de la réussite du workflow (la page aval accepte le token) : un audit fiable suit les deux séparément.
Gérer la clé API et les secrets
La clé CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret de CI, jamais en clair dans le dépôt ; le déploiement la monte en variable d'environnement au runtime. C'est autant une question de sécurité que d'exploitation : une clé recopiée à la main avec un espace parasite génère des ERROR_WRONG_USER_KEY pénibles à diagnostiquer.
Exemple : créer une tâche Turnstile
Exemple côté client, tel qu'il vivrait dans votre propre suite de tests :
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;
}
Le contrat reste identique quelle que soit la pile : isolez l'environnement, tracez les appels, mesurez délais et réussite, puis automatisez la validation dans votre CI. La logique se transpose vers Go, Ruby ou Java sans changement.
Mesurer ce qui compte
Un crawl que vous ne mesurez pas est un crawl que vous ne pouvez pas défendre. Suivez la latence du premier solve (p50 et p95), le taux de réussite du solveur par famille de CAPTCHA, l'acceptation aval après injection du token, et le coût par solve. Câblés dans le tableau de bord que votre équipe utilise déjà, ces signaux révèlent une dérive avant le reporting. Fixez vos cibles à partir de vos propres mesures, qui varient selon l'environnement, le volume et l'heure de la journée.
Dépannage
Ces erreurs couvrent l'essentiel des tickets sur ce type d'intégration ; chaque correctif s'applique sans quitter votre éditeur.
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace parasite ou mauvais compte. | Recopiez la clé depuis le tableau de bord, stockez-la en secret CI. |
ERROR_ZERO_BALANCE |
Solde sous le minimum par tâche. | Rechargez le solde, ajoutez une alerte de solde bas. |
ERROR_PAGEURL / ERROR_BAD_PARAMETERS |
Paramètre requis manquant ou mal formé. | Revalidez l'URL de la page et le sitekey contre le HTML en direct. |
| Token refusé après résolution | Token injecté dans une autre session que celle du défi. | Gardez résolution et soumission dans le même contexte navigateur. |
Liste de contrôle avant mise en production
- Le périmètre reste limité à vos applications ou à des sources sous accord écrit.
- La clé CaptchaAI vit dans un coffre ou un secret CI, jamais dans le dépôt.
- Chaque appel trace sa durée, son code retour HTTP et l'identifiant de tâche.
- Un budget de retry borné (trois tentatives, backoff exponentiel plafonné à 30 s) est en place.
- Les tests d'intégration sont rejouables depuis votre CI, et vos obligations RGPD sont vérifiées.
FAQ
Le scraping de backlinks est-il autorisé ?
Cela dépend de la source et de la finalité. Un crawl sur vos propres domaines ou sur des sources couvertes par un accord écrit est le cadre visé ici. Dès qu'un site tiers entre en jeu, vérifiez ses conditions d'utilisation et votre base légale, et minimisez les données personnelles collectées au titre du RGPD.
Quel plan CaptchaAI pour un crawl de backlinks à grand volume ?
La facturation est par thread, avec des résolutions illimitées par thread. Votre débit dépend donc du nombre de threads en parallèle, pas du nombre de défis. Le plan BASIC ($15/mois, 5 threads) suffit pour un crawl modeste ; montez vers STANDARD ($30/mois, 15 threads) ou ADVANCE ($90/mois, 50 threads) quand vous parallélisez davantage.
Comment éviter que les CAPTCHA faussent mes données de backlinks ?
Suivez séparément la réussite du solveur et l'acceptation aval, puis alertez sur l'écart entre les deux. Une page protégée que votre crawler abandonne silencieusement crée un trou dans le jeu de données que le rapport ne signale pas.
CaptchaAI prend-il en charge hCaptcha pour ce type de crawl ?
Non — pas encore pris en charge, pas plus que FunCaptcha (Arkose Labs) ou GeeTest v4 (à venir). CaptchaAI couvre reCAPTCHA v2/v3, Cloudflare Turnstile et Challenge, GeeTest v3, image/OCR, grille et BLS, avec CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta).
Guides connexes
- Le démarrage rapide CaptchaAI
- Les tests QA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- Brancher la résolution CAPTCHA sur votre CI
- Résoudre reCAPTCHA v2 via l'API
Fiabilisez vos workflows CAPTCHA avec une approche méthodique et reproductible. – Obtenez votre clé CaptchaAI.
