Scarnox · Blog

API de solveur de captcha : son fonctionnement et comment l'appeler

Une API de solveur de captcha est un service web que vous appelez en HTTP. Vous lui envoyez les détails d'un captcha, à savoir le type de tâche, la sitekey de la page et l'URL de la page, et elle renvoie un token que le site accepte comme preuve que le défi a été réussi. L'endpoint de Scarnox fonctionne ainsi et il est synchrone : une seule requête vous donne la réponse.

Ce guide couvre la requête, la réponse, le format des erreurs et les détails qui déterminent si une intégration tient en production. Si vous voulez d'abord un script exécutable, commencez par Comment résoudre un PopularCaptcha en Python.

Ce que fait l'API et ce qu'elle ne fait pas

Votre code trouve le captcha sur une page, lit sa sitekey et l'envoie au solveur. Le solveur renvoie un token. Votre code écrit ce token dans le champ de formulaire attendu par le site et soumet le formulaire.

Le solveur ne charge pas votre page, ne clique sur rien et ne soumet pas votre formulaire. Il produit seulement le token. Garder cette limite en tête facilite le raisonnement sur le reste de l'intégration : tout ce qui concerne votre session, vos cookies et le timing de vos requêtes reste dans votre code.

Aujourd'hui, le seul type de tâche disponible est PopularCaptcha sans proxy, soit PopularCaptchaTaskProxyless. Les autres types de captcha sont prévus dans la feuille de route. Le guide des types de captcha indique lequel est lequel.

L'endpoint

Envoyez une requête POST à :

POST https://api.scarnox.com/api/tasks/create
Authorization: Bearer scarnox_YOURAPIKEY
Content-Type: application/json

Le corps décrit la tâche :

{
  "captcha_type": "PopularCaptchaTaskProxyless",
  "site_key": "10000000-ffff-ffff-ffff-000000000001",
  "site_url": "https://example.com/signup"
}

Les trois champs obligatoires sont :

Trois champs optionnels existent. proxy prend une valeur de la forme http://user:pass@host:port et s'utilise avec les types de tâches à proxy. rqdata et is_invisible servent à des variantes de widgets précises. La liste complète des types de tâches et le détail des champs figurent dans la référence de l'API.

Synchrone signifie pas de polling

L'appel bloque jusqu'à ce que le token soit prêt. Vous n'interrogez rien, et il n'y a pas de seconde requête « obtenir le résultat » dans ce flux. Réglez le délai d'attente de votre client HTTP à environ 185 secondes pour qu'une résolution lente ne ressemble pas à une panne réseau.

En Python avec la bibliothèque requests, cela donne :

import requests

r = requests.post(
    "https://api.scarnox.com/api/tasks/create",
    headers={"Authorization": "Bearer scarnox_YOURAPIKEY"},
    json={
        "captcha_type": "PopularCaptchaTaskProxyless",
        "site_key": "10000000-ffff-ffff-ffff-000000000001",
        "site_url": "https://example.com/signup",
    },
    timeout=185,
)
data = r.json()

Lisez la clé depuis une variable d'environnement plutôt que de l'écrire dans le script. Quiconque peut lire le code source ne doit pas pouvoir utiliser votre solde.

Lire la réponse

Une résolution réussie renvoie un errorId égal à 0, le token dans solution, et un champ cost :

{"errorId": 0, "solution": {"token": "..."}, "cost": ...}

Une résolution échouée renvoie un errorId différent de 0, ainsi qu'un errorCode lisible par une machine et un errorDescription lisible par un humain :

{"errorId": 1, "errorCode": "...", "errorDescription": "..."}

Vérifiez errorId dans le corps à chaque appel. Ne supposez pas qu'une requête HTTP terminée signifie que vous avez un token. La règle la plus importante est la suivante : vous êtes facturé uniquement lorsque errorId vaut 0. Les résolutions échouées sont gratuites. Pour les tarifs actuels, consultez la page tarifs.

Durée de vie du token

Les tokens PopularCaptcha expirent en environ deux minutes. Soumettez le token dès que vous le recevez. Ne mettez pas les tokens en cache pour plus tard, et ne résolvez pas à l'avance avant la soumission du formulaire. Si votre code effectue plusieurs étapes entre l'obtention du token et l'envoi du formulaire, déplacez la résolution au dernier moment.

Mettre le token dans le formulaire

La plupart des sites lisent la réponse de PopularCaptcha dans un champ de formulaire nommé h-captcha-response. Beaucoup acceptent aussi g-recaptcha-response avec la même valeur. Envoyer les deux est donc un choix sûr et courant :

requests.post("https://example.com/signup", data={
    "email": "you@example.com",
    "h-captcha-response": token,
    "g-recaptcha-response": token,
})

Si le formulaire n'accepte pas le token, la cause est généralement une sitekey ou une URL de page qui ne correspond pas à la page où se trouvait réellement le widget. Vérifiez bien ces valeurs avant d'incriminer le solveur.

Gestion des erreurs

Une intégration en production demande une courte liste de bonnes habitudes :

Le guide sur les réessais et la gestion des erreurs détaille chacun de ces points.

Pour commencer

Créez un compte : vous pouvez démarrer avec un crédit d'essai gratuit, sans carte bancaire. Lancez ensuite la requête ci-dessus sur une page de test que vous contrôlez, et vérifiez que le formulaire accepte le token avant de la connecter à quoi que ce soit d'important.

Étapes suivantes