Appeler l’API CAPTCHA depuis Cloudflare Workers

Activez d’abord le profil du site cible pour votre espace de travail dans la console. L’envoi d’un nom d’hôte et d’une action n’en crée pas. Consultez la configuration du profil de site si ce prérequis n’est pas rempli.

• SOLVETHREE_API_KEY : votre clé API d’espace de travail, stockée comme secret du Worker.
• INTEGRATION_KEY : un secret distinct que l’appelant de votre application doit envoyer dans x-integration-key.
• SOLVETHREE_PROXY : l’URL du proxy utilisé pour la résolution. Stockez-la comme secret si elle contient des identifiants.
• CAPTCHA_SITE : le nom d’hôte cible, pas une URL complète.

L’exemple fixe l’action à login et fournit un seul proxy. Modifiez ces paramètres déployés pour les adapter à votre intégration ; n’acceptez pas de paramètres cibles arbitraires fournis par les appelants. Si recaptchaType est omis, l’API utilise reCAPTCHA Enterprise v3 par défaut.

Utilisez la clé d’intégration entre un appelant applicatif de confiance et le Worker, pas dans du code de navigateur distribué publiquement. Il s’agit d’un identifiant partagé, pas d’une autorisation d’accès aux tâches par utilisateur.

export default {
  async fetch(request, env) {
    if (!env.INTEGRATION_KEY || request.headers.get('x-integration-key') !== env.INTEGRATION_KEY) {
      return new Response('Unauthorized', { status: 401 });
    }
    const url = new URL(request.url);
    const headers = { Authorization: `Bearer ${env.SOLVETHREE_API_KEY}`, 'Content-Type': 'application/json' };
    let response;
    if (request.method === 'POST') {
      const requestId = request.headers.get('x-request-id');
      if (!requestId || !/^[A-Za-z0-9_-]{1,64}$/.test(requestId)) return new Response('Provide X-Request-ID', { status: 400 });
      response = await fetch('https://api.solvethree.com/v1/tasks?waitMs=0', {
        method: 'POST', headers, redirect: 'error', signal: AbortSignal.timeout(20000),
        body: JSON.stringify({ site: env.CAPTCHA_SITE, action: 'login', proxy: env.SOLVETHREE_PROXY, requestId }),
      });
    } else if (request.method === 'GET') {
      const id = url.searchParams.get('id');
      if (!id || !/^[A-Za-z0-9_-]{1,128}$/.test(id)) return new Response('Provide a valid id', { status: 400 });
      response = await fetch(`https://api.solvethree.com/v1/tasks/${encodeURIComponent(id)}?waitMs=15000`, {
        headers, redirect: 'error', signal: AbortSignal.timeout(25000),
      });
    } else return new Response('Use POST or GET', { status: 405 });
    if (!response.ok) return Response.json({ error: 'Solver API request failed', status: response.status }, { status: response.status });
    return Response.json(await response.json(), { headers: { 'Cache-Control': 'no-store' } });
  },
};
// Store keys in Worker secret bindings. The task proxy field does not add a
// generic HTTP proxy option to Workers fetch; another client must submit through it.

1. 1.

   Créer une tâche

   Envoyez une requête POST au Worker avec x-integration-key et x-request-id. Choisissez un identifiant de requête contenant 1–64 lettres ASCII, chiffres, traits de soulignement ou traits d’union. Le Worker construit le corps de la tâche à partir de la cible et du proxy configurés ; il n’utilise pas de corps fourni par l’appelant.

2. 2.

   Conserver l’identifiant de tâche

   Le Worker renvoie la réponse JSON du service de résolution. Enregistrez l’identifiant de tâche renvoyé et conservez l’identifiant de requête utilisé pour la créer.

3. 3.

   Récupérer le résultat

   Envoyez une requête GET au Worker avec l’identifiant de tâche dans le paramètre de requête id et le même en-tête de clé d’intégration. Le gestionnaire valide la syntaxe de l’identifiant et récupère cette tâche auprès de solvethree.

Les deux requêtes en amont s’authentifient avec la clé de l’espace de travail. Le gestionnaire transmet les codes d’état HTTP autres que ceux de réussite avec un corps d’erreur générique et marque les réponses JSON réussies avec Cache-Control: no-store. Il ne vérifie pas l’appartenance des tâches au-delà de la clé d’intégration partagée ; ajoutez ce contrôle d’autorisation avant d’ouvrir la récupération à des utilisateurs distincts.

La création utilise waitMs=0 avec un délai d’expiration de 20 secondes pour fetch. La récupération utilise waitMs=15000 avec un délai d’expiration de 25 secondes pour fetch. Ces limites s’appliquent aux appels HTTP individuels, pas à la durée de vie totale de la tâche.

Si le délai de création expire avant que vous receviez un identifiant de tâche, renvoyez la même demande de tâche avec le même identifiant de requête. Cela permet de récupérer la tâche existante si elle a été créée. Ne générez pas de nouvel identifiant simplement parce que la connexion a échoué : la première requête a peut-être déjà atteint solvethree. Réutiliser un identifiant avec des paramètres modifiés provoque un conflit.

L’exemple n’intercepte pas les exceptions de fetch, y compris les dépassements de délai. Ajoutez une gestion des exceptions si votre appelant a besoin d’une réponse d’erreur structurée, mais conservez l’identifiant de requête pour permettre la récupération.

• pending ou solving : récupérez à nouveau la même tâche, dans la limite d’une échéance globale définie dans votre appelant.
• ready : la solution est disponible ; arrêtez l’interrogation et transmettez-la au client de soumission.
• failed : arrêtez l’interrogation et examinez errorCode et error. Corrigez le problème signalé avant de créer une autre tâche.

Une erreur HTTP et une tâche à l’état failed sont deux échecs différents. Le gestionnaire vérifie d’abord l’état HTTP ; l’appelant doit tout de même examiner l’état de la tâche dans une réponse réussie. Pour le diagnostic, consultez les erreurs de l’API CAPTCHA.

L’exemple de Worker appelle uniquement solvethree. Le champ proxy de la tâche indique au service de résolution quel proxy utiliser ; il ne modifie pas le routage réseau du Worker. La fonction fetch de Workers ne propose pas d’option générique d’URL de proxy.

Transmettez la solution prête à un client capable de la soumettre à la cible prévue via le même proxy. Utilisez les valeurs userAgent et secChUa renvoyées dans la solution plutôt que des en-têtes de navigateur sans rapport. Une tâche prête signifie que solvethree a généré une solution ; son acceptation dépend de la requête suivante adressée à la cible.