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 porte pas sur l'automatisation de sites tiers que vous ne contrôlez pas.
Bunny.net Edge Scripting exécute votre code JavaScript directement sur le réseau de périphérie, au plus près de l'utilisateur. Pour résoudre un CAPTCHA depuis cet environnement, la logique tient en trois temps : votre Edge Script appelle l'API CaptchaAI en HTTPS, récupère un token, puis le transmet au formulaire ou à la route protégée. Un Edge Script n'étant pas un serveur permanent — il démarre à froid et ne conserve aucun état entre deux invocations — la résolution doit rester asynchrone, bornée dans le temps et entièrement tracée. La vraie difficulté n'est pas de faire fonctionner ce flux une fois, mais de le rendre assez stable pour tourner sans surveillance.
Architecture de l'appel
Votre Edge Script joue le rôle d'orchestrateur : il collecte les paramètres attendus par le type de CAPTCHA visé (sitekey, URL de la page, action éventuelle), envoie la tâche à CaptchaAI, attend le token, puis poursuit le parcours protégé dans la même session que celle qui a déclenché le défi. Un token appliqué depuis un contexte différent est la première cause de rejet après résolution.
Gestion des secrets
La clé CaptchaAI ne vit jamais dans le dépôt. Stockez-la dans les variables d'environnement de votre Edge Script, ou dans un coffre (HashiCorp Vault, AWS Secrets Manager) que le pipeline injecte au déploiement ; le script la lit via process.env. Faites-la tourner régulièrement et cloisonnez les secrets par environnement.
Exemple : créer une tâche Turnstile
Voici l'appel côté serveur à écrire dans votre Edge Script pour soumettre un défi Cloudflare Turnstile :
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 identifiant de tâche que vous interrogez jusqu'à obtenir le token, après une temporisation initiale puis un polling plafonné. Ce contrat reste identique quel que soit le type de CAPTCHA : seul le champ type de la tâche change.
Observabilité et conformité
Instrumentez chaque appel pour tracer la durée d'obtention du token, le code retour HTTP et l'identifiant de tâche. Séparez les journaux par environnement et corrélez les identifiants à votre traçage distribué (par exemple OpenTelemetry) : vous rejouez ainsi un incident à partir d'un seul identifiant, et vous distinguez la réussite du solveur de celle du parcours complet. Si le flux traverse un formulaire qui collecte des données personnelles, minimisez ce que vous journalisez et vérifiez vos obligations RGPD. Côté latence, appeler un backend proche — une région comme eu-west-3 (Paris), un hébergement OVHcloud ou Scaleway — garde les allers-retours courts pour un public francophone.
Liste de contrôle avant 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 secret CI ou un coffre, jamais dans le code source.
- Une stratégie de retry idempotent, avec backoff exponentiel borné, gère les erreurs transitoires.
- Le token est appliqué dans la même session que celle qui a déclenché le défi.
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé copiée avec une espace parasite ou mauvais compte. | Recopiez la clé depuis le tableau de bord et stockez-la comme secret CI. |
ERROR_ZERO_BALANCE |
Solde du compte sous le minimum par tâche. | Rechargez le solde et ajoutez une alerte de seuil. |
ERROR_BAD_PARAMETERS |
Un paramètre requis est manquant ou mal formé. | Revalidez l'URL de la page et le sitekey contre le HTML réel. |
| Token refusé après résolution | Token appliqué dans une session différente de l'originale. | Gardez la résolution et l'envoi du formulaire dans le même contexte. |
FAQ
Bunny.net Edge Scripting peut-il appeler l'API CaptchaAI directement ?
Oui. Un Edge Script exécute du JavaScript côté serveur et émet une requête HTTPS vers l'API CaptchaAI comme n'importe quel client. Gardez l'appel asynchrone et borné dans le temps, et lisez la clé depuis les variables d'environnement.
Comment protéger ma clé API dans un Edge Script ?
Ne la codez jamais en dur. Injectez-la via une variable d'environnement ou un coffre au moment du déploiement, faites-la tourner régulièrement et cloisonnez les valeurs par environnement, pour qu'un secret de préproduction ne puisse jamais atteindre la production.
Quels types de CAPTCHA puis-je résoudre depuis l'edge ?
reCAPTCHA v2 et v3, Cloudflare Turnstile et Cloudflare Challenge, GeeTest v3, les CAPTCHA image/OCR et les grilles d'images ; CaptchaFox, Friendly Captcha et Lemin sont en bêta. hCaptcha et FunCaptcha (Arkose Labs) ne sont pas pris en charge.
La facturation change-t-elle si j'exécute la résolution à la périphérie ?
Non. Le modèle reste basé sur les threads, avec des résolutions illimitées par thread : l'endroit d'où part la requête n'entre pas en compte. Le plan BASIC ($15/mois, 5 threads) suffit à valider une intégration avant de monter en charge.
Guides connexes
- Démarrage rapide CaptchaAI
- QA CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- Intégration CAPTCHA en CI
- Résoudre reCAPTCHA v2 via API
Passez de la démonstration à une intégration reproductible et mesurable. – Obtenez votre clé CaptchaAI.
