Résoudre les CAPTCHAs avec BullMQ et Node.js

Périmètre sûr : ce guide s'applique uniquement à vos propres applications, à vos environnements de QA, de préproduction ou de production, ou à des systèmes pour lesquels vous détenez une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni le contournement de protections.

Pour résoudre des CAPTCHAs de façon fiable dans une file BullMQ, isolez chaque résolution dans un job dédié, appelez l'API CaptchaAI depuis le worker, puis vérifiez le token côté backend avant toute action métier. BullMQ, la file Redis de référence pour Node.js, apporte les retrys, la concurrence contrôlée et la reprise sur incident qu'un appel CAPTCHA exige.

Pourquoi passer par une file d'attente

Un appel CAPTCHA direct casse dès qu'il tourne sans surveillance : timeout réseau, pic de charge, changement de famille de CAPTCHA. Derrière BullMQ, la résolution est découplée de la demande : le job encaisse les latences, applique un backoff exponentiel borné, et expose une file dont la taille signale un incident. Un job échoué se rejoue seul, sans relancer le workflow.

Préparer l'environnement

Avant d'écrire le worker, validez ces prérequis :

• Instance Redis joignable par le worker, dédiée à la QA et isolée de la production.
• Clé CaptchaAI dans un secret CI ou un coffre, jamais dans le code source.
• Worker BullMQ et Redis dans la même région — par exemple eu-west-3 à Paris chez OVHcloud ou Scaleway — pour ne pas ajouter de latence réseau.

Encapsuler l'appel à CaptchaAI

Isolez l'appel dans une fonction réutilisable qui prend la sitekey et l'URL de votre page et renvoie un identifiant de tâche. L'exemple ci-dessous crée une tâche Turnstile ; le même contrat vaut pour les autres familles en changeant le type de tâche.

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;
}

Câbler le worker BullMQ

Assemblez le Worker autour de la fonction ci-dessus, un job par défi :

1. Créez la tâche avec la sitekey et l'URL, puis récupérez l'identifiant renvoyé.
2. Interrogez le résultat à intervalle régulier, avec un plafond ferme par job.
3. Renvoyez le token comme valeur de sortie, consommée par l'étape suivante via l'événement completed.
4. Alignez la concurrency sur vos threads CaptchaAI : la facturation est par thread simultané avec résolutions illimitées, donc un plan BASIC ($15/mois, 5 threads) traite cinq résolutions en parallèle.

Vérifier le token côté backend

Le token renvoyé doit être validé par votre backend avant toute opération métier : cette étape empêche qu'une requête soit acceptée sur la base d'un token périmé ou contrefait. Appliquez-le toujours dans la même session que celle du défi — même contexte de navigateur, même cookie jar. Une session dépareillée est la première cause de rejet après résolution.

Observabilité et journalisation

Instrumentez chaque job : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file BullMQ. Ces signaux distinguent deux mesures souvent confondues, la réussite de la résolution et celle du workflow complet. Côté conformité, minimisez les données personnelles dans les logs — ni cookies, ni identifiants bruts — au titre du RGPD.

Dépannage

Liste de contrôle avant la mise en production

• Périmètre limité à vos propres applications ou à des sources autorisées.
• Clé CaptchaAI dans un secret CI ou un coffre, jamais dans le code source.
• Concurrence du worker alignée sur votre allocation de threads.
• Durées d'appel et codes retour tracés pour chaque job.
• Retry idempotent avec backoff exponentiel borné sur les erreurs transitoires.
• Journaux conformes au RGPD, sans donnée personnelle.

FAQ

Comment aligner la concurrence BullMQ sur mes threads CaptchaAI ?

Réglez l'option concurrency du worker sur le nombre de threads de votre plan. La facturation étant par thread simultané, une concurrence supérieure remplit la file sans accélérer les résolutions.

Que faire si le token est refusé après résolution ?

Vérifiez qu'il est appliqué dans la session exacte ayant déclenché le défi, cookies compris, et qu'il n'a pas expiré. Si le rejet persiste, comparez la sitekey et l'URL réelles aux paramètres envoyés.

Comment rester conforme au RGPD lors de la journalisation ?

Ne journalisez que les métadonnées techniques utiles — durée, code retour, identifiant de tâche — et excluez toute donnée personnelle. Fixez une rétention courte.

Guides connexes

• Démarrage rapide CaptchaAI
• QA CAPTCHA en environnements autorisés
• Tester l'endpoint API sur vos formulaires
• Résolution CAPTCHA en CI
• Résoudre reCAPTCHA v2 via l'API

Fiabilisez vos workflows CAPTCHA avec une approche reproductible. – Obtenez votre clé CaptchaAI.