> ## 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. # Recaptcha2 протокол розпізнавання API інтеграція > Recaptcha verification code recognition service API guide - Ace Data Cloud У цьому документі буде представлено опис інтеграції API розпізнавання протоколу Recaptcha2, який дозволяє користувачам не розпізнавати та не натискати на зображення коду Recaptcha2, а лише подати Website Key для автоматичного декодування на бекенді та завершення перевірки. ## Процес подачі заявки Щоб використовувати API розпізнавання протоколу Recaptcha2, спочатку перейдіть до [консолі 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). > 📘 Повна документація: [API розпізнавання протоколу Recaptcha2 →](https://platform.acedata.cloud/documents/captcha-token-recaptcha2) ## Основне використання Спочатку розгляньте основний спосіб використання, а саме введіть URL сайту, на якому потрібно обробити код, і ви отримаєте оброблений результат. Спочатку потрібно просто передати поле `website_url`, наш приклад сайту: `https://www.google.com/recaptcha/api2/demo`, нам потрібно отримати `website_key` на сторінці `website_url`, спочатку відкрийте цю веб-сторінку, натисніть F12 для входу в консоль, а потім у вкладці Element виконайте глобальний пошук за `recaptcha-demo`, ми можемо отримати наступний результат:

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

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

Натисніть кнопку «Спробувати», щоб провести тестування, як показано на малюнку, тут ми отримали наступний результат: ```json theme={null} { "token": "03AFcWeA5kjJyDQ9S1a9UYimR6nuxnpEnAs5x2Pixao0dXZhMBjiR2MwAwN7K3NXik02Vl--cEmCwxDuf7mNBMbGlfLHb5948cvCdk1jnp_mjbWzT9ZyxzSnny52TiWVZo1xvTTad5QIQz9iRfJrjcM1BkBj5OpwT4mRVK-Yoz8Q8m5MlXEwQ5Zyp0Lxh_L-32EkdwyyCIOlG-Q1wJ-lR7utNB6E8MCrtTM1tox75-3KPvMNHbTjvqSf1l3FO_bASk39mtleI_NjThAPHCBL__cHu2wJxRYITYxqYgCu3FYcmC3OfcUJJEmgg4KEpQTIjo1X2N1m81obHWKrOrrNqfQvELnXrhHU4gVcFwpaMladoLysqOrDqHsYxNeUTp5YiEu6_Xl2eC6r9IKTbeddIf5QXQML_OILc4Ee3-vEUepmelWq7GE4wOKf8zQ8Xfz1MbJM3daEmiVEMFs4EQsjGgioPeyQUjiJT5U2sZfiJbgyGdUVletCBn4abnSLBYVI-rKKlETKu4IQVGCmh_hNn7cnkX3E5p_Kqu3gifOYHSbCu2ctuaPe9G3M8XxbQ57b_UFgg1MMToSAcZDL2NWtL4yPag5Y4lCnpmfrGOwvX-QFF0JF-DrbRn_Opv52JrLD9GrfGxo99kiucQIZkAzpWLV3Kkhtep2DB8OiA4rSb5R6xT4nNoawg1BM2cM5jazL-1U6LzSs9Hq1XWV1nwj-8-mTDwHmBYMI6fmSfl1-bOX0uHGgWHnzEAW2mw4EErVVUTUJJcUr_LZ2woRkexk-CPQTtdlHmQHbt_1FsOzfGtnXY87xIbhCJReVyv-_HQ48d9xCDuQ-JnNjX98NfDsfvpxe9Zar_LjcQCBNtvHgKH_JkniBDiWrZBAoDJIonDjJ6X1mmWLyPDxYmBR6O7QkxR3DxdDvZQRaZnfD-_sA9T9JEkYWHdBlpumEBq9wVs8dSm60TiRAOZU1ZLjieGP5vI5_aV-ct5SwOmWHF-VQkJUfNZ33MoEkZW2Rvh7_ERbI_PRS_u65BCkhuOh8fmQcxJU5YACpoLXXkwGM8qmSB1yBBeOQL-wWUfo8GREpZIu1oGQVQ8k3FcNJzFQQAYcLBWfGn-8qMxfAJEd356lJYIUuU1CY2rhR1u_7C1R_bH0WTifDqYLCRGzn-tzqBOXybrkOs_KURL-gT6wAoZRpUvBBAEa1mRg5gxap0pOkpdf7MPb5PsWVME7E3stvordioyN2tdLKr6VC-0kiQZD1WzykazPZzkl302Y_kpQ2vKPawWVWmNhy5Vm_cwT6afOAuSHnU1aYtFNvEDpBcXXH2YcqS-sBnMb3KlO5KpfZSp-tGzvjds46ajyoD7bHGzxvCx9EplICVrGWQ8gRYe2MCVJ3OocE-VK7PxI1iKXJK_LBl4hQR7uUKaDVEbmBYMcgS1z5YmXbJV89yjrU-u5ncTn5JkJgoSdOvMi8l2fsZIl2wYi-hWgQjP6LLI6M6wr8AhyiSZBQ34adR07niQPzLfX5Ntwr_8NyMg69bWKlLXknv8O2KznYXQQwsWA3okJCGwhfJkp35QnkHsprTN9LD48cwg8zP7a1mgM-2WHuZmoCpqg1XJgT_tPjc7X9kCQt8e3YirW6IJs-CdBUDkbp12FCukip48mDz7SOWjnLruoNABfo_zCurdOQY_tfcWe4g_ef0y_vey3hLGvxuay_ZMGzDLIo-7_WEp7jU09YKqWOZV7cSxDPm65M1v69ND6b5awsopISEe7E3hKMGrVSonRa9_bkiQ2fuPa5-xitNr4IMxwWMepqDk54v_cyVzUBdAAq8V8w3VHvV4-tjTXFqp0L54RBhJ_EaCXO7nwNbVLqCirfDpKRASfkYoaqsoXbwFMpfFrh-KzDZVIuU6D-VBF5k50ufGPnoXTA8kIF0GjAepW5SCxYupoQos4La6W2f--cl4WAl8oKhSpFtRpb1CNMKmtD7_BJrPDxpnXiA-ENBFe8Y4EOoG5uavVeQl6YftHej52JOTKurOqD-NE-UDBLInNuOo0ayCdV1w8XDAnORgxbkYP65GO5FdytK4zrDVNQEK26D54e0xLpDqUG8UUmUT_VNj9UY78WyWGPTXiGwYAA2_iVUKbT8-phHLDDqeoG3Q5iTP7RUpaW49JmM-tlSeczqqyy9Wc8iZh2Cf9veRJ7HiUeIEMeKGnqD7E9nXxcjC75GzIo477c83U7QN_1QXQjWuAr0C3KFq2W7dJmO08pQ0Z13dG7tz4Ilg1Bc3LIcNgeJLkCTZYpDpn7JpeZRbe6fqvmbqWPQ" } ``` Результат повернення містить кілька полів, описаних нижче: * `token`, результат обробки завдання Recaptcha2. Можна побачити, що ми отримали результат перевірки Recaptcha2, який можна використовувати для POST або імітації відправки на цільовий сайт, одноразового використання, термін дії 120 секунд, рекомендується використовувати протягом 60 секунд. Далі буде надано фрагмент Python, який відправить оброблений токен на цільовий сайт для проходження Recaptcha2. Спочатку потрібно дізнатися, як сайт надсилає POST запит, щоб ми могли передати згенерований токен. Для цього потрібно відкрити консоль F12, а потім вручну пройти перевірку. В результаті ми побачимо, що сайт надіслав POST запит, і нам потрібно лише переглянути конструкцію цього POST запиту. Конкретний процес виглядає так: * Спочатку вручну пройти перевірку, деталі наведені на малюнку нижче:

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

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

