Encapsuler CaptchaAI dans une Activity Temporal

Périmètre sûr : ce guide couvre 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 traite pas de l'automatisation de sites tiers ni de l'évasion d'anti-bot.

Une Activity est l'endroit exact où doit vivre un appel CaptchaAI dans Temporal : c'est la seule couche où le moteur peut appliquer un retry durable, un timeout et un heartbeat sans casser le déterminisme de votre Workflow. Le code de Workflow ne doit jamais faire d'appel réseau ; il orchestre, tandis que l'Activity résout le défi CAPTCHA et vous rend le token. Vous héritez alors de la reprise automatique après incident, d'un délai maximal par tentative et d'une trace complète dans l'interface Temporal.

Architecture : Workflow, Activity et worker

Trois composants se répartissent le travail :

• Workflow : orchestre la séquence métier, sans aucun appel réseau.
• Activity solveCaptcha : appelle CaptchaAI via HTTPS, récupère le token et l'injecte dans votre formulaire ou votre route d'API.
• worker : exécute concrètement l'Activity sur vos machines.

Déployez le worker au plus près de votre cible — OVHcloud ou Scaleway en région parisienne, ou AWS eu-west-3 — pour limiter la latence, et tracez chaque étape pour détecter les régressions.

Configurer 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 dans le code. Le worker la monte en variable d'environnement : une rotation de clé ne touche ni votre code ni l'historique Temporal.

Politique de retry et timeouts de l'Activity

Dimensionnez le StartToCloseTimeout sur la latence réelle : un CAPTCHA à token peut demander plusieurs secondes de polling avant d'aboutir. Configurez une RetryPolicy bornée — trois tentatives, backoff exponentiel, plafond à 30 secondes — plutôt que des retries infinis qui masquent un défaut et consomment votre solde. Pendant le polling long, émettez un heartbeat pour distinguer une Activity active d'une Activity figée, et gardez l'opération idempotente pour ne jamais soumettre deux fois la même tâche.

Exemple de code

Le contrat de l'Activity reste le même quel que soit le langage :

1. Capturez uniquement les paramètres attendus par le type de CAPTCHA (sitekey, URL de page, action, proxy éventuel).
2. Soumettez la tâche, puis interrogez le résultat jusqu'à obtention du token.
3. Appliquez le token dans la session qui a déclenché le défi.

Exemple d'appel HTTP côté serveur, dans votre propre worker :

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

Observabilité et journalisation

Instrumentez chaque appel CAPTCHA pour obtenir des métriques exploitables : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente interne. La facturation CaptchaAI repose sur les threads concurrents, avec des résolutions illimitées par thread — à partir de BASIC ($15/mois, 5 threads) — ce qui garde le coût par résolution stable tant que vous évitez les boucles de retry.

Séparez les journaux par environnement et corrélez les identifiants à votre traçage distribué (OpenTelemetry) pour rejouer un scénario complet à partir d'un seul identifiant. Si vos journaux capturent des données de formulaire, minimisez les données personnelles conservées et vérifiez vos obligations RGPD.

Points de contrôle avant la mise en production

Passez cette grille en revue lors de la revue de code, avant de fusionner l'intégration. Chaque ligne correspond à une panne que des équipes rencontrent réellement.

Dépannage

La plupart des tickets sur ce type d'intégration se ramènent à quelques codes d'erreur. Chacun se corrige sans quitter votre éditeur.

FAQ

Pourquoi ne pas appeler CaptchaAI directement dans le Workflow ?

Parce que le code de Workflow doit rester déterministe : Temporal le rejoue pour reconstruire son état, et un appel réseau y produirait des résultats incohérents. Cette opération à effet de bord a sa place dans une Activity, où le moteur peut la retenter, la chronométrer et la tracer.

Quelle politique de retry configurer pour l'Activity ?

Bornez à trois tentatives avec un backoff exponentiel plafonné à 30 secondes, via la RetryPolicy plutôt qu'une boucle maison. Tracez chaque échec avec son identifiant de tâche ; si l'erreur persiste, vérifiez le réseau (DNS, certificats) et le solde de votre clé.

Comment éviter que le polling dépasse le timeout de l'Activity ?

Émettez un heartbeat à chaque itération de polling : Temporal sait ainsi que l'Activity progresse et n'applique pas son timeout prématurément. Réglez le StartToCloseTimeout au-dessus de la durée de résolution attendue.

CaptchaAI prend-il en charge tous les types de mon workflow ?

CaptchaAI expose une API unique pour reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, ainsi que les CAPTCHA image/OCR et en grille. Vous changez le type de tâche sans réécrire l'Activity ni le Workflow.

Guides connexes

• Le guide de démarrage rapide CaptchaAI
• Faire de la QA CAPTCHA en environnements autorisés
• Tester votre endpoint API sur vos formulaires
• Intégrer la résolution CAPTCHA dans votre CI
• Résoudre reCAPTCHA v2 via l'API

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