Skip to main content
본 문서에서는 사용자가 hCaptcha 인증 이미지의 인식 및 클릭 없이 Website Key를 제출하기만 하면 백엔드에서 자동으로 해독하여 인증을 완료할 수 있는 hCaptcha 프로토콜 인식 API 연동 방법을 소개합니다.

​
신청 절차

API를 사용하려면 먼저 hCaptcha 프로토콜 인식 API 해당 페이지에서 서비스를 신청해야 합니다. 페이지에 들어가면 “Acquire” 버튼을 클릭합니다. 아래와 같이 표시됩니다: 로그인 또는 등록이 되어 있지 않으면 자동으로 로그인 페이지로 이동하여 등록 및 로그인을 요청합니다. 로그인 및 등록 후에는 자동으로 현재 페이지로 돌아옵니다. 첫 신청 시 무료 사용량이 제공되며, 해당 API를 무료로 사용할 수 있습니다.

​
기본 사용

먼저 기본 사용 방법을 이해해야 합니다. 처리할 hCaptcha 인증 코드가 있는 웹사이트의 URL을 입력하면 처리된 결과를 얻을 수 있습니다. 먼저 website_url 필드를 간단히 전달해야 합니다. 우리의 예제 웹사이트는 https://accounts.hcaptcha.com/demo입니다. website_url 페이지에서 website_key를 가져와야 하며, 이 웹페이지를 열고 F12를 눌러 콘솔에 들어간 후 Element 페이지에서 전역 검색으로 hcaptcha-demo를 검색하면 아래와 같은 결과를 얻을 수 있습니다:

여기서 data-sitekey에 해당하는 문자열이 website_key의 값입니다. 아래는 구체적인 매개변수 결과입니다:

여기서 우리는 Request Headers를 설정했습니다. 포함된 내용은 다음과 같습니다:
  • accept: 어떤 형식의 응답 결과를 받고 싶은지, 여기서는 application/json으로 JSON 형식으로 입력합니다.
  • authorization: API 호출을 위한 키로, 신청 후 직접 드롭다운에서 선택할 수 있습니다.
또한 Request Body를 설정했습니다. 포함된 내용은 다음과 같습니다:
  • website_url: 인증 코드를 처리할 웹사이트의 URL입니다.
  • website_key: hCaptcha에서의 웹사이트 키 식별자입니다.
선택 후 오른쪽에도 해당 코드가 생성된 것을 확인할 수 있습니다. 아래와 같이 표시됩니다:

“Try” 버튼을 클릭하면 테스트를 진행할 수 있으며, 위 그림과 같이 다음과 같은 결과를 얻을 수 있습니다:
可以看到我们得到了处理 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：Bad request, possibly due to missing or invalid parameters.
  • 400 api_not_implemented：Bad request, possibly due to missing or invalid parameters.
  • 401 invalid_token：Unauthorized, invalid or missing authorization token.
  • 429 too_many_requests：Too many requests, you have exceeded the rate limit.
  • 500 api_error：Internal server error, something went wrong on the server.

​
错误响应示例

​
结论

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