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 le contournement de protections, ni l'évasion d'anti-bot.
Une fonction Inngest s'exécute sans surveillance, se rejoue après un échec et découpe votre logique en steps durables. C'est précisément le contexte où un appel à l'API CaptchaAI doit rester prévisible : latence maîtrisée, échecs propres et token appliqué dans la bonne session. Ce guide montre comment structurer cet appel pour qu'il tienne en production, pas seulement lors d'une première démo.
Pourquoi une fonction Inngest change la donne pour la résolution de CAPTCHA
La résolution d'un CAPTCHA est un appel d'entrée/sortie à latence variable : vous soumettez une tâche, patientez, puis récupérez un token. Placer ce travail dans une fonction Inngest en arrière-plan vous apporte trois atouts concrets.
D'abord, l'exécution durable : chaque step est mémorisé, et si le processus redémarre, Inngest reprend là où il en était. Ensuite, le retry intégré : une erreur transitoire de l'API n'exige aucune boucle maison, la plateforme relance le step avec un backoff. Enfin, l'isolation par step : l'appel à CaptchaAI, l'application du token et la vérification en aval deviennent des unités traçables séparément. Vous savez lequel a échoué sans démêler une fonction monolithique.
Architecture : un step Inngest dédié à la résolution du CAPTCHA
Le schéma se lit en cinq minutes. Un événement déclenche votre fonction, puis trois steps s'enchaînent :
- Résoudre. Un premier step, par exemple
step.run("resoudre-captcha"), appelle CaptchaAI en HTTPS et renvoie le token. - Appliquer. Un second step injecte ce token dans la même session que celle qui a déclenché le défi — même contexte de navigateur, même client HTTP, même cookie jar.
- Vérifier. Un troisième step contrôle l'acceptation en aval et enregistre le résultat.
Ce découpage évite le piège le plus courant : un token valide rejeté parce qu'appliqué dans une autre session. En isolant la résolution dans son propre step, vous rendez le retry idempotent : le rejouer ne casse rien, puisqu'il ne produit qu'un token.
Isoler la clé API et les secrets
La clé CaptchaAI ne vit jamais dans le code source. Stockez-la dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret CI, puis montez-la en variable d'environnement à l'exécution. Si vos workers tournent sur Scaleway ou OVHcloud, utilisez le gestionnaire de secrets de l'hébergeur plutôt qu'un fichier .env déployé à la main.
Côté conformité, appliquez le principe de minimisation cher au RGPD : ne journalisez ni la clé, ni les données personnelles qui transitent par le formulaire protégé. Tracez l'identifiant de tâche, pas le contenu soumis.
Exemple de code
Voici un appel HTTP côté serveur, tel que vous l'écririez dans un step Inngest de votre service :
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;
}
Enveloppez cet appel dans un step.run(...) : Inngest gère alors le retry et la reprise, pendant que votre code reste concentré sur le contrat soumission/résultat.
Observabilité et journalisation
Les métriques à instrumenter
Quel que soit le langage, instrumentez les appels CAPTCHA pour obtenir des métriques exploitables qui alimentent vos tableaux de bord de QA et vos alertes : durée totale d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente interne.
Corréler les journaux et distinguer les taux
Séparez les journaux par environnement et corrélez chaque identifiant à votre traçage distribué (OpenTelemetry, par exemple) : vous rejouez un scénario complet depuis un seul identifiant. Distinguez surtout deux métriques que l'on confond : le taux de réussite de la résolution et le taux d'acceptation en aval. Un token résolu n'est pas un workflow réussi ; surveillez l'écart et alertez dessus.
Liste de contrôle avant la mise en production
- Le périmètre est strictement limité à vos propres applications ou à des sources autorisées.
- La clé CaptchaAI est stockée dans un coffre ou un secret CI, jamais dans le code source.
- Chaque appel de résolution vit dans son propre step, rejouable sans effet de bord.
- Le token est appliqué dans la même session que celle qui a déclenché le défi.
- Les durées d'appel et les codes retour sont tracés pour chaque exécution.
- Le budget de retry est borné (par exemple trois tentatives, backoff exponentiel, plafond à 30 s).
- Les tests sont reproductibles depuis votre intégration continue.
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
| Token refusé après une résolution réussie | Token appliqué dans une session différente de celle du défi. | Gardez la résolution et la soumission dans le même contexte d'exécution. |
| Le step de résolution boucle sur les retries | Erreur transitoire non bornée ou paramètres erronés. | Bornez le budget de retry et validez le sitekey et l'URL avant l'appel. |
| Latence d'obtention du token en hausse | File saturée ou threads insuffisants pour votre parallélisme. | Surveillez la taille de la file et ajustez le nombre de threads du plan. |
FAQ
Faut-il gérer soi-même le retry, ou Inngest s'en charge-t-il ?
Inngest relance automatiquement un step en échec avec un backoff. Vous n'avez donc pas besoin d'écrire votre propre boucle : bornez le nombre de tentatives dans la configuration de la fonction et rendez le step de résolution idempotent. Réservez une logique manuelle aux cas où vous visez un comportement différent de la plateforme.
CaptchaAI prend-il en charge tous les types de CAPTCHA depuis une fonction Inngest ?
L'API expose une seule interface pour reCAPTCHA v2 et v3, Cloudflare Turnstile et Cloudflare Challenge, GeeTest v3, ainsi que les CAPTCHA image/OCR, en grille et BLS. CaptchaFox, Friendly Captcha et Lemin sont disponibles en bêta. En revanche, hCaptcha et FunCaptcha (Arkose Labs) ne sont pas pris en charge, et GeeTest v4 est annoncé comme à venir.
Comment s'assurer que le token est appliqué dans la bonne session ?
Gardez la résolution et la soumission du formulaire dans le même contexte de navigateur ou le même client HTTP, avec le même cookie jar. Passer le token à une session distincte est la cause la plus fréquente de rejet après une résolution réussie. Dans Inngest, faites transiter le token entre deux steps qui partagent le même contexte d'exécution.
Comment le coût évolue-t-il à grande échelle ?
La facturation de CaptchaAI repose sur les threads, pas sur le nombre de résolutions : chaque plan inclut des résolutions illimitées par thread. L'offre BASIC ($15/mois, 5 threads) suffit à la plupart des intégrations Inngest ; vous montez en threads quand votre parallélisme l'exige. Les vrais postes de surcoût sont les boucles à paramètres erronés et les tempêtes de retry, couverts par la liste de contrôle ci-dessus.
Guides connexes
- le guide de démarrage rapide CaptchaAI
- la résolution de CAPTCHA en environnement de test autorisé
- tester l'endpoint de l'API sur vos formulaires
- intégrer la résolution de CAPTCHA à votre CI
- résoudre reCAPTCHA v2 via l'API
Structurez vos appels CAPTCHA autour de steps durables et mesurables. – Obtenez votre clé CaptchaAI.
