메인 콘텐츠로 건너뛰기
본 문서는 Recaptcha3 프로토콜 인식 API 연동 설명을 소개하며, 사용자가 Recaptcha3 인증 이미지의 인식 및 클릭 없이 Website Key를 제출하기만 하면 백그라운드에서 자동으로 디코딩하여 인증을 완료할 수 있도록 합니다.

​
신청 절차

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

​
기본 사용

먼저 기본 사용 방식을 이해해야 하며, Recaptcha2와 비교하여 추가로 page_action이라는 매개변수를 전달해야 합니다. 이 매개변수는 코드에서 가져와야 하며, 이번에 보여줄 웹 속도 URL은 https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php입니다. 아래는 이를 얻는 방법 중 하나입니다:

​
간편 방법:

f12를 열고 Element 페이지에서 .execute(를 검색합니다. 빨간 상자 영역에서 action 매개변수를 확인할 수 있으며, execute 뒤에 따라오는 문자열도 필요합니다. 구체적인 내용은 아래 그림과 같습니다.

다음으로는 처리할 인증 코드가 있는 웹사이트의 URL을 입력하면 처리된 결과를 얻을 수 있습니다. 먼저 간단히 website_url 필드를 전달해야 하며, 마지막으로 website_key 매개변수를 입력해야 합니다. 이 내용은 위에서 얻을 수 있으며, execute 뒤에 있는 문자열입니다. 이제 화면에 해당 내용을 입력할 수 있습니다. 아래와 같이 표시됩니다:

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

「Try」 버튼을 클릭하면 테스트를 진행할 수 있으며, 위 그림과 같이 다음과 같은 결과를 얻을 수 있습니다: 
{
  "token": "03AFcWeA5mfdNlQD0RGX9PTWPs0l65QukjwbYObCue5hygRuA6jJmBtwR98S2bmmZOjbLh7ogEMDd8NzJdq8DoHOD_LHIUWmdEL3HJS0pP2nmTTSoU_ltxORWA4sVsrWiXDgkARA4wAhJCegD6PftkRuu0KKbqRsJ7KVKukUbLU1ThBu7P3r0fybwpS11yQmF7xpbEZeFzRm_osERk9tQzs1lEYORZSVA5dimbWi42TqUC87mJHCKO0HMiU404LOyER84It7ne51V5YXEHR_o6-ORr2CmBOawdTDTsqWUwT8vyEvzy-ov-pZdl0B0A_U59_uZd7vbIwv937-iXyzkVWbakUXNMdXlHffpFYd7OLTSBhJu6nasV3IhrbnxO8eGIbPDoHIyGpA74D882ALwTnXMgkcmGeGM9YuqCrf7F06cNKY7yKiisZIU-7v3ZnHV3JUkODGpXQ6dwq2fuP5o6kgeUQVdkv4fAZ_Tx_TB_R6gPSgwulr8Q5hH34bs-v1oUl2S9mLhXT9SWvgYizU_4FN2Ou23ETXTAVD_uI9fWaDgKaLOKI1i-xHCF_LKU3wKjyYJfQhFSCSyoeGL4o1j9lZ27cEHL5AlCm_jcCiXhe2_LT_dI-r5ozuyOGv-iDZ_1XTSSnCGdmroXX56XsZAytU52zBAlYVe_aRAojruc9KdkhK4kdeBESBbDLVe3-jNFwYspe0R93SORxXXIqR9CtZrIjI_2U8XjCHFz_euChdU_wkH5BjvONVbUT1DQNuoo0ugJL5kUkFrubHppOKvoZMwIKjjK_ZX1NBeCvQvYm6IpwBWfvM4hjGI7UVXH3iZkrX9PLATIIIkA8PxTeN45k8DulzOhKLSFKK196fRlH83S8UAaM-vjBxf32Vg83C1gWzKB5sYhxqEtZeB7DNpmAkozFfubljURr7YTjtq8Bgnj0PkfzbgKk8FRl-hMUb9BUjNNuSuFC7GZVim6xQnIV9ZPaAcuzJTYcOizFJePbVEXlc9A5Vq2rDh3D7Ld5o5oqc2kK4eCrO_38le6EVTs_fRY2nXy6RMyjjaJN12lOKYwYzGKhm52gTZTrJXqeTAW8o2KfwZ9iek-tr5qxj5b40iY4V2PY6SflMQvmKLAgFhB-yo-o5PEkikQ98T-bE-wG2-3kd5NRMiD132kIhf48zhVJUGeJqdV_3m8ukyqTk26KisM12kN-h9uYefvUCxzd_mBuWlHzH9rFMlJSe8Z6lcZIVcqNF4fcEM-ukNnwMUK5H_SC48U7O_xfOaEqEpAHDC7CCyVwlGCFh0uAT8KSpaNFfxBmMPXeYrGYn83PCgMg1NZA-7PrpeidXmWdBZ2yY8MA__7uCe8clCmINseBTCIbNmAHPlI_zJKqQfhXaDbaELeD62P0Pquu_SBtdEtqPeB9Esn_yjbK3IFvAaGSnFhwhHHK8dpOI7v-rJvTigPu8MMrEUTvug_zog81kCG8HY3xorTj2OdTwdEYpeMJ1VIHSjdTcnepLB0Cffx5wAdk-gf1TGEnEyTiwII4A4vtq8r0LFK4YObOzNmBTl3IoTNheYYKpheTKH3KShMK6hXDKxDRGEUhdsW4TRtVT-dwJDqY_F7J1RwKP-xDuN98VgwQmQuhJteQUALevgI2jAGFCFfSeFbQ8BOT6ekEI0m30zDX0kh83mkE7-u9qKljYifjqbLarMNPP51QRbvAS3mHlP17PMhIKzjuIka4T2Y9XdRwDgRRdEkYiJgDvkcABTknGBMezraon8JNDRhIJMUIKpidWTdhEQ79qAEfZkowdbnTdKeWeayi1OmV_W4aox-aC62H-VIn70McXXB6zRyYlA2NvTUWgNhHWkSO1SW7uflNEyUeWFRLBZV_firMEVfIGirHOAbQqsn83BirDNPHl4xevf4nRu4gWpgOGBrzeUXQeuMWO4ZFsdWxJ2VsT19t0H5DJtxtHYXFtPZ8tFDFY-r8JKFab4S6e5v8PCrfjCWkPmDaRJal_vLFa1V1dF1l0ARu9NLW4mEuT600azFms8cMlvuCTvWI2VWyn4Wk05UvcR8FYO2-ke4E-ZFRl0jSxjlEutzbOwm2ik4eF0Wh2DBliaSr1obHaxkmLJDUIzGQ3wi49Nyn0SSOdz_BGaxuRrrxCZ4ci0e2b5cxLtkv64Njy7IYJURaBuQk99ijdw7rg3pssAa_uJSMQeZe_kLtgEWF73uT4ceSOFPVuxMGLrJRQTBYxAHVKq7kloS5wtphUr2Sp-b4kezKnCV9HNfC5NRk2KqDT-bkJ6cUYN_0yauyZK1_F4BVTk36IOCe1Cqfe3K-wAZBzvrI_Vz8Li1uEWe0b5KOQ"
}
결과는 여러 필드로 구성되어 있으며, 설명은 다음과 같습니다:
  • token, 이번 Recaptcha3验证码 작업 처리 후의 검증 결과입니다.
우리는 Recaptcha3验证码의 검증 결과를 얻었으며, 이를 POST 또는 GET으로 목표 웹사이트에 제출하는 데 사용할 수 있습니다. 이는 일회용이며 유효 기간은 120초입니다. 60초 이내에 사용하는 것이 좋습니다. 아래는 생성된 token을 목표 웹사이트에 제출하는 방법을 간략히 소개합니다: token 검증에 해당하는 Python 버전 코드 호출: 
import requests

url = "https://recaptcha-demo.appspot.c/recaptcha-v3-verify.php?action=examples/v3scores&token='{token}'"

r = requests.get(url)
if r.status_code == 200:
    return r.text
따라서 우리는 결과를 얻을 수 있습니다: 
{
  "success": true,
  "hostname": "recaptcha-demo.appspot.com",
  "challenge_ts": "2024-09-14T08:52:26Z",
  "apk_package_name": null,
  "score": 0.9,
  "action": "examples/v3scores",
  "error-codes": []
}
여기서 success는 이 검증의 처리 결과를 나타내며, 우리는 Recaptcha3验证码 검증을 성공적으로 통과했습니다. 또한, 해당하는 대체 코드를 생성하고 싶다면, 생성된 코드를 직접 복사할 수 있습니다. 예를 들어 CURL의 코드는 다음과 같습니다: 
curl -X POST 'https://api.acedata.cloud/captcha/token/recaptcha3' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "website_url": "https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php",
  "website_key": "6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9",
  "page_action": "examples/v3scores"
}'
Python의 대체 코드 아래와 같습니다: 
import requests

