> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # hCaptcha протокол розпізнавання API інтеграція > hCaptcha verification code recognition service API guide - Ace Data Cloud У цьому документі буде представлено опис інтеграції hCaptcha протоколу розпізнавання API, який дозволяє користувачам не розпізнавати та не натискати на зображення hCaptcha, а лише подавати Website Key для автоматичного декодування на бекенді та завершення верифікації. ## Процес подачі заявки Щоб використовувати hCaptcha протокол розпізнавання API, спочатку перейдіть до [консолі Ace Data Cloud](https://platform.acedata.cloud/console/applications) для отримання вашого API Token, зберігайте його для подальшого використання. ![](https://cdn.acedata.cloud/5hmkdg.jpg) Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, запрошуючи вас зареєструватися та увійти, після чого ви автоматично повернетеся на цю сторінку. **Один API Token дозволяє викликати всі послуги платформи, не потрібно окремо подавати заявку на кожну послугу.** Перший запит на отримання токена надає безкоштовний ліміт, щоб ви могли безкоштовно протестувати; при недостатньому ліміті ви можете поповнити загальний баланс в [консолі](https://platform.acedata.cloud/console/coin). > 📘 Повна документація: [hCaptcha протокол розпізнавання API →](https://platform.acedata.cloud/documents/captcha-token-hcaptcha) ## Основне використання Спочатку розглянемо основний спосіб використання, а саме введення URL сайту, на якому потрібно обробити hCaptcha, щоб отримати оброблений результат. Спочатку потрібно просто передати поле `website_url`, наш приклад сайту: `https://accounts.hcaptcha.com/demo`, нам потрібно отримати `website_key` на сторінці `website_url`, спочатку відкрийте цю веб-сторінку, натисніть F12 для входу в консоль, а потім у вкладці Element виконайте глобальний пошук за `hcaptcha-demo`, ми можемо отримати наступний результат:

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

Ми можемо бачити, що тут ми налаштували Request Headers, включаючи: * `accept`: який формат відповіді ви хочете отримати, тут вказано `application/json`, тобто формат JSON. * `authorization`: ключ для виклику API, після подачі заявки ви можете вибрати його зі списку. Також налаштовано Request Body, включаючи: * `website_url`: URL сайту, на якому потрібно обробити капчу. * `website_key`: ідентифікатор сайту в hCaptcha. Після вибору ви можете помітити, що праворуч також згенеровано відповідний код, як показано на малюнку:

Натисніть кнопку «Спробувати», щоб провести тестування, як показано на малюнку, тут ми отримали наступний результат: ```json theme={null} { "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" } ``` Можна побачити, що ми отримали результати обробки hCaptcha CAPTCHA, після чого ми можемо використовувати їх для POST або імітації відправки на цільовий сайт, одноразового використання, термін дії 120 секунд, рекомендується використовувати протягом 60 секунд. Далі буде надано фрагмент CURL версії, який відправляє оброблений токен на цільовий сайт для проходження Recaptcha2 CAPTCHA. Спочатку нам потрібно дізнатися, як сайт надсилає POST запит, щоб ми могли передати згенерований токен. Для цього потрібно відкрити консоль F12, а потім вручну пройти перевірку, в результаті чого ми можемо побачити, що сайт надіслав POST запит. Нам потрібно лише переглянути конструкцію цього POST запиту, конкретний процес виглядає так: * Спочатку вручну пройдіть перевірку, конкретно, як на зображенні нижче:

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

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

З аналізу зображення видно, що URL цього POST запиту: `https://accounts.hcaptcha.com/demo`, нам потрібно лише надіслати параметри `g-recaptcha-response`, `h-captcha-response` та `email`, після чого ми можемо передати оброблений токен у нижче наведених даних, виклик CURL коду для перевірки токена виглядає так: ```shell theme={null} curl 'https://accounts.hcaptcha.com/demo' \ --data-raw 'email=&g-recaptcha-response={token}&h-captcha-response={token}' ``` Виклик коду Python для перевірки токена виглядає так: ```python theme={null} 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 виглядає так: ```shell theme={null} 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 виглядає так: ```python theme={null} 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`, не блокуючи очікування: ```json theme={null} { "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab", "status": "processing" } ``` Потім використовуйте цей `task_id` для опитування `POST /captcha/tasks` (рекомендується кожні 3-5 секунд), щоб отримати результат: ```shell theme={null} 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`: ```json theme={null} { "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "status": "processing" } ``` Після завершення обробки буде повернуто `status: ready` та токен: ```json theme={null} { "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "status": "ready", "token": "P1_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1Ni......" } ``` Опис тарифікації: в асинхронному режимі створення завдання та опитування «в обробці» не тарифікуються; **тільки при успішному отриманні токена тарифікується один раз** (з ціною, що відповідає синхронному режиму). Тому скасування незавершених завдань під час ротації не призведе до витрат. `/captcha/tasks` є загальним для всіх інтерфейсів CAPTCHA (серії токенів та розпізнавання, такі як hcaptcha, recaptcha2, recaptcha3, recognition/\* тощо), можна використовувати один і той же `task_id` для опитування. ## Обробка помилок При виклику API, якщо виникає помилка, API поверне відповідний код помилки та інформацію. Наприклад: * `400 token_mismatched`: Неправильний запит, можливо, через відсутні або недійсні параметри. * `400 api_not_implemented`: Неправильний запит, можливо, через відсутні або недійсні параметри. * `401 invalid_token`: Неавторизовано, недійсний або відсутній токен авторизації. * `429 too_many_requests`: Занадто багато запитів, ви перевищили ліміт запитів. * `500 api_error`: Внутрішня помилка сервера, щось пішло не так на сервері. ### Приклад відповіді з помилкою ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Висновок Завдяки цьому документу ви дізналися, як використовувати hCaptcha протокол для розпізнавання API, щоб користувачі не потребували розпізнавання та натискання на зображення hCaptcha CAPTCHA, а лише через подання Website Key могли реалізувати автоматичне декодування на задньому плані, завершуючи перевірку. Сподіваємося, що цей документ допоможе вам краще інтегрувати та використовувати цей API. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої технічної підтримки.