Migrer une intégration reCAPTCHA de CapSolver vers solvethree

solvethree utilise reCAPTCHA v3 Enterprise par défaut et accepte aussi la version v3 standard. Ses autres produits publics sont Kasada et Ticketmaster TMPT. Il ne prend pas en charge reCAPTCHA v2, hCaptcha, Turnstile ni la résolution par extension de navigateur : ce n’est donc pas un remplacement universel de toutes les intégrations CapSolver.

Avant d’envoyer une tâche reCAPTCHA, configurez le site cible dans la console et assurez-vous qu’un profil actif est disponible pour votre espace de travail. Envoyer un nom d’hôte et une action ne crée pas ce profil. Ne supprimez pas le champ websiteKey de CapSolver en supposant que le reste de la requête suffit.

La requête initiale utilise clientKey de CapSolver et une enveloppe de tâche propre au fournisseur :

{
  "clientKey": "CAPSOLVER_API_KEY",
  "task": {
    "type": "ReCaptchaV3Task",
    "websiteURL": "https://accounts.example.com/login",
    "websiteKey": "PUBLIC_SITE_KEY",
    "pageAction": "login",
    "isEnterprise": true,
    "proxy": "http://user:[email protected]:8080"
  }
}

Pour solvethree, envoyez le corps à plat ci-dessous à POST https://api.solvethree.com/v1/tasks. Définissez l’en-tête Authorization sur Bearer suivi de la clé API de votre espace de travail. Gardez cette clé côté serveur ; ne reprenez pas clientKey dans le nouveau corps JSON.

{
  "site": "accounts.example.com",
  "action": "login",
  "proxy": "http://user:[email protected]:8080",
  "requestId": "example_login_001"
}

L’exemple est une requête Enterprise, car il laisse recaptchaType à sa valeur par défaut. Sélectionnez explicitement la version v3 standard si votre cible l’utilise ; ne convertissez pas tous les types de tâches CapSolver vers la valeur Enterprise par défaut.

Une tâche CapSolver ProxyLess n’a pas d’équivalent direct sans proxy ici : solvethree exige un proxy fourni par l’appelant. Si votre intégration actuelle ne gère pas de proxy, il s’agit d’une modification de l’intégration, pas d’un renommage de champ. Ne copiez pas non plus une configuration de proxy SOCKS dans la nouvelle requête ; solvethree accepte les URL de proxy HTTP et HTTPS.

Commencez avec un seul proxy afin que la route utilisée pour la résolution et la soumission soit sans ambiguïté. Si vous utilisez plutôt proxyCandidates, fournissez au maximum douze URL de proxy HTTP ou HTTPS distinctes, sans chemin, paramètres de requête ni fragment. Ces candidats permettent au service d’essayer d’autres sorties réseau ; ils ne garantissent pas qu’un proxy ou une cible fonctionnera.

CapSolver récupère les résultats asynchrones via getTaskResult avec clientKey et taskId. solvethree les récupère via GET /v1/tasks/:id avec une authentification Bearer. Mettez à jour l’analyseur de résultats ainsi que l’appel HTTP ; les champs de statut et d’erreur de CapSolver relèvent d’un contrat différent.

1. 1.

   Vérifier d’abord la réponse HTTP

   Traitez les réponses HTTP non réussies avant de lire le contenu d’une réponse réussie. Une erreur de requête HTTP et une tâche de résolution échouée nécessitent des traitements distincts.

2. 2.

   Examiner la tâche renvoyée lors de la création

   La création reCAPTCHA attend jusqu’à 15 secondes par défaut ; la réponse peut donc déjà indiquer un état final. Seul ready contient une solution utilisable. Si la tâche est pending ou solving, récupérez-la avec l’ID de tâche solvethree renvoyé.

3. 3.

   Arrêter les interrogations lorsque la tâche est prête ou a échoué

   Pour ready, transmettez la solution à votre code de soumission. Pour failed, examinez errorCode et error, puis cessez d’interroger cette tâche. Les résolutions échouées sont remboursées. Ne réessayez pas aveuglément avec des données invalides inchangées et ne supposez pas que chaque échec indique un crédit insuffisant.

Lors d’une migration progressive, associez chaque ID de tâche à son fournisseur. Terminez les tâches CapSolver existantes via CapSolver et acheminez les nouvelles tâches solvethree via solvethree. Normalisez leurs résultats dans votre adaptateur plutôt que d’envoyer l’ID de tâche de l’ancien fournisseur à la nouvelle API.

Utilisez solution.token lorsque vous soumettez le résultat reCAPTCHA à la cible prévue. Conservez également les valeurs userAgent et secChUa renvoyées, et utilisez le proxy qui a fonctionné pour la soumission. Si votre adaptateur actuel ne renvoie qu’une chaîne de jeton, modifiez-le pour transmettre ces informations jusqu’au client chargé de la soumission.

Si un jeton prêt est rejeté, examinez la requête applicative sortante avant de payer une autre résolution. Vérifiez qu’elle contient le nouveau jeton — pas un ID de tâche ni un ancien jeton — et que la soumission utilise l’identité du navigateur renvoyée, le proxy qui a fonctionné et l’URL cible prévue. Une tâche ready signifie qu’une solution a été générée, pas que la cible a accepté votre requête suivante.

L’exemple après migration inclut requestId pour la récupération. Générez-en un pour chaque nouvelle tâche logique et conservez-le avec les données exactes de la requête. Il doit contenir de 1 à 64 lettres ASCII, chiffres, traits de soulignement ou traits d’union. Le réutiliser avec la même requête de tâche renvoie la tâche existante ; l’utiliser avec des données différentes provoque un conflit.

Si la création dépasse le délai, récupérez la tâche si vous avez son ID, ou renvoyez le même corps avec le même requestId. Une réponse perdue ne prouve pas que la création a échoué. Ne générez pas un nouvel ID simplement parce que votre client a cessé d’attendre.

Dans le délai d’expiration de votre client, prévoyez l’attente par défaut de la création reCAPTCHA, jusqu’à 15 secondes, plus le temps réseau. L’interrogation GET répond sans attendre par défaut et accepte waitMs jusqu’à 15000. Placez waitMs dans les paramètres de l’URL, pas dans le JSON de la tâche, et tenez aussi compte de cette attente dans le délai d’expiration des interrogations.