Skip to main content
Questo documento presenterà una guida all’integrazione dell’API di riconoscimento del protocollo hCaptcha, che consente agli utenti di completare la verifica senza dover riconoscere e selezionare le immagini del captcha hCaptcha, ma semplicemente inviando la Website Key per ottenere la decodifica automatica in background.

​
Processo di richiesta

Per utilizzare l’API, è necessario prima andare alla pagina corrispondente dell’API di riconoscimento del protocollo hCaptcha per richiedere il servizio corrispondente. Una volta entrati nella pagina, fare clic sul pulsante “Acquire”, come mostrato nell’immagine: Se non si è ancora effettuato il login o la registrazione, si verrà automaticamente reindirizzati alla pagina di accesso che invita a registrarsi e accedere. Dopo aver effettuato il login o la registrazione, si verrà riportati automaticamente alla pagina corrente. Alla prima richiesta, verrà offerto un credito gratuito, che consente di utilizzare gratuitamente questa API.

​
Utilizzo di base

Innanzitutto, è importante comprendere il modo di utilizzo di base, che consiste nell’inserire l’URL del sito web che deve elaborare il captcha hCaptcha per ottenere il risultato elaborato. È necessario semplicemente trasmettere un campo website_url. Il nostro sito di esempio è: https://accounts.hcaptcha.com/demo, dobbiamo ottenere il website_key dalla pagina website_url. Prima di tutto, aprire questa pagina, premere F12 per accedere alla console e infine cercare globalmente hcaptcha-demo nella pagina Element. Possiamo ottenere il seguente risultato:

La stringa corrispondente a data-sitekey è il valore di website_key. Di seguito sono riportati i risultati specifici dei parametri:

Possiamo vedere che qui abbiamo impostato le intestazioni della richiesta, tra cui:
  • accept: il formato della risposta desiderata, qui è impostato su application/json, ovvero formato JSON.
  • authorization: la chiave per chiamare l’API, che può essere selezionata direttamente dopo la richiesta.
Inoltre, è stato impostato il corpo della richiesta, che include:
  • website_url: l’URL del sito web che deve elaborare il captcha.
  • website_key: l’identificatore della chiave del sito in hCaptcha.
Dopo aver selezionato, si può notare che a destra è stato generato il codice corrispondente, come mostrato nell’immagine:

Cliccando sul pulsante “Try” è possibile effettuare un test, come mostrato nell’immagine sopra, e qui abbiamo ottenuto il seguente risultato:
可以看到我们得到了处理 hCaptcha验证码 的验证结果，然后我们可以用于POST或模拟提交给目标网站，一次性使用，有效期120s，建议在60s内使用，接下来将提供一段CURL版本将处理后token提交到目标网站来通过Recaptcha2验证码。 首先我们需要获取网站是如何发送POST请求，这样我们才能将生成的token传入进去，我们需要先打开F12控制台，然后人工先通过一下，最后我们可以看到网站发送了一个POST请求，我们只需要查看这次的POST请求构造，具体的过程如下：
  • 先人工通过验证，具体的如下图：

  • 再点击submit，观看控制台的network变化，具体的如下图：

  • 分析此次提交的POST请求构造，最后可以右键该请求复制CURL的代码，具体的如下图：

由上图分析可知，此次POST请求的URL为：https://accounts.hcaptcha.com/demo，我们仅需要提交参数 g-recaptcha-response、h-captcha-response 和 email，然后我们只需要将处理后的token传入下面的data中即可，调用token验证所对应CURL代码如下：
调用token验证所对应的Python代码如下：
然后我们观察控制台变得了这样的结果：

最后我们就通过了hCaptcha验证码的验证。 另外如果想生成对应的对接代码，可以直接复制生成，例如 CURL 的代码如下：
Python 的对接代码如下：

​
错误处理

在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：
  • 400 token_mismatched：Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
  • 400 api_not_implemented：Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
  • 401 invalid_token：Non autorizzato, token di autorizzazione non valido o mancante.
  • 429 too_many_requests：Troppe richieste, hai superato il limite di frequenza.
  • 500 api_error：Errore interno del server, qualcosa è andato storto sul server.

​
错误响应示例

​
结论

通过本文档，您已经了解了如何使用 hCaptcha 协议识别 API 让用户无需识别和点选 hCaptcha 验证码图片，仅需通过提交 Website Key 即可实现后台自动解码，完成验证。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。