Skip to main content
Cet article présentera une documentation d’intégration de l’API de reconnaissance de protocole hCaptcha, qui permet aux utilisateurs de ne pas avoir à reconnaître et à cliquer sur les images de captcha hCaptcha, mais simplement de soumettre la clé du site Web pour réaliser un décodage automatique en arrière-plan et compléter la vérification.

​
Processus de demande

Pour utiliser l’API de reconnaissance de protocole hCaptcha, commencez par obtenir votre jeton API sur le tableau de bord Ace Data Cloud et conservez-le pour référence. Si vous n’êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion qui vous invite à vous inscrire et à vous connecter, après quoi vous serez automatiquement renvoyé à la page actuelle. Un jeton API suffit pour appeler tous les services de la plateforme, sans avoir à en demander un pour chaque service. La première demande vous donnera un quota gratuit pour une expérience sans frais ; en cas de quota insuffisant, vous pouvez recharger le solde général dans le tableau de bord.
📘 Documentation complète : API de reconnaissance de protocole hCaptcha →

​
Utilisation de base

Tout d’abord, comprenons la méthode d’utilisation de base, qui consiste à entrer l’URL du site Web nécessitant le traitement du captcha hCaptcha, afin d’obtenir le résultat traité. Il suffit de transmettre un champ website_url, notre site d’exemple est : https://accounts.hcaptcha.com/demo, nous devons obtenir le website_key sur la page website_url, ouvrez d’abord cette page, appuyez sur F12 pour accéder à la console, puis effectuez une recherche globale dans l’onglet Éléments pour hcaptcha-demo, nous pouvons obtenir le résultat suivant :

La chaîne de caractères correspondant à data-sitekey est la valeur de website_key, voici les résultats des paramètres spécifiques :

Nous pouvons voir ici que nous avons défini les en-têtes de requête, y compris :
  • accept : le format de réponse souhaité, ici rempli avec application/json, c’est-à-dire au format JSON.
  • authorization : la clé pour appeler l’API, que vous pouvez sélectionner directement après la demande.
De plus, nous avons défini le corps de la requête, y compris :
  • website_url : l’URL du site Web nécessitant le traitement du captcha.
  • website_key : l’identifiant de la clé du site dans hCaptcha.
  • rqdata : optionnel. Le défi hCaptcha Enterprise peut fournir data-rqdata sur la page, en cas de défi de ce type, remplissez sa valeur d’origine ; le hCaptcha ordinaire n’a pas besoin d’être rempli.
  • proxy : optionnel, apportez votre propre proxy (Bring Your Own Proxy). Une fois configuré, le système utilisera l’IP proxy que vous fournissez pour résoudre le captcha, afin de contrôler la qualité de l’IP de sortie (par exemple, éviter que l’IP proxy publique soit bloquée par le site cible et renvoie 410 Gone). Le format est scheme://[user:pass@]host:port, scheme prend en charge http/https/socks4/socks5, par exemple http://user:pass@1.2.3.4:8080. Si non rempli, le proxy par défaut de la plateforme sera utilisé.
Après avoir fait votre choix, vous pouvez constater que le code correspondant a également été généré à droite, comme illustré ci-dessous :

Cliquez sur le bouton « Essayer » pour effectuer un test, comme montré sur l’image ci-dessus, ici nous avons obtenu le résultat suivant :
Nous pouvons voir que nous avons obtenu le résultat de vérification du captcha hCaptcha, puis nous pouvons l’utiliser pour POST ou simuler une soumission au site cible, à usage unique, avec une durée de validité de 120 secondes, il est conseillé de l’utiliser dans les 60 secondes. Ensuite, nous fournirons une version CURL pour soumettre le token traité au site cible afin de passer le captcha Recaptcha2. Tout d’abord, nous devons comprendre comment le site envoie des requêtes POST, afin que nous puissions y insérer le token généré. Nous devons d’abord ouvrir la console F12, puis passer manuellement par le processus, et enfin nous pouvons voir que le site a envoyé une requête POST. Nous devons simplement examiner la construction de cette requête POST, le processus spécifique est le suivant :
  • D’abord, passez manuellement la vérification, comme indiqué dans l’image ci-dessous :

  • Ensuite, cliquez sur soumettre, regardez les changements dans le réseau de la console, comme indiqué dans l’image ci-dessous :

  • Analysez la construction de la requête POST soumise, puis faites un clic droit sur cette requête pour copier le code CURL, comme indiqué dans l’image ci-dessous :