url = "https://api.acedata.cloud/captcha/token/recaptcha3"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "website_url": "https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php",
    "website_key": "6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9",
    "page_action": "examples/v3scores"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

​
오류 처리

API를 호출할 때 오류가 발생하면, API는 해당 오류 코드와 정보를 반환합니다. 예를 들어:
  • 400 token_mismatched：잘못된 요청, 누락되었거나 잘못된 매개변수 때문일 수 있습니다.
  • 400 api_not_implemented：잘못된 요청, 누락되었거나 잘못된 매개변수 때문일 수 있습니다.
  • 401 invalid_token：권한 없음, 잘못되었거나 누락된 인증 토큰입니다.
  • 429 too_many_requests：요청이 너무 많음, 비율 제한을 초과했습니다.
  • 500 api_error：내부 서버 오류, 서버에서 문제가 발생했습니다.

​
오류 응답 예시

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
결론

이 문서를 통해 Recaptcha3 프로토콜을 사용하여 API를 통해 사용자가 Recaptcha3 인증 이미지의 인식 및 클릭 없이 Website Key를 제출하여 백그라운드에서 자동으로 디코딩하고 인증을 완료할 수 있는 방법을 이해하셨습니다. 이 문서가 API를 더 잘 연결하고 사용하는 데 도움이 되기를 바랍니다. 질문이 있으시면 언제든지 기술 지원 팀에 문의해 주십시오.