Résolution de CAPTCHAs avec Koyeb Edge Workers

Périmètre sûr : ce guide couvre uniquement vos propres applications et environnements, ou des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne s'applique pas à l'automatisation de sites tiers ou de services que vous ne contrôlez pas.

Résoudre un CAPTCHA depuis un worker Koyeb revient à appeler l'API CaptchaAI en HTTPS depuis un service sans état, à attendre le token, puis à le réinjecter dans votre requête. Le vrai enjeu n'est pas le premier appel qui réussit en cinq minutes : c'est de tenir dans la durée, sans surveillance, à travers les déploiements, les pics de trafic et les démarrages à froid propres au serverless. Ce guide décrit une architecture qui absorbe ces trois contraintes et reste lisible pour l'équipe qui reprendra le code.

Pourquoi exécuter la résolution CAPTCHA dans un worker serverless

Koyeb est une plateforme serverless européenne : vous poussez un conteneur et il s'exécute au plus près de vos utilisateurs, sans serveur à gérer. Une intégration robuste traite le démarrage à froid, un réseau qui hoquette ou un changement de type de CAPTCHA comme des cas normaux.

Un point de coût mérite d'être clarifié tôt : CaptchaAI facture par thread simultané, pas au CAPTCHA résolu. L'offre BASIC ($15/mois, 5 threads) suffit à alimenter un worker, et vous montez en threads quand le volume grimpe — une boucle de retry ne fera donc pas exploser la facture.

Architecture cible : du worker jusqu'à CaptchaAI

Le worker appelle CaptchaAI via HTTPS pour obtenir un token, puis l'injecte dans le flux qui a déclenché le défi CAPTCHA — même session, même client HTTP, même contexte de cookies. Cette continuité de session est la règle la plus importante : un token appliqué dans une autre session que celle du défi est la première cause de rejet après résolution. Tracez chaque étape avec un identifiant de corrélation unique pour repérer les régressions dès une montée de version.

Gérer les secrets et la clé API

La clé CaptchaAI ne vit jamais dans le code source. Stockez-la dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret CI/CD, et laissez le déploiement Koyeb la monter en variable d'environnement au runtime. Séparez une clé par environnement pour éviter qu'un test de préproduction ne consomme le solde de production.

Si votre worker collecte des données au passage, gardez le réflexe RGPD : ne journalisez que le strict nécessaire au diagnostic, sans données personnelles dans les logs.

Exemple d'appel côté serveur

Voici un appel HTTP côté serveur, tel qu'il vivrait dans votre propre service worker :

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

Le contrat reste identique quel que soit le type : vous soumettez une tâche, récupérez un identifiant, puis interrogez le résultat jusqu'au token. Passez de Cloudflare Turnstile à reCAPTCHA v2 ou v3 en changeant le type, sans toucher au reste de la boucle.

Observabilité : ce qu'il faut journaliser

Quel que soit le langage, instrumentez les appels CAPTCHA pour obtenir des métriques exploitables : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente. Ces signaux alimentent vos tableaux de bord de QA et vos alertes.

Séparez les journaux par environnement et corrélez les identifiants à votre traçage distribué, par exemple via OpenTelemetry. En cas d'incident, vous rejouez un cas réel au lieu de le reconstituer de mémoire.

Indicateurs à suivre

Les valeurs ci-dessous sont des objectifs que vous fixez pour votre intégration, pas des garanties : les résultats varient selon l'environnement, le volume et le moment de la journée.

Liste de contrôle avant la mise en production

• Le périmètre est strictement limité à vos applications ou à des sources autorisées.
• La clé CaptchaAI est stockée dans un secret CI/CD ou un coffre, jamais en clair dans le dépôt.
• Les durées d'appel et les codes retour sont tracés pour chaque exécution.
• Une stratégie de retry idempotent avec backoff exponentiel borné couvre les erreurs transitoires.
• Le token est appliqué dans la même session que celle du défi, et les tests sont rejouables en CI.

Dépannage

FAQ

Faut-il un navigateur headless pour appeler CaptchaAI depuis un worker ?

Non. L'appel se résume à des requêtes HTTPS de soumission puis d'interrogation du résultat, ce qui convient parfaitement à un worker serverless sans état. Vous n'embarquez un navigateur que si votre propre flux impose de piloter une page complète.

Comment sécuriser la clé API dans un environnement serverless ?

Placez-la dans un secret CI/CD ou un coffre, montez-la en variable d'environnement au déploiement, et utilisez une clé distincte par environnement. Ne l'écrivez jamais dans les logs ni dans le dépôt, et faites-la tourner au moindre doute.

Que se passe-t-il si un démarrage à froid ralentit le worker ?

Le démarrage à froid ajoute de la latence à la première requête, pas à la résolution elle-même. Dimensionnez vos timeouts en conséquence et surveillez la p95 pour distinguer un cold start d'un vrai problème d'intégration.

La facturation dépend-elle du nombre de CAPTCHAs résolus ?

Non : CaptchaAI facture par thread simultané, avec des résolutions illimitées par thread sur le mois. Un worker qui traite un CAPTCHA à la fois tient sur un seul thread ; montez en threads quand la concurrence augmente.

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

Passez d'un appel qui fonctionne une fois à une intégration qui tient en production. – Obtenez votre clé CaptchaAI.