Appeler CaptchaAI depuis un job Defer.run

Périmètre sûr : ce guide s'applique exclusivement à vos propres applications ou à des systèmes pour lesquels 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 job Defer.run qui doit franchir une étape protégée par un CAPTCHA a besoin de trois choses : une clé API isolée du code, un appel à CaptchaAI observable de bout en bout, et une gestion des erreurs qui ne bloque pas la file d'attente. Ce guide montre comment câbler ces trois éléments dans un job planifié qui tourne sans surveillance, en CI comme en production, sans se contenter d'une démo qui ne marche qu'une fois.

Comment se déroule un appel CAPTCHA dans un job Defer.run

Le principe est le même quel que soit le type de défi : votre worker soumet une tâche à CaptchaAI via HTTPS, interroge le résultat jusqu'au token, puis l'injecte dans le formulaire ou la route d'API qui a déclenché le défi. Tracer chaque étape rend les régressions visibles dès la montée de version suivante. Le déroulé tient en cinq étapes :

1. Ne capturez que les paramètres attendus. Ne gardez que ce que le défi exige (sitekey, URL de la page, action, proxy éventuel) ; stocker davantage crée de fausses pistes de débogage.
2. Soumettez la tâche à l'API (createTask) et vérifiez le statut de la réponse. Tout état inattendu est une erreur : journalisez la réponse et remontez-la vers votre supervision.
3. Interrogez le résultat (getTaskResult). Patientez une quinzaine de secondes avant la première interrogation, puis interrogez toutes les 5 secondes, avec un plafond de 120 secondes par tâche.
4. Injectez le token dans la même session que celle qui a déclenché le défi : même navigateur, même client HTTP, mêmes cookies. Le champ dépend du type (par exemple cf-turnstile-response pour Cloudflare Turnstile). Une session dépareillée est la première cause de rejet après résolution.
5. Mesurez la latence, les retries et l'acceptation en aval. Réussite de la résolution et réussite du workflow sont deux métriques distinctes : suivez les deux.

Isoler la clé API dans un job planifié

• La clé CaptchaAI ne vit jamais dans le code source : stockez-la dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou un secret d'intégration continue.
• Le déploiement la monte en variable d'environnement au runtime, jamais en clair dans un dépôt, une image ou un log.
• Un job Defer.run sur Scaleway, OVHcloud ou en région AWS eu-west-3 (Paris) récupère ainsi la clé au démarrage.

Exemple : soumettre une tâche Turnstile

Voici un appel HTTP côté serveur, à l'intérieur de votre propre service, qui crée une tâche Turnstile et renvoie son identifiant :

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

L'identifiant renvoyé alimente la boucle d'interrogation. Le contrat createTask / getTaskResult étant identique pour tous les types, la même logique se transpose vers Go, Ruby, Java ou tout autre écosystème HTTP.

Observabilité et journalisation

Ce qui n'est pas mesuré ne peut pas être défendu. Instrumentez chaque appel CAPTCHA pour alimenter vos tableaux de bord existants et repérer une régression avant vos utilisateurs. Les signaux à capturer :

• la durée totale d'obtention du token ;
• le code retour HTTP et l'identifiant de tâche ;
• la taille de la file d'attente interne ;
• l'écart entre résolution réussie et acceptation en aval.

Séparez les journaux par environnement (développement, préproduction, production) et corrélez les identifiants avec votre traçage distribué, par exemple via OpenTelemetry, pour rejouer un scénario complet à partir d'un identifiant unique. Côté conformité, appliquez le principe de minimisation du RGPD : pas de données personnelles là où un identifiant de tâche suffit. Ce dernier écart est le plus révélateur : c'est lui qui trahit un token injecté dans la mauvaise session.

Dépannage

Les erreurs ci-dessous couvrent l'essentiel des tickets sur ce type d'intégration ; chacune se corrige en une ligne.

Liste de contrôle avant la mise en production

• Le périmètre reste limité à vos propres applications ou à des sources autorisées.
• La clé CaptchaAI est stockée dans un coffre ou un secret CI, jamais en clair dans le dépôt.
• Le code n'envoie que les paramètres réellement attendus par le défi.
• Le token est injecté dans la même session que celle qui a déclenché le défi.
• Une stratégie de retry idempotent avec backoff exponentiel borné est en place (trois tentatives, plafond à 30 secondes).
• La latence, les codes retour et l'acceptation en aval sont tracés pour chaque exécution.
• Les tests d'intégration sont rejouables depuis votre intégration continue.

FAQ

Trois questions reviennent une fois l'intégration en place.

Faut-il résoudre le CAPTCHA dans le même job Defer.run que la soumission du formulaire ?

Oui, dans la même session logique : le token doit être injecté par le contexte qui a déclenché le défi (même client HTTP, mêmes cookies). Si vous éclatez résolution et soumission en deux jobs, transmettez explicitement le contexte, sinon le token sera refusé.

Où stocker la clé API CaptchaAI dans un job planifié ?

Dans un coffre (Vault, AWS Secrets Manager, Azure Key Vault) ou un secret d'intégration continue, monté en variable d'environnement au runtime. Un job planifié doit pouvoir renouveler la clé sans redéploiement du code.

Quel plan CaptchaAI convient à un worker qui tourne en continu ?

Cela dépend de votre concurrence, pas de votre nombre de résolutions. La facturation est au thread, avec résolutions illimitées : un worker léger tient sur BASIC ($15/mois, 5 threads, facturé en dollars US), et vous montez en threads quand plusieurs tâches s'exécutent en parallèle. Le vrai poste de coût, ce sont les boucles de mauvais paramètres qui saturent vos threads — plafonnez les retries avant de monter de plan.

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

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