Згідно з наведеним зображенням, URL для цього POST запиту: `https://www.google.com/recaptcha/api2/demo`, нам потрібно лише надіслати параметр `g-recaptcha-response`, після чого ми просто передаємо оброблений токен у нижче наведених даних, код CURL для виклику токена для перевірки виглядає так: ```shell theme={null} curl 'https://www.google.com/recaptcha/api2/demo' \ --data-raw 'g-recaptcha-response={token}’ ``` Код на Python для виклику перевірки токена виглядає так: ```python theme={null} import requests token = '{token}' data = { 'g-recaptcha-response': token, } response = requests.post('https://www.google.com/recaptcha/api2/demo',data=data) if response.status_code: print(response.text) ``` Після цього ми запускаємо код і спостерігаємо, що консоль показує такий результат:

Врешті-решт, ми пройшли перевірку протоколу Recaptcha2. Крім того, якщо ви хочете згенерувати відповідний код для інтеграції, ви можете просто скопіювати його, наприклад, код CURL виглядає так: ```shell theme={null} curl -X POST 'https://api.acedata.cloud/captcha/token/recaptcha2' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "website_key": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-", "website_url": "https://www.google.com/recaptcha/api2/demo" }' ``` Код інтеграції на Python виглядає так: ```python theme={null} import requests url = "https://api.acedata.cloud/captcha/token/recaptcha2" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "website_key": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-", "website_url": "https://www.google.com/recaptcha/api2/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`, не блокуючи очікування: ```shell theme={null} curl -X POST 'https://api.acedata.cloud/captcha/token/recaptcha2' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "website_key": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-", "website_url": "https://www.google.com/recaptcha/api2/demo", "async": true }' ``` ```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": "03AFcWeA5kjJyDQ9S1a9UYimR6nuxnpEnAs5x2Pixao0dXZhMB......" } ``` Опис тарифікації: в асинхронному режимі створення завдання та опитування «в обробці» не підлягають тарифікації; **тільки при успішному отриманні результату стягується плата один раз** (з ціною, що відповідає синхронному режиму). Тому скасування незавершених завдань під час ротації не призведе до витрат. `/captcha/tasks` є універсальним для всіх інтерфейсів перевірки (серії токенів та розпізнавання), можна використовувати один і той же `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" } ``` ## Висновок Завдяки цьому документу ви дізналися, як використовувати API для розпізнавання протоколу Recaptcha2, щоб користувачі не повинні були розпізнавати та натискати на зображення з капчею Recaptcha2, а лише подавати Website Key для автоматичного декодування на задньому плані, завершуючи перевірку. Сподіваємося, цей документ допоможе вам краще інтегрувати та використовувати цей API. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої технічної підтримки.