Skip to main content
Cet article présente une documentation sur l’API de reconnaissance de protocole hCaptcha, qui permet aux utilisateurs de valider sans avoir à reconnaître et cliquer sur les images de captcha hCaptcha, il suffit de soumettre la clé du site Web pour réaliser le décodage automatique en arrière-plan et compléter la validation.

​
Processus de demande

Pour utiliser l’API de reconnaissance de protocole hCaptcha, commencez par obtenir votre jeton API sur le tableau de bord d’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, comprenez la méthode d’utilisation de base, qui consiste à entrer l’URL du site Web nécessitant le traitement du captcha hCaptcha pour obtenir le résultat traité. Vous devez d’abord 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 Element 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 :

Ici, nous avons configuré 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 configuré 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.
Après sélection, 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é 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 la requête 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 obtenir le résultat », 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 :
Ensuite, utilisez ce task_id pour interroger POST /captcha/tasks (il est conseillé de le faire toutes les 3 à 5 secondes) pour obtenir le résultat :
En cours de traitement, cela renverra status: processing :
Une fois le traitement terminé, cela renverra status: ready et le token :
Explication des frais : en mode asynchrone, la création de tâches et l’interrogation « en cours de traitement » ne sont pas facturées ; vous ne serez facturé qu’une seule fois lorsque vous obtiendrez le token avec succès (au même prix que le mode synchrone). Par conséquent, annuler les tâches non terminées lors de la rotation ne générera pas de frais. /captcha/tasks est commun à toutes les interfaces de captcha (token et séries de reconnaissance, comme hcaptcha, recaptcha2, recaptcha3, recognition/*, etc.), vous pouvez interroger avec le même task_id.

​
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 en soumettant 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.