Résoudre reCAPTCHA Enterprise avec Node.js

Installez le paquet officiel directement depuis solvethree.com :

npm install https://solvethree.com/downloads/solvethree-sdk-0.1.0.tgz

1. 1.

   Activer le profil de site

   Configurez le site cible dans la console et vérifiez que son profil est actif et accessible à votre espace de travail. Envoyer un nom d’hôte et une action ne crée pas de profil. Consultez la configuration du profil de site.

2. 2.

   Configurer l’environnement serveur

   Dans l’environnement du processus Node.js, définissez SOLVETHREE_API_KEY sur la clé API de votre espace de travail et SOLVETHREE_PROXY sur l’URL de votre proxy. Conservez la clé API sur le serveur ; ne l’exposez pas dans le code du navigateur.

3. 3.

   Préparer le script

   Enregistrez l’exemple suivant sous solve.mjs. Remplacez accounts.example.com par votre nom d’hôte configuré et login par l’action reCAPTCHA réelle de la page.

Utilisez un nom d’hôte pour site, et non l’URL d’une page. reCAPTCHA utilise enterprise-v3 par défaut ; l’exemple n’a donc pas besoin de recaptchaType. N’ajoutez pas type ni url. La requête exige exactement un des deux champs proxy ou proxyCandidates ; cet exemple utilise un seul proxy.

import { randomUUID } from 'node:crypto';
import { Solvethree, SolvethreeError, TaskFailedError } from '@solvethree/sdk';

const client = new Solvethree({ apiKey: process.env.SOLVETHREE_API_KEY });
const request = {
  site: 'accounts.example.com', // Use your configured hostname.
  action: 'login',              // Use the page's actual action.
  proxy: process.env.SOLVETHREE_PROXY,
  requestId: randomUUID(),
};
let result;
try {
  result = await client.solve(request, { timeoutMs: 180_000 });
} catch (error) {
  if (error instanceof TaskFailedError) {
    throw new Error(`Task failed: ${error.errorCode}`);
  }
  if (error instanceof SolvethreeError) {
    // Save these IDs; use them to recover the existing task.
    console.error({ requestId: error.requestId, taskId: error.taskId });
  }
  throw error;
}
const { token, userAgent, secChUa } = result.solution;
console.log('Ready task:', result.id); // Keep solution credentials private.

Exécutez le script avec Node.js après avoir défini les variables d’environnement. solve crée la tâche une seule fois et interroge son état jusqu’à ce qu’elle soit prête ou qu’une exception soit levée. Le délai de 180,000 ms limite l’attente du client.

Les champs renvoyés ont des rôles différents :

• result.id identifie la tâche. Ce n’est pas le jeton CAPTCHA.
• result.solution.token est la valeur à envoyer dans le champ CAPTCHA de l’application.
• result.solution.userAgent et result.solution.secChUa constituent l’identité de navigateur à utiliser avec ce jeton.

Gardez les valeurs de la solution confidentielles. Si vous devez pouvoir reprendre après un redémarrage du processus, enregistrez le requestId et les paramètres exacts de la tâche avant d’appeler solve, en protégeant les éventuels identifiants du proxy.

Continuez dans le même script après le retour de solve. Cet exemple utilise undici, que vous devez installer séparément comme l’indique son commentaire. Il envoie le jeton via request.proxy et utilise les deux champs d’identité de navigateur renvoyés.

// Continue after client.solve(). Install undici separately: npm install undici@7.
import { fetch, ProxyAgent } from 'undici';

const dispatcher = new ProxyAgent(request.proxy);
try {
  // Replace the URL and form fields with your application's contract.
  const response = await fetch('https://accounts.example.com/login', {
    method: 'POST',
    dispatcher,
    redirect: 'manual',
    headers: {
      'user-agent': result.solution.userAgent,
      'sec-ch-ua': result.solution.secChUa,
    },
    body: new URLSearchParams({
      'g-recaptcha-response': result.solution.token,
    }),
    signal: AbortSignal.timeout(30_000),
  });
  console.log('Application HTTP status:', response.status);
  await response.arrayBuffer();
} finally {
  await dispatcher.close();
}

Remplacez l’URL et les champs du formulaire par ceux attendus par votre application. L’exemple fournit uniquement g-recaptcha-response ; incluez tous les autres champs et données de session exigés par l’application. Veillez à ce que la cible corresponde au site et à l’action utilisés pour la résolution.

Comme la demande de résolution utilise un seul proxy, réutiliser request.proxy permet d’envoyer le jeton via ce même proxy. Si vous modifiez la requête pour utiliser proxyCandidates, sélectionnez plutôt le proxy ayant réussi avec la fonction utilitaire successfulProxy du SDK.

Une tâche prête signifie qu’une solution a été générée, pas que la cible a accepté votre requête applicative. Vérifiez dans la réponse de la cible que sa condition réelle de réussite est remplie ; afficher un statut HTTP ne suffit pas. Pour diagnostiquer un rejet, consultez jeton prêt rejeté.

L’exemple de résolution distingue les échecs définitifs de tâche des autres erreurs du SDK. Conservez cette distinction : l’échec d’une tâche et celui d’une requête HTTP nécessitent des traitements différents.

solve lève TaskFailedError

L’exception contient errorCode et taskId. Appelez getTask(taskId) si vous avez besoin de la réponse complète de la tâche échouée, y compris le texte de l’erreur.

Essayez ceci : Cessez d’interroger cette tâche et corrigez la cause signalée avant d’en créer une autre. Ne réessayez pas avec des paramètres invalides inchangés.

Une SolvethreeError contient taskId

Le SDK dispose d’un ID pour la tâche existante.

Essayez ceci : Reprenez l’interrogation avec getTask. Continuez pour pending ou solving, utilisez la solution uniquement lorsque le statut est ready et arrêtez-vous sur failed.

La création est interrompue et seul requestId est disponible

L’expiration du délai de connexion ne prouve pas que la tâche n’a pas été créée.

Essayez ceci : Reprenez avec createTask en utilisant des paramètres de tâche identiques et le même requestId. Réutiliser cet ID avec des paramètres différents provoque un conflit.

L’API rejette une requête HTTP

Examinez le statut HTTP exposé par ApiError plutôt que de traiter la réponse comme une tâche prête ou échouée.

Essayez ceci : Corrigez l’erreur HTTP avant de traiter une réponse de réussite. Ne supposez pas que tout échec est dû à un crédit insuffisant.

L’exemple génère un nouveau requestId à chaque démarrage du programme. Le relancer sans modification ne constitue pas une reprise : utilisez plutôt votre requête et vos ID enregistrés. Le SDK ne réessaie jamais automatiquement de créer une tâche ; il respecte toutefois Retry-After lors d’échecs temporaires d’interrogation, dans la limite du délai de résolution.

Pour l’interrogation explicite et les paramètres d’attente, consultez l’interrogation des tâches et les délais d’expiration.