Les hooks JavaScript de PocketBase s'exécutent côté serveur, à l'intérieur de votre backend : c'est exactement là que vous devez appeler CaptchaAI pour résoudre un défi CAPTCHA sans jamais exposer votre clé API au navigateur. Vous récupérez un token, l'injectez dans la requête protégée, et votre logique métier reprend son cours. Ce guide montre comment câbler cet appel proprement, pour qu'il tienne en production — dans un job planifié, une file interne ou une CI — et pas seulement le temps d'une démonstration.
Périmètre sûr : ce guide s'applique 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 couvre ni l'automatisation de sites tiers, ni l'évasion de protections anti-bot sur des services que vous ne contrôlez pas.
Où placer l'appel dans un hook PocketBase
Dans PocketBase, les hooks vivent dans le dossier pb_hooks et se déclenchent sur des évènements serveur (onRecordBeforeCreateRequest, onRecordAfterUpdateSuccess, et ainsi de suite). Placez l'appel CaptchaAI dans le hook qui précède l'opération protégée : ce composant interne appelle le service via HTTPS, obtient le token avant que l'enregistrement ne soit écrit, puis rejette la requête si la résolution échoue. Tracez chaque étape : c'est ce qui révèle une régression lors d'une montée de version plutôt qu'en production.
Le flux : soumettre la tâche puis interroger le résultat
La mécanique est identique pour tout type de CAPTCHA et se porte dans tout langage capable de faire du HTTP. Gardez cet ordre :
- Capturez uniquement les paramètres utiles (sitekey, URL de page, action, proxy éventuel). En stocker davantage crée de fausses pistes de débogage.
- Soumettez la tâche ; le service renvoie un identifiant. Traitez tout statut d'erreur comme un échec, journalisez la réponse et remontez-la à votre supervision.
- Interrogez le résultat régulièrement : quelques secondes d'attente, puis toutes les 5 secondes, avec un plafond strict par tâche.
- Appliquez 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 cookie jar. Une session dépareillée est la première cause de rejet.
- Mesurez la latence, les retries et l'acceptation en aval : réussite du solveur et réussite du workflow sont deux métriques distinctes.
Configuration des secrets
La clé CaptchaAI ne doit jamais apparaître dans le code source. Elle vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret de CI, et le déploiement la monte en variable d'environnement au runtime. Sur OVHcloud ou Scaleway, exploitez le gestionnaire de secrets natif plutôt qu'un fichier .env versionné.
Exemple d'appel côté serveur
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;
}
L'appel crée la tâche et renvoie un taskId ; il vous reste à interroger le résultat, puis à injecter le token dans la requête que votre hook laisse passer. Le même contrat submit/poll vaut pour les autres familles prises en charge (reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile, GeeTest v3, image/OCR) : vous changez le type de tâche et gardez la boucle.
Observabilité et journalisation
Instrumentez chaque appel CAPTCHA pour obtenir des signaux exploitables : durée totale d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file interne. Séparez les journaux par environnement et corrélez les identifiants à votre traçage distribué (OpenTelemetry, par exemple) pour rejouer un scénario complet depuis un identifiant unique. Côté conformité, minimisez les données personnelles écrites dans les logs et vérifiez vos obligations RGPD avant de conserver des payloads bruts.
Indicateurs à suivre
Câblez quelques indicateurs dans le tableau de bord que vous utilisez déjà : latence de première résolution (p50), taux de réussite du solveur, acceptation de bout en bout après injection et coût par résolution acceptée. Les valeurs varient selon l'environnement, le volume et le moment de la journée ; visez une réussite et une acceptation stables, de l'ordre de 95 % par famille, et surveillez l'écart entre les deux.
CaptchaAI facture au thread concurrent, pas au solve : le forfait BASIC ($15/mois, 5 threads) inclut des résolutions illimitées par thread. Votre coût dépend donc de votre parallélisme, pas du volume brut ; ce sont surtout les mauvais paramètres et les retries répétés qui font grimper la facture.
Liste de contrôle avant 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.
- Les durées d'appel et les codes retour sont tracés pour chaque exécution.
- Une stratégie de retry idempotent, plafonnée à trois tentatives avec backoff exponentiel, est en place pour les erreurs transitoires.
- Le token est appliqué dans la même session que celle qui a déclenché le défi.
- Les tests sont rejouables et reproductibles depuis votre intégration continue.
Dépannage
Ces symptômes couvrent l'essentiel des tickets de support pour ce type d'intégration ; chaque ligne indique un correctif direct.
| Symptô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_ZERO_BALANCE |
Solde du compte sous le minimum par tâche. | Rechargez le solde et ajoutez une alerte de solde dans votre tableau de bord. |
ERROR_BAD_PARAMETERS |
Paramètre requis manquant ou mal formé. | Revalidez l'URL de page, le sitekey et les champs propres au solveur face au HTML réel. |
| Token refusé après résolution | Token appliqué dans une session différente de celle qui a déclenché le défi. | Gardez la résolution et l'envoi du formulaire dans le même contexte ou la même session HTTP. |
FAQ
Où placer l'appel CaptchaAI dans un hook PocketBase ?
Dans le hook qui précède l'opération protégée, par exemple onRecordBeforeCreateRequest. Vous obtenez le token avant l'écriture de l'enregistrement et rejetez la requête si la résolution échoue. L'appel part toujours du serveur (dossier pb_hooks), jamais du navigateur, pour que la clé API reste confidentielle.
Que faire si le token est refusé après la résolution ?
Vérifiez d'abord la cohérence de session : le token doit être appliqué dans le même contexte de navigateur ou client HTTP que celui qui a déclenché le défi. Contrôlez ensuite que le sitekey et l'URL de page envoyés correspondent au HTML réel. Un décalage sur l'un de ces éléments explique la plupart des rejets.
Ce guide couvre-t-il l'automatisation de sites tiers ?
Non. Tous les exemples portent sur vos propres applications ou sur des environnements de test pour lesquels vous détenez une autorisation écrite ; aucune technique d'évasion ou d'anti-détection n'est décrite. Si votre projet implique une source externe, validez d'abord les conditions d'utilisation et la base juridique avant toute automatisation.
Guides connexes
- Démarrage rapide CaptchaAI
- QA CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires web
- Intégrer la résolution CAPTCHA dans votre CI
- Résoudre reCAPTCHA v2 via l'API
Structurez vos workflows CAPTCHA avec une méthode reproductible et mesurable. — Obtenez votre clé CaptchaAI.
