Périmètre sûr : ce guide s'applique uniquement à vos propres applications et à vos environnements de QA, de préproduction ou de production, ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne couvre ni l'automatisation de sites tiers, ni l'évasion de protections anti-bot.
Dans une tâche Trigger.dev v3, CaptchaAI s'appelle comme n'importe quel service HTTP : la tâche crée une résolution, interroge le résultat, puis injecte le token dans la requête qui suivait. La vraie difficulté n'est pas le premier appel — il fonctionne en cinq minutes — mais de garder ce flux stable une fois qu'il tourne sans surveillance, à chaque déploiement et à chaque pic de charge. Voici une intégration lisible, instrumentée et exploitable en production.
Où CaptchaAI s'insère dans une tâche Trigger.dev v3
Trigger.dev v3 exécute votre logique sous forme de tâches durables, avec retries et contrôle de concurrence intégrés. La résolution d'un CAPTCHA y devient un appel réseau parmi d'autres : la tâche envoie la demande à CaptchaAI, attend le token, puis poursuit le workflow — soumission d'un formulaire, appel d'une route d'API interne ou écriture en base.
Comme CaptchaAI expose une seule API pour toutes les familles prises en charge (reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile, GeeTest v3, image et OCR), vous gardez la même boucle create/poll même si le défi affiché change.
Le flux recommandé : créer, interroger, injecter
La séquence reste identique quel que soit le type de CAPTCHA :
- Capturez uniquement les paramètres attendus (sitekey, URL de la page, action, proxy éventuel). Stocker davantage crée de fausses pistes de débogage.
- Créez la tâche de résolution via l'API CaptchaAI. Traitez tout statut inattendu comme une erreur : journalisez-la et alertez votre supervision.
- Interrogez le résultat. Attendez environ 15 s, puis interrogez toutes les 5 s avec un plafond strict de 120 s par tâche.
- Injectez le 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 jar de cookies. Un décalage de session est la première cause de token refusé.
- Mesurez la latence, les retries et l'acceptation en aval. La réussite de la résolution et la réussite du workflow sont deux métriques distinctes.
Gérer la clé API comme un secret
La clé CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret d'intégration continue, jamais dans le code source. Le déploiement la monte en variable d'environnement au runtime, et la tâche Trigger.dev la lit via process.env.
Prévoyez la rotation : régénérez la clé dans le tableau de bord et mettez à jour le secret sans redéployer. Sous RGPD, minimisez au passage les données personnelles qui transitent par la tâche.
Exemple de code
Exemple d'appel HTTP côté serveur, dans votre propre 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;
}
La fonction renvoie un taskId : la tâche interroge ensuite le résultat jusqu'au token, puis l'injecte dans la requête suivante. La logique se transpose vers tout écosystème HTTP.
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.
Séparez les journaux par environnement (développement, préproduction, production) et corrélez les identifiants à votre traçage distribué, par exemple via OpenTelemetry. Vous rejouez ainsi un scénario complet depuis un identifiant unique, ce qui accélère nettement le diagnostic.
Mesurer la réussite
Les chiffres ci-dessous reposent sur des mesures observées et des retours d'utilisateurs. Les résultats varient selon l'environnement, le volume et le moment de la journée.
| Indicateur | Cible | Ce qu'il révèle |
|---|---|---|
| Latence de première résolution (p50) | < 25 s (token), < 8 s (OCR image) | L'intégration est saine et n'attend pas de retries. |
| Latence de première résolution (p95) | < 60 s (token) | La traîne est maîtrisée et vos timeouts sont bien dimensionnés. |
| Taux de réussite du solveur | >= 95 % par famille | Vos paramètres sont corrects et le solveur correspond au défi réel. |
| Acceptation de bout en bout | >= 95 % après token | La vérification en aval accepte le token dans la même session. |
Côté facturation, CaptchaAI se paie par thread, avec des résolutions illimitées par thread — pas de coût par défi ni de surcoût par type. Le plan BASIC ($15/mois, 5 threads) suffit à valider une tâche Trigger.dev ; vous ajoutez des threads quand la concurrence augmente, sans toucher au code.
Dépannage
| Problème | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace parasite ou mauvais compte. | Recopiez la clé depuis le tableau de bord et stockez-la comme secret CI. |
ERROR_PAGEURL / ERROR_BAD_PARAMETERS |
Un paramètre requis est manquant ou mal formé. | Revalidez l'URL, le sitekey et les champs spécifiques face au HTML réel. |
| Token refusé après résolution | Token injecté dans une session différente de celle du défi. | Gardez la résolution et la soumission dans la même session HTTP. |
Liste de contrôle
- Le périmètre est strictement limité à vos propres applications ou à des sources autorisées.
- La clé CaptchaAI est stockée dans un secret CI ou un coffre, jamais dans le code source.
- Les durées d'appel et les codes retour sont tracés pour chaque exécution de tâche.
- Une stratégie de retry idempotent avec backoff exponentiel borné couvre les erreurs transitoires.
FAQ
Faut-il gérer les retries dans la tâche Trigger.dev ou côté appel CaptchaAI ?
Les deux, à des niveaux différents. Bornez le retry de l'appel CAPTCHA lui-même (trois tentatives, doublement du délai, plafond à 30 secondes) pour absorber une erreur réseau transitoire. Laissez ensuite le retry de Trigger.dev gérer les échecs de tâche, avec un identifiant journalisé contre les doublons.
Comment stocker la clé API dans un projet Trigger.dev v3 ?
Comme un secret d'environnement, jamais en clair dans le dépôt. Montez la clé au runtime et lisez-la via process.env. Utilisez un secret CI ou un coffre pour la rotation ; vérifiez qu'elle n'apparaît pas dans les journaux.
Que faire si le token est refusé après une résolution réussie ?
Vérifiez d'abord la session : le token doit être injecté dans le même contexte de navigateur ou client HTTP que celui qui a déclenché le défi. Un décalage de cookies ou d'en-têtes explique la plupart des refus. Contrôlez ensuite que le sitekey et l'URL correspondent à la page réelle.
Comment ce coût évolue-t-il quand le volume augmente ?
De façon linéaire avec les résolutions réussies, puisque la facturation est par thread avec résolutions illimitées. Les vrais gaspillages sont les boucles de paramètres erronés et les tempêtes de retries : la liste de contrôle ci-dessus les élimine.
Guides connexes
- Le démarrage rapide CaptchaAI
- Tester vos 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.
