Utiliser l'extension CaptchaAI avec Chrome headless

Périmètre sûr : ce guide s'applique exclusivement à vos propres applications, à vos environnements de QA, de préproduction ou de 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.

L'extension CaptchaAI se charge dans Chrome headless exactement comme dans un navigateur visible, à une condition : la traiter comme un workflow reproductible, pas comme un clic d'activation ponctuel. Ce qui tient en production, c'est un profil de navigateur stable, une clé API bien stockée, un cycle de résolution instrumenté et une vérification côté backend. Ce tutoriel s'adresse aux ingénieurs qui exploitent des pipelines de collecte autorisée ou des tests de bout en bout, et vise à faire tenir dans la durée une intégration qui, au premier essai, ne marche qu'une fois.

Ce qui change réellement en mode headless

Le mode headless supprime l'interface graphique, pas le CAPTCHA. L'extension a besoin d'un répertoire de profil persistant (--user-data-dir), sinon l'état de session repart de zéro à chaque exécution. Et l'absence d'écran rend la journalisation indispensable : vos logs deviennent votre seule fenêtre sur ce qui se passe.

Préparer un profil de navigateur isolé

Trois conditions à vérifier avant d'écrire la moindre ligne d'intégration :

• L'environnement de QA est isolé de la production et vos endpoints internes acceptent le trafic de test.
• La clé CaptchaAI vit dans un coffre ou un secret CI, jamais dans le code source.
• Chaque pool de workers a son propre répertoire de profil persistant, pour éviter les collisions de cookies.

Le cycle soumission puis interrogation du résultat

L'intégration tient en cinq étapes, valables quelle que soit la famille CAPTCHA :

1. Capturez uniquement ce dont le solveur a besoin — sitekey, URL de page, action et proxy éventuel. Stocker davantage crée de fausses pistes de débogage.
2. Soumettez la tâche à l'API et traitez tout statut d'erreur comme un échec : journalisez la réponse et remontez-la vers votre supervision.
3. Interrogez le résultat : attendez 15 secondes, puis toutes les 5 secondes, avec un plafond strict de 120 secondes par tâche.
4. Appliquez le token dans la même session que celle qui a déclenché le défi. Une session dépareillée est la première cause de rejet.
5. Mesurez la latence, les retries et l'acceptation en aval — réussite du solveur et réussite du workflow sont deux métriques distinctes.

Exemple : encapsuler l'appel dans une fonction

Isolez l'appel à CaptchaAI dans une fonction réutilisable : elle prend le sitekey et l'URL de votre page, retourne un identifiant de tâche et vous laisse tracer la durée et le code retour.

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 déroulé reste identique quel que soit le langage. CaptchaAI expose une seule API sur reCAPTCHA v2/v3, Cloudflare Turnstile et Challenge, GeeTest v3, image/OCR et grilles d'images, plus CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta) : vous changez le type de tâche, la boucle ne bouge pas.

Vérifier le token côté backend

Le token retourné doit être revalidé par votre propre backend avant toute opération métier : aucune requête ne doit être acceptée sur la base d'un token périmé ou appliqué dans une mauvaise session. C'est aussi le bon endroit pour corréler l'identifiant de tâche avec votre traçage distribué.

Dépannage

FAQ

L'extension fonctionne-t-elle vraiment sans interface graphique ?

Oui, à condition de fournir un répertoire de profil persistant et de charger l'extension au lancement du navigateur. La logique de résolution reste identique ; le vrai différenciateur est la journalisation, car sans écran vos logs sont la seule fenêtre sur l'exécution.

Quel plan CaptchaAI choisir pour un pool de workers headless ?

La facturation se fait au thread simultané, avec des résolutions illimitées ; dimensionnez donc les threads sur les tâches réellement en vol, pas sur le volume total :

• BASIC ($15/mois, 5 threads) pour quelques workers de test.
• ADVANCE ($90/mois, 50 threads) pour un pipeline de production plus large.

Comment rester conforme au RGPD en journalisant mes exécutions ?

Séparez développement, préproduction et production, avec des clés et des journaux distincts — sur OVHcloud ou Scaleway en région Paris, vous y gagnez aussi en latence. Minimisez les données personnelles conservées dans vos logs : CaptchaAI n'a besoin que du sitekey et de l'URL de page.

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

Adoptez une approche méthodique et reproductible pour vos workflows CAPTCHA. – Obtenez votre clé CaptchaAI.