Périmètre sûr : ce guide s'applique uniquement à vos propres applications Phoenix, à 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.
Phoenix ne fournit aucun client de résolution CAPTCHA intégré : pour résoudre un CAPTCHA dans une application Elixir Phoenix, vous appelez l'API CaptchaAI en HTTP depuis un module Elixir, récupérez un token, puis l'injectez dans le formulaire ou la route protégée. Le reste relève de l'ingénierie Elixir habituelle.
L'objectif n'est pas de faire fonctionner le flux une fois dans iex, mais de le rendre assez stable pour tourner sans surveillance dans un GenServer, une tâche planifiée ou un pipeline CI, à travers les déploiements et les aléas réseau.
Comment une application Phoenix appelle CaptchaAI
Un module dédié — par exemple un client encapsulé dans un GenServer ou une Task supervisée — envoie la requête à CaptchaAI via HTTPS, attend le résultat, puis renvoie le token au contexte appelant. Réutilisez le client HTTP déjà présent dans votre projet (Req, Finch, Tesla ou HTTPoison).
Vos contrôleurs et vues LiveView ne parlent jamais directement à l'API : ils demandent un token à votre client interne, qui gère l'envoi, l'interrogation et les erreurs. Cette frontière de module facilite le test.
Où stocker la clé API dans un projet Phoenix
La clé CaptchaAI ne vit jamais dans le code source. Chargez-la à l'exécution dans config/runtime.exs via System.get_env/1, pour que la même image de déploiement serve tous les environnements : un .env ignoré par Git en développement, un secret de pipeline en CI, un coffre (HashiCorp Vault, AWS Secrets Manager) en production.
Côté RGPD, le token n'est pas une donnée personnelle, mais les journaux qui l'entourent peuvent l'être : limitez ce que vous consignez avant d'archiver des requêtes complètes.
La boucle d'envoi et d'interrogation du résultat
Le contrat est le même pour toutes les familles : soumettre une tâche, recevoir un identifiant, interroger le résultat jusqu'au token.
- Capturez uniquement les paramètres attendus (sitekey, URL de la page, action, proxy éventuel). En stocker davantage crée de fausses pistes de débogage.
- Envoyez la tâche, puis traitez tout statut d'échec comme une erreur : journalisez la réponse et remontez-la à votre supervision.
- Interrogez le résultat après un premier délai, puis à intervalle régulier, avec un plafond strict par tâche.
- Appliquez le token dans la même session que celle qui a déclenché le défi — première cause de rejet après résolution.
Exemple : créer une tâche Turnstile
Appel HTTP côté serveur, dans votre propre service. Adaptez le type et les paramètres à la page que vous contrôlez :
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 logique se transpose telle quelle en Elixir. CaptchaAI expose une API unique sur reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, l'image/OCR et les grilles : vous changez le type de tâche, la boucle reste identique.
Injecter le token CAPTCHA dans la même session Phoenix
Une tâche résolue et un workflow réussi sont deux métriques différentes. Le token doit être appliqué dans le contexte qui poursuit le parcours : le même contrôleur, le même socket LiveView, le même client HTTP avec ses cookies. Un token valide rejeté « sans raison » vient presque toujours d'un changement de session entre les deux étapes.
Observabilité avec Telemetry et logs
Instrumentez chaque appel CAPTCHA avec :telemetry : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente. Ces événements alimentent vos tableaux de bord de QA et vos alertes.
Séparez les journaux par environnement et attachez au Logger les métadonnées corrélées à votre traçage distribué (OpenTelemetry). Les métriques à suivre en continu : latence de résolution, taux de réussite du solveur et taux d'acceptation en aval — surveillez surtout l'écart entre ces deux derniers.
Retry et erreurs transitoires de l'API
Les délais d'expiration et les coupures réseau font partie du fonctionnement normal. Encadrez-les avec un retry idempotent et un backoff exponentiel borné : par exemple trois tentatives, doublement du délai à chaque essai, plafond à 30 secondes. Des tentatives infinies masquent les vrais défauts et consomment votre solde. Journalisez chaque échec terminal avec son identifiant de tâche ; si l'erreur persiste, vérifiez le réseau et les quotas de votre clé.
Liste de contrôle avant la mise en production
- Le périmètre est limité à vos propres applications Phoenix ou à des sources autorisées.
- La clé CaptchaAI est chargée depuis un coffre ou un secret CI, jamais dans le code.
- Seuls les paramètres attendus par la famille de CAPTCHA sont capturés.
- Les durées d'appel et les codes retour sont tracés via Telemetry.
- Un retry idempotent avec backoff borné couvre les erreurs transitoires.
- Le token est appliqué dans la même session que celle du défi.
- Les tests d'intégration ExUnit sont rejouables depuis la CI.
Dépannage des erreurs CAPTCHA courantes
| 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 inférieur au minimum requis par tâche. | Rechargez 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. |
ERROR_CAPTCHA_UNSOLVABLE |
Défi non résolu de façon fiable. | Réessayez une fois ; sinon, capturez le HTML et ouvrez un ticket. |
| Token refusé après résolution | Session différente de celle du défi. | Gardez résolution et soumission dans le même contexte. |
FAQ
Quel client HTTP utiliser pour appeler CaptchaAI depuis Elixir ?
Celui que votre projet utilise déjà : Req, Finch, Tesla ou HTTPoison. L'API est un simple échange HTTP/JSON ; n'ajoutez pas de dépendance pour ce seul appel.
Où placer la clé API dans une application Phoenix ?
Dans config/runtime.exs, chargée via System.get_env/1 et alimentée par un coffre ou un secret CI. La même image de déploiement sert alors tous les environnements, sans que la clé apparaisse dans un fichier versionné.
Comment appliquer le token dans un formulaire Phoenix LiveView ?
Demandez le token à votre client interne, puis injectez-le dans le socket LiveView ou le contrôleur, sans changer de session. Le champ attendu dépend de la famille de CAPTCHA (g-recaptcha-response pour reCAPTCHA, cf-turnstile-response pour Turnstile).
CaptchaAI prend-il en charge hCaptcha pour mon application Phoenix ?
Non — hCaptcha et FunCaptcha (Arkose Labs) ne sont pas pris en charge, et GeeTest v4 est annoncé comme à venir. CaptchaAI couvre reCAPTCHA v2 et v3, Turnstile et Challenge, GeeTest v3, l'image/OCR et les grilles, avec CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta).
Guides connexes
- Le démarrage rapide CaptchaAI
- La QA 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 dans Phoenix avec une approche méthodique et reproductible. – Obtenez votre clé CaptchaAI.
