Migrer de l'extension 2Captcha vers l'extension CaptchaAI

Périmètre sûr : ce guide s'applique exclusivement à vos propres applications, à 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.

Migrer de l'extension 2Captcha vers l'extension CaptchaAI n'est pas un simple changement de case à cocher : vous remplacez un composant actif de votre pile d'automatisation. Traitée comme un workflow de navigateur reproductible — profil isolé, clé API centralisée, gestion explicite des tokens — la bascule se fait en une session et tient en production.

Ce qui change vraiment entre les deux extensions

Les deux extensions injectent un token de résolution dans la page ; les différences qui comptent sont ailleurs.

Là où beaucoup de services facturent chaque résolution, CaptchaAI facture par thread : les forfaits démarrent à BASIC ($15/mois, 5 threads), et le coût reste prévisible à volume soutenu.

La migration en cinq étapes

1. Préparez un environnement isolé. Séparez la QA de la production, stockez la clé CaptchaAI dans un coffre ou un secret d'intégration continue, et autorisez les requêtes de test sur vos endpoints internes.
2. Capturez uniquement les paramètres utiles. Relevez la sitekey, l'URL de page et, si besoin, le proxy attendus par le type de CAPTCHA ; en stocker davantage crée de fausses pistes de débogage.
3. Encapsulez l'appel au solveur. Une seule fonction qui prend la sitekey et l'URL, renvoie un token et trace la durée et le code retour : le jour où l'API évolue, vous n'avez qu'un endroit à corriger.
4. Appliquez le token dans la même session. Même contexte de navigateur, mêmes cookies que le défi d'origine — c'est la première cause de rejet après résolution.
5. Mesurez avant de généraliser. Tracez la latence, les retries et l'acceptation en aval avant d'étendre l'intégration.

Exemple : créer une tâche Turnstile en Node.js

La fonction ci-dessous envoie la tâche puis renvoie son identifiant ; il ne reste plus qu'à interroger le résultat avant d'injecter le token dans la page.

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;
}

Valider le token côté backend

Le token renvoyé par le solveur doit toujours être vérifié par votre propre backend avant la moindre opération métier. C'est cette vérification qui empêche qu'une requête soit acceptée sur la foi d'un token périmé, rejoué ou contrefait, ou validé côté client seul.

Instrumenter et journaliser vos appels

Instrumentez chaque appel CAPTCHA pour obtenir des métriques exploitables : durée d'obtention du token, code retour HTTP et identifiant de tâche. Séparez les journaux par environnement et corrélez les identifiants à votre traçage distribué (OpenTelemetry, par exemple). Côté conformité, appliquez le principe de minimisation du RGPD : ne journalisez pas de données personnelles superflues.

Dépannage

• ERROR_ZERO_BALANCE — solde sous le minimum par tâche ; rechargez et posez une alerte de solde.
• ERROR_WRONG_USER_KEY — clé copiée avec un espace ou mauvais compte ; recopiez-la depuis le tableau de bord.
• Token refusé après résolution — appliqué dans une autre session que le défi ; gardez la résolution et l'envoi dans le même contexte.

Checklist de migration

• Le périmètre reste limité à vos propres applications ou à des sources autorisées.
• La clé CaptchaAI vit dans un secret d'intégration continue ou un coffre, jamais dans le code.
• Chaque appel trace sa durée et son code retour.
• Une stratégie de retry idempotent couvre les erreurs transitoires.
• Les tests sont rejouables à l'identique depuis votre CI.

FAQ

Dois-je réécrire mon code pour migrer de 2Captcha vers CaptchaAI ?

Non, la logique reste la même : vous envoyez une tâche, vous interrogez le résultat, vous injectez le token. En pratique, vous mettez à jour la clé API, le domaine d'appel et le nom du profil chargé par l'extension. Si votre appel au solveur est déjà encapsulé, la migration se limite à ce point unique.

CaptchaAI prend-il en charge hCaptcha et FunCaptcha ?

Non — hCaptcha et FunCaptcha (Arkose Labs) ne sont pas pris en charge. CaptchaAI couvre reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, l'image/OCR et les grilles, avec CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta). Vérifiez que les types dont vous dépendez y figurent avant de basculer.

Quels forfaits CaptchaAI conviennent à mon volume ?

Le modèle repose sur les threads, avec des résolutions illimitées par thread. BASIC ($15/mois, 5 threads) suffit à la plupart des équipes QA ; montez en gamme (STANDARD à $30/mois, 15 threads, puis au-delà) quand votre parallélisme augmente. Dimensionnez sur les résolutions simultanées, pas sur le total mensuel.

Guides connexes

• Le démarrage rapide CaptchaAI
• Tester vos CAPTCHA en environnement autorisé
• Tester l'endpoint API sur vos formulaires
• Intégrer la résolution CAPTCHA à votre CI
• Résoudre reCAPTCHA v2 via l'API

Basculez proprement et mesurez vos propres temps de résolution dès la première session. – Obtenez votre clé CaptchaAI.