D’après l’image ci-dessus, nous pouvons voir que l’URL de cette requête POST est : https://accounts.hcaptcha.com/demo, nous devons simplement soumettre les paramètres g-recaptcha-response, h-captcha-response et email, puis nous devons simplement insérer le token traité dans les données ci-dessous, le code CURL correspondant pour vérifier le token est le suivant :
Le code Python correspondant pour vérifier le token est le suivant :
Ensuite, nous observons que la console a produit ce résultat :

Enfin, nous avons réussi à passer la vérification du captcha hCaptcha. De plus, si vous souhaitez générer le code d’intégration correspondant, vous pouvez le copier directement, par exemple, le code CURL est le suivant :
Le code d’intégration Python est le suivant :

​
Mode asynchrone (async)

Par défaut, l’API est synchrone et bloquante : une requête attendra jusqu’à ce que le traitement du token soit terminé avant de renvoyer une réponse. Si vous effectuez une rotation de plusieurs solveurs (multi-solver rotation) et souhaitez « soumettre une tâche et obtenir immédiatement un task_id, puis planifier d’autres solveurs et revenir plus tard pour lire les résultats », vous pouvez passer async: true dans le corps de la requête. En passant async: true, l’interface renverra immédiatement un task_id, sans bloquer l’attente :
Pour vérifier le progrès, vous pouvez utiliser ce task_id pour interroger POST /captcha/tasks (il est conseillé de le faire toutes les 3 à 5 secondes). Cette interface ne déclenchera ni n’avancera le traitement de la tâche ; même si vous ne consultez pas, si vous perdez la connexion ou quittez le client, le serveur continuera à traiter :
En cours de traitement, cela renverra status: processing :
Une fois le traitement terminé, cela renverra status: ready et le token :
Explication de la facturation : en mode asynchrone, la création de tâches et la lecture de l’état « en cours de traitement » ne sont pas facturées ; le client est facturé une fois lors de la première lecture réussie des résultats (conforme au comportement actuel et au prix du mode synchrone). Le serveur avancera la tâche de manière autonome, mais ne facturera pas à l’avance si le traitement est terminé en arrière-plan. Si la tâche n’est pas réussie dans les 120 secondes, elle sera arrêtée avec un HTTP 504 timeout, sans facturation. /captcha/tasks n’est pas responsable de l’avancement des tâches.

​
Gestion des erreurs

Lors de l’appel de l’API, si une erreur se produit, l’API renverra le code d’erreur et les informations correspondantes. Par exemple :
  • 400 token_mismatched : Mauvaise requête, probablement en raison de paramètres manquants ou invalides.
  • 400 api_not_implemented : Mauvaise requête, probablement en raison de paramètres manquants ou invalides.
  • 401 invalid_token : Non autorisé, token d’autorisation invalide ou manquant.
  • 429 too_many_requests : Trop de requêtes, vous avez dépassé la limite de taux.
  • 500 api_error : Erreur interne du serveur, quelque chose s’est mal passé sur le serveur.

​
Exemple de réponse d’erreur

​
Conclusion

Grâce à ce document, vous avez compris comment utiliser l’API de reconnaissance du protocole hCaptcha pour permettre aux utilisateurs de ne pas avoir à reconnaître et cliquer sur les images de captcha hCaptcha, mais simplement de soumettre la clé du site pour réaliser le décodage automatique en arrière-plan et compléter la vérification. Nous espérons que ce document vous aidera à mieux intégrer et utiliser cette API. Si vous avez des questions, n’hésitez pas à contacter notre équipe de support technique.