hCaptcha протокол розпізнавання API інтеграція

У цьому документі буде представлено опис інтеграції hCaptcha протоколу розпізнавання API, який дозволяє користувачам не розпізнавати та не натискати на зображення hCaptcha, а лише подавати Website Key для автоматичного декодування в бекенді та завершення верифікації.

Процес подачі заявки

Щоб використовувати hCaptcha протокол розпізнавання API, спочатку перейдіть до консолі Ace Data Cloud для отримання вашого API Token, зберігайте його для подальшого використання.

Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, щоб запросити реєстрацію та вхід, після чого ви будете автоматично повернені на цю сторінку. Один API Token дозволяє викликати всі послуги платформи, не потрібно окремо подавати заявку на кожну послугу. Перший запит на отримання токена надає безкоштовний ліміт для тестування; при недостатньому ліміті ви можете поповнити загальний баланс у консолі.

📘 Повна документація: hCaptcha протокол розпізнавання API →

Основне використання

Спочатку розгляньте основний спосіб використання, а саме введіть URL сайту, на якому потрібно обробити hCaptcha, і ви отримаєте оброблений результат. Спочатку потрібно просто передати поле website_url, наш приклад сайту: https://accounts.hcaptcha.com/demo, нам потрібно отримати website_key на сторінці website_url, спочатку відкрийте цю веб-сторінку, натисніть F12 для входу в консоль, а потім у вкладці Element виконайте глобальний пошук за hcaptcha-demo, ми можемо отримати наступний результат:

Тут data-sitekey відповідає рядку, який є значенням website_key, нижче наведені конкретні результати параметрів:

Ми можемо бачити, що тут ми налаштували заголовки запиту, включаючи:

accept: який формат відповіді ви хочете отримати, тут вказано application/json, тобто формат JSON.
authorization: ключ для виклику API, після подачі заявки ви можете вибрати його зі списку.

Також налаштовано тіло запиту, яке включає:

website_url: URL сайту, на якому потрібно обробити капчу.
website_key: ідентифікатор сайту в hCaptcha.
rqdata: необов’язковий. Виклик hCaptcha Enterprise може надати data-rqdata на сторінці, у разі таких викликів заповніть його початкове значення; звичайна hCaptcha не потребує заповнення.
proxy: необов’язковий, використовуйте свій проксі (Bring Your Own Proxy). Після налаштування система буде використовувати наданий вами проксі IP для розв’язання капчі, щоб контролювати якість вихідного IP (наприклад, уникнути блокування цільовим сайтом через публічний проксі IP, що призводить до повернення 410 Gone). Формат: scheme://[user:pass@]host:port, scheme підтримує http/https/socks4/socks5, наприклад, http://user:pass@1.2.3.4:8080. Якщо не заповнити, буде використано проксі за замовчуванням платформи.

Після вибору ви також можете помітити, що з правого боку згенеровано відповідний код, як показано на малюнку:

Натисніть кнопку «Спробувати», щоб провести тестування, як показано на малюнку, тут ми отримали наступний результат:

{
  "token": "P1_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.hadwYXNza2V5xQda4nQzFgUbYJqILiiwbvyhjocSilg8RjFHvIHmCzmqUNZa9hesIWEVRx5KIbMVeAQzSTWCwXmiQrPZuIEmZz-ZPL6DPNmB3ZXtJNsVYRLdRyvWPTB7EYskJG85yDVor2TcgQFNqAahhKT3WXjtk3S54ZBhv7QvaImUmos8MWgUOvUZHsvUtojN-izWIrBkD1if_71quOHvcvEVTLcSLx9dOgzpNAJ8_6BmJEsGlPbMGnSKrS1QfpPyzvgrnpjjIY_6TMYwJrR0EwJgCdp_lfc4mkxl0NJsZt8D_q7jcv3v6jt1CZ2qbqF5_-i4y0MYnQMCm1T62xBPdiEyst_FtGuWxJllkrrmWN0edyWcWeasLcCS6qpRry0H7RU7DYQnML6dmQoZg15NT0tFrAYeLK7EwvJxzcFbvUQ-Tc5QVk7tzvKpDtUVfQeZmRRgxWbCFf6bAT1z0uUwdma1O1lcTkSZCC5cVTaprkkKE04Ov4aCIKg2N7WGj4r0AOykisAISX5oidF3gejDTJy9vU1hgaCYFOimnwRKyqRsJdznptzhzDOQuICuAHYT3is1sY26ltJGOZTdDKkt2i2owCoAylgLbBP8VjTOGrsM12IH3Xsy076O40RCG6zThWN5TFKSpl7PNA6l2KoW-P3_K9WORjx2DSvKTAwqcouSU-0Rc_8Hlq9cIuS1iDhiNfJnJ_zNy_2gXSR2j7NP7m_lsfwELKypKm6pPzIhOuz5RwPotfPQfXOMdF3Xy98iQiihZmuHENvLAhjV_W7NL9TK3THPwDTFriS8ghIncl02v-fVARXDiuFTvjjlegL7xbHgIrOhLpunsxLiwdImUWatEI9jqaf84X4BtoS0TGYo4pHkpIG10dhoz3vooeSToAws6tz7ZWSHm6naksZ41X_WIxd7N8P9yzxrbLgVv-nHia5qHQLDmiZf3alITKhtisennw8NpespaQIVZzw_B16bdUNKqHCCTLdFbr16-3KpRoHzOOU2kBhV-gDN0NiA3ecqIMnyMdnpKlUpnjJ5sMA3e0pKEX_Vbu8DE8zfkcwLIwCIb2BLrKEHnCvv4JX8TfBktzMc5oTtZyEu-E_6ew0mSm_nhVsGtmLXSsB81FP9VGGRd50buIXRNW4GFp3XdTmYyuN32kc-AHJ5kKDj2HGraHxKco0McT7nV2bgx97k-C7hgxL2x5t3lC97edphh2kt2-gXuTxxfB7K-ZG6w5d1MnRte4ZG7TxvPFFi5693IFRFbvcr-U3WyGZJmGGdfV55PnoIU9Qn-WDtBU4EXyvd_KTt-asHtI6VQiVSNzacemTfsu9WBF33f2gafDY4qqhyXDPNsu6BZCGMSBhxDPURY74OBr4mYOdhjELY07nSkr9RQtQwiiSa8B8XFlezCPafjgdbmmNzG3PXa3n23sSwVnJHpHhq79eTP_KeeCiqlCvNsHLEfiH5HCNRGp7v5b342wBk__BWFimJMvohz0rucTVYgVFBdTOomUTuqCPeUgDP3X6BnNqyVDRA-HrdRl-RkU6mnw-3-IwyMZQ-fEnFMzbGp3zaoY7Do2jKvKKILoq6Q8zlDYkrLwuXjDP-nernI2hxP9wVOUVmtq5Rs19RLUI4MNWZAqwG-wGnaoB756d8nfmh5XhFzvArE5bpL50FY1yJqv7nbPW7JNnkfZG80yVRrIZO_F9NEb3n4eiIzg9Gu9fv8ncyChiCCp-swK5B7_w-XsAlco98bO-YK-fFMJOhyt0PU8Zc-hYoCa6cLVTvhdPzIUA0CQOemg4Pz6PX6SVwLYSlOXYkzbrgBlyH5YBS3oaRCeavVLrJsKt0_KwHwgBa1mdP5mlYUpBDbKR4PKwknU7y111JH0B4fO39dOVA-zecvDG0bnuy98Jym4KUchZr1tXabMcM20mg1UvcxMfnKOx0ojBcVwYA7kPQK3EzMnwX9NbAzYP6IlMgjFK9ZM7HCXxN6J1_6kw10RT4O58-Pbh3cMSrZDfM-GuG7p7XrVpJrX8TD195DCJqx-DmVv3Bs3CiuCPTvGrSZ58KE4hQagidGreUD2WXxLBFfTv1RgM3eXMtROs7hddyBajIu401lxucNbpRB7lYV7pJwxG7LQoSZ2G2LzG8eFPVPIkDNVOa8nGzh-sWaF7kc7bVv-P4FXbLX0WCjvQRES2MCbXPyJ-OpZZXZcJy7SOsGY3jZbTkGoez19cRQLiFO35gA5l9FBptDKW-_yGemt5XeKsR_FwGPN9C-0k1E-28oB4iKo-h1zb2kJpilhnmG36Z59F5T6W77M7OD_N6VHRWuPClLElO09OrPLHbJmxq9JvMWjTg5JjEaqyTLyLXWgw0N3kZMCqJJeqNj5w5I7dpuJ6ScfXKVaT96v2UESebdbMFT7vkZAkFF8LIowkN56pNwXLHkB2KyIWR2WQL-335BEpQ0AVB6RX4kdociIhtvAdsIE6pvFIwkzyO0OvIHxzOwPxZKdmDmBVMu7YxJStrhY-XWCu4kO5gDIJ0iedPWKNleHDOZuZqGKhzaGFyZF9pZM4xrUyBomtyqDE1ZmUwNDhkonBkAA.dVWyVc6N3lx2ZJQ7NJ9aEsWA-KAIuQ4PMSKVGQuWyCA",
  "elapsed": 31.6
}

Можна побачити, що ми отримали результати обробки hCaptcha CAPTCHA, а потім можемо використовувати їх для POST або імітації подання на цільовий веб-сайт, одноразового використання, термін дії 120 секунд, рекомендується використовувати протягом 60 секунд. Далі буде надано фрагмент CURL версії, щоб подати оброблений токен на цільовий веб-сайт для проходження Recaptcha2 CAPTCHA. Спочатку нам потрібно дізнатися, як веб-сайт надсилає POST запит, щоб ми могли передати згенерований токен. Спочатку відкриваємо консоль F12, потім вручну проходимо перевірку, в кінці ми можемо побачити, що веб-сайт надіслав POST запит, нам потрібно лише переглянути конструкцію цього POST запиту, конкретний процес виглядає так:

Спочатку вручну проходимо перевірку, конкретно, як на зображенні нижче:

Потім натискаємо submit, спостерігаємо за змінами в мережі консолі, конкретно, як на зображенні нижче:

Аналізуємо конструкцію цього POST запиту, в кінці можемо клацнути правою кнопкою миші на цьому запиті та скопіювати код CURL, конкретно, як на зображенні нижче:

З аналізу зображення видно, що URL цього POST запиту: https://accounts.hcaptcha.com/demo, нам потрібно лише подати параметри g-recaptcha-response, h-captcha-response та email, потім ми просто передаємо оброблений токен у нижче data, виклик CURL коду для перевірки токена виглядає так:

curl 'https://accounts.hcaptcha.com/demo' \
  --data-raw 'email=&g-recaptcha-response={token}&h-captcha-response={token}'

Виклик коду Python для перевірки токена виглядає так:

import requests

token = '{token}'

data = {
    'email': '',
    'g-recaptcha-response': token,
    'h-captcha-response': token
}

response = requests.post('https://accounts.hcaptcha.com/demo',
                        data=data)

if response.status_code == 200:
    print(response.text)

Потім ми спостерігаємо, що консоль отримала такий результат:

Врешті-решт, ми пройшли перевірку hCaptcha. Крім того, якщо ви хочете згенерувати відповідний код інтеграції, ви можете просто скопіювати його, наприклад, код CURL виглядає так:

curl -X POST 'https://api.acedata.cloud/captcha/token/hcaptcha' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "website_key": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
  "website_url": "https://accounts.hcaptcha.com/demo"
}'

Код інтеграції на Python виглядає так:

import requests

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

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

payload = {
    "website_key": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
    "website_url": "https://accounts.hcaptcha.com/demo"
}

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

Асинхронний режим (async)

За замовчуванням API є синхронним блокуючим: один запит буде чекати, поки обробка токена не завершиться, перш ніж повернути результат. Якщо ви займаєтеся ротацією кількох рішень (multi-solver rotation) і хочете «після подання завдання відразу отримати task_id, спочатку перейти до інших рішень, а потім повернутися, щоб прочитати результат», ви можете передати async: true у тілі запиту. Після передачі async: true інтерфейс відразу поверне task_id, не блокуючи очікування:

{
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab"
}

Якщо потрібно активно перевірити прогрес, можна використовувати цей task_id для запиту POST /captcha/tasks (рекомендується кожні 3-5 секунд). Цей інтерфейс не буде ініціювати або просувати обробку завдання; навіть якщо не запитувати, відключити інтернет або вийти з клієнта, сервер все ще продовжить обробку:

curl -X POST 'https://api.acedata.cloud/captcha/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002"
}'

Під час обробки буде повернуто status: processing:

{ "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "status": "processing" }

Після завершення обробки буде повернуто status: ready та токен:

{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "ready",
  "token": "P1_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1Ni......"
}

Опис тарифікації: в асинхронному режимі створення завдання та читання статусу «в обробці» не тарифікуються; клієнт сплачує один раз при першому успішному читанні результату (як і в поточній поведінці та ціні синхронного режиму). Сервер самостійно просуває завдання, але не стягує плату за те, що завдання завершилося раніше в фоновому режимі. Якщо завдання не буде успішно завершено протягом 120 секунд, воно буде зупинено з HTTP 504 timeout, без тарифікації. /captcha/tasks не відповідає за просування завдання.

Обробка помилок

При виклику 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"
}

Висновок

Завдяки цьому документу ви дізналися, як використовувати API для розпізнавання hCaptcha, щоб користувачі не повинні були розпізнавати та натискати на зображення hCaptcha CAPTCHA, а лише подавати Website Key для автоматичного декодування на сервері, завершуючи перевірку. Сподіваємося, що цей документ допоможе вам краще інтегрувати та використовувати цей API. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої технічної підтримки.

Getting Started

AI Чат

AI Зображення

AI Відео

AI Аудіо

Веб і дані

CAPTCHA

Ідентичність

Проксі

Advanced

Coding

hCaptcha протокол розпізнавання API інтеграція

Процес подачі заявки

Основне використання

Асинхронний режим (async)

Обробка помилок

Приклад відповіді з помилкою

Висновок

​Процес подачі заявки

​Основне використання

​Асинхронний режим (async)

​Обробка помилок

​Приклад відповіді з помилкою

​Висновок

Процес подачі заявки

Основне використання

Асинхронний режим (async)

Обробка помилок

Приклад відповіді з помилкою

Висновок