Périmètre sûr : ce guide couvre uniquement vos propres applications, vos environnements de QA, de préproduction ou de production, et les systèmes pour lesquels vous détenez une autorisation écrite. Il ne traite pas de l'automatisation de sites tiers ni de l'évasion des systèmes anti-bot.
Pour résoudre un CAPTCHA depuis un Background Worker Render, votre processus appelle l'API CaptchaAI en sortie, récupère le token, puis l'injecte dans la session qui a déclenché le défi — sans jamais exposer de port HTTP entrant. Un Background Worker consomme des tâches depuis une file ou un planificateur : l'endroit idéal pour isoler cette logique et la rendre assez solide pour tourner seule.
Pourquoi confier la résolution CAPTCHA à un worker en arrière-plan
La résolution paraît triviale dans un script lancé à la main ; elle se complique dès qu'elle doit tourner en continu, avec une latence prévisible et des modes d'échec propres. Un worker dédié prend une tâche, appelle CaptchaAI, récupère le token et le passe à l'étape suivante. Il n'ouvre aucun port entrant — que des appels sortants en HTTPS —, ce qui réduit la surface exposée.
CaptchaAI expose une seule API sur toutes les familles prises en charge — reCAPTCHA v2 et v3, Cloudflare Turnstile et Cloudflare Challenge, GeeTest v3, CAPTCHA image/OCR et grilles d'images. Le worker reste donc simple quand la protection de la page évolue : vous changez le type de tâche, la boucle ne bouge pas.
Architecture d'un worker de résolution sur Render
Votre worker appelle CaptchaAI en HTTPS pour obtenir un token, puis l'injecte dans le formulaire ou la route d'API qui déclenche le défi. Tracez chaque étape — envoi, interrogation, acceptation en aval — pour rendre les régressions visibles quand une réponse change de forme.
Gardez la résolution dans un worker séparé pour l'échelonner à part. Le choix de la région se raisonne en latence : pour un public France, Belgique ou Suisse, une région européenne — chez OVHcloud, Scaleway, ou eu-west-3 (Paris) sur AWS — rapproche le worker de vos utilisateurs sans changer une ligne de code.
Sécuriser la clé API CaptchaAI dans les secrets Render
Ne mettez jamais la clé CaptchaAI dans le code source. Sur Render, déclarez-la comme variable d'environnement secrète du service ; en CI, passez par un coffre (Vault, AWS Secrets Manager ou Azure Key Vault). Le code la lit via process.env.CAPTCHAAI_KEY : un seul endroit à modifier lors d'une rotation.
Pour les équipes soumises au RGPD, limitez au passage les données personnelles présentes dans les journaux : un identifiant de tâche et un code retour suffisent au diagnostic — la même exigence de minimisation que la CNIL attend sur tout traitement.
Le cycle envoi/interrogation, étape par étape
Le contrat est identique quel que soit le langage : envoyez la tâche, interrogez le résultat, puis appliquez le token dans la session qui a déclenché le défi.
- Capturez uniquement les paramètres attendus par la famille de CAPTCHA (sitekey, URL de la page, action, proxy éventuel). En stocker plus crée de fausses pistes de débogage.
- Interrogez le résultat à intervalle régulier plutôt qu'en boucle serrée : 15 secondes d'attente initiale, puis toutes les 5 secondes, avec un plafond (120 secondes par tâche).
- Appliquez le token dans le même contexte navigateur ou client HTTP. Une session dépareillée cause le plus souvent un rejet.
Exemple Node.js : créer une tâche Turnstile
L'appel ci-dessous, côté serveur dans votre propre service, crée une tâche Turnstile et récupère 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;
}
La fonction renvoie un taskId ; interrogez ensuite le résultat avec cet identifiant jusqu'à obtenir le token, puis injectez-le dans le flux. Le worker traite plusieurs tâches en parallèle : CaptchaAI facture au thread simultané, avec des résolutions illimitées par thread. Le débit dépend donc de votre plan — de BASIC ($15/mois, 5 threads) à STANDARD ($30/mois, 15 threads) et au-delà — et non d'un coût à la résolution.
Journaliser et instrumenter le worker
Instrumentez chaque appel : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file. Corrélez chaque identifiant à votre traçage distribué (par exemple via OpenTelemetry) pour rejouer un scénario complet et raccourcir le diagnostic.
Réussite du solveur ou acceptation en aval : mesurez les deux
Une tâche résolue et un workflow réussi sont deux métriques distinctes. Le taux de réussite du solveur dit si vos paramètres correspondent au défi ; l'acceptation en aval dit si le token passe dans la bonne session. Fixez vos seuils de latence — médiane et p95 — sur vos mesures, et alertez sur l'écart entre les deux taux : il révèle une régression avant vos utilisateurs.
Checklist 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 en secret Render ou en coffre, jamais dans le dépôt.
- Les durées d'appel, codes retour et identifiants de tâche sont tracés à chaque exécution.
- Un retry idempotent avec backoff exponentiel borné couvre les erreurs transitoires (trois tentatives, plafond à 30 secondes).
- Les tests sont rejouables depuis votre CI, et vous suivez séparément la réussite du solveur et l'acceptation en aval.
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace parasite ou mauvais compte. | Recopiez la clé et stockez-la en secret Render. |
ERROR_ZERO_BALANCE |
Solde sous le minimum requis. | Créditez le compte et ajoutez une alerte de solde. |
ERROR_PAGEURL / ERROR_BAD_PARAMETERS |
Paramètre requis absent ou mal formé. | Revalidez l'URL et le sitekey face au HTML réel. |
CAPCHA_NOT_READY en boucle |
Résultat pas encore prêt côté service. | Continuez d'interroger jusqu'au plafond, sans raccourcir l'intervalle. |
| Token refusé après résolution | Token appliqué dans une autre session que celle du défi. | Gardez la résolution et l'envoi du formulaire dans le même contexte. |
FAQ
Pourquoi un Background Worker plutôt qu'un service web exposé ?
Un worker n'a besoin d'aucun port entrant : il consomme des tâches depuis une file et n'appelle CaptchaAI qu'en sortie. Vous réduisez la surface exposée et dimensionnez la résolution à part.
Comment stocker la clé API CaptchaAI en toute sécurité sur Render ?
Dans une variable d'environnement secrète du service, jamais dans le code. En CI, passez par un coffre (Vault, AWS Secrets Manager, Azure Key Vault) : un seul point à mettre à jour lors d'une rotation.
Quel plan CaptchaAI choisir pour un worker qui monte en charge ?
Le plan fixe le nombre de tâches simultanées, pas un quota de résolutions. BASIC ($15/mois, 5 threads) convient à un worker unique ; montez vers STANDARD ($30/mois, 15 threads) ou au-dessus quand plusieurs tâches tournent en parallèle.
Guides connexes
- Le guide de démarrage rapide CaptchaAI
- Tester la résolution en environnements QA autorisés
- Valider l'endpoint API sur vos formulaires web
- Intégrer la résolution de CAPTCHA dans votre CI
- Résoudre reCAPTCHA v2 via l'API
Déployez un worker de résolution CAPTCHA stable et mesurable, du premier appel jusqu'à la production. – Créez votre clé CaptchaAI.
