Périmètre sûr : Ce guide couvre uniquement vos propres applications et vos environnements de QA, de préproduction ou de production, ainsi que les systèmes pour lesquels vous détenez une autorisation écrite. Il ne porte ni sur l'automatisation de sites tiers, ni sur la neutralisation de protections anti-bot.
Pour résoudre des CAPTCHA depuis un workflow Firefox automatisé, la voie la plus fiable n'est pas une extension à cliquer mais l'API CaptchaAI. Une extension suppose une fenêtre visible et une action humaine ; un job en CI, dans un cron ou derrière une file d'attente doit s'exécuter sans surveillance. L'appel API vous donne un contrat HTTP reproductible, piloté depuis Firefox comme depuis n'importe quel client, que vous mesurez et rejouez.
Pourquoi l'API plutôt qu'une extension sur Firefox
La plupart des équipes arrivent ici quand leur automatisation Firefox fonctionne dans un notebook, puis casse dès qu'elle s'exécute sans opérateur. Une extension ne clique pas toute seule dans un pipeline headless ; l'API, si — et elle tient à travers les déploiements, les aléas réseau et les changements de type sur la page.
Ce que l'API CaptchaAI prend en charge
Une seule interface couvre toute la famille de types, avec latence prévisible et facturation par thread.
| Famille de CAPTCHA | Prise en charge |
|---|---|
| reCAPTCHA v2 et v3 | ✅ |
| Cloudflare Turnstile et Challenge | ✅ |
| GeeTest v3 | ✅ |
| Image / OCR et grille d'images | ✅ |
| CaptchaFox, Friendly Captcha, Lemin | ✅ bêta |
| hCaptcha, FunCaptcha | ❌ non pris en charge |
| GeeTest v4 | À venir |
Le workflow en pratique
Le déroulé reste le même quel que soit votre langage, du poste local au pipeline CI :
- Isolez l'environnement : QA séparée de la production, clé CaptchaAI en secret CI, endpoints internes ouverts aux tests.
- Capturez les seuls paramètres utiles : sitekey, URL de la page, action et proxy éventuel, comparés au HTML réel.
- Encapsulez l'appel dans une fonction réutilisable qui renvoie un token et trace la durée et le code retour.
- Interrogez le résultat : attendez une quinzaine de secondes, puis interrogez toutes les 5 secondes, avec un plafond ferme par tâche.
- Appliquez le token dans la même session que celle qui a déclenché le défi.
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;
}
Vérifier le token côté backend
Le token doit être validé par votre propre backend avant toute opération métier : aucune requête ne doit être acceptée sur la foi d'un token périmé ou falsifié. Appliquez-le dans la même session que celle qui a déclenché le défi — même contexte Firefox, même client HTTP, même cookie jar. Une session dépareillée reste la première cause de rejet.
Journalisation, observabilité et RGPD
Instrumentez chaque appel : durée 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). Côté RGPD, ne journalisez aucune donnée personnelle inutile. Enfin, ne confondez pas la réussite du solveur avec celle du workflow de bout en bout.
Liste de contrôle avant la mise en production
| Contrôle | Pourquoi | Réglage |
|---|---|---|
| Périmètre autorisé | Rester dans vos droits | Vos apps ou sources autorisées |
| Clé en secret | Ne jamais exposer la clé | Secret CI ou coffre, jamais dans le code |
| Traçabilité | Diagnostiquer vite | Durée et code retour tracés à chaque appel |
| Retry borné | Absorber les erreurs transitoires | 3 tentatives, backoff exponentiel |
| Même session | Éviter les rejets de token | Même contexte pour résolution et envoi |
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
ERROR_WRONG_USER_KEY |
Clé mal copiée ou mauvais compte | Recopiez la clé, stockez-la en secret CI |
ERROR_PAGEURL |
URL ou paramètre manquant | Revalidez l'URL et le sitekey face au HTML réel |
| Token refusé après résolution | Session différente de celle du défi | Même contexte de navigateur ou HTTP |
FAQ
Existe-t-il une extension CaptchaAI pour Firefox ?
Pour un usage manuel, une extension a du sens. Mais dès que votre workflow Firefox tourne sans opérateur, l'API est le bon outil : aucun clic, une intégration à tout client HTTP.
L'API fonctionne-t-elle en mode headless et en CI ?
Oui. L'appel se réduit à un échange HTTP, sans fenêtre visible, et s'exécute à l'identique en local, en headless et en CI.
Comment gérer une erreur transitoire de l'API ?
Mettez en place un retry avec backoff exponentiel borné — trois tentatives, délai doublé, plafond à 30 secondes — et tracez chaque échec avec son identifiant de tâche. Si l'erreur persiste, contrôlez la configuration réseau et les quotas de votre clé.
Guides connexes
- Démarrage rapide CaptchaAI
- Résolution de CAPTCHA en QA sur environnements autorisés
- Tester l'endpoint API sur vos formulaires
- Intégrer la résolution de CAPTCHA à votre CI
- Résoudre reCAPTCHA v2 via l'API
Structurez vos workflows CAPTCHA de façon méthodique et reproductible. – Obtenez votre clé CaptchaAI.
