> ## 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. # Recaptcha3 Протокол распознавания API Инструкция по интеграции > Recaptcha verification code recognition service API guide - Ace Data Cloud В данной статье будет представлена инструкция по интеграции API распознавания протокола Recaptcha3, которая позволяет пользователям не распознавать и не нажимать на изображения капчи Recaptcha3, а просто отправить Website Key для автоматической декодировки на сервере и завершения проверки. ## Процесс подачи заявки Чтобы использовать API распознавания протокола Recaptcha3, сначала перейдите в [консоль 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 распознавания протокола Recaptcha3 →](https://platform.acedata.cloud/documents/captcha-token-recaptcha3) ## Основное использование Сначала ознакомьтесь с основными способами использования. В отличие от Recaptcha2, нам нужно дополнительно передать параметр `page_action`, который необходимо получить из кода. URL для демонстрации скорости сети: `https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php`, ниже представлен один из способов его получения: ### Упрощенный метод: Откройте f12, затем на странице Element выполните поиск по `.execute(`, в красной рамке мы можем увидеть параметр `action`, а также за ним следует строка, которая также потребуется далее, конкретно это показано на изображении ниже.

Затем необходимо ввести URL сайта, на котором нужно обработать капчу, чтобы получить обработанный результат. Сначала нужно просто передать поле `website_url`, а затем также ввести параметр `website_key`, который можно получить выше, это также строка, следующая за execute. Далее мы можем заполнить соответствующие поля на интерфейсе, как показано на изображении:

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

Нажмите кнопку «Try», чтобы провести тестирование, как показано на изображении выше, здесь мы получили следующий результат: ```json theme={null} { "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 секунд. Далее будет кратко описан один из способов отправки сгенерированного токена на целевой сайт: Вызов кода на Python для проверки токена: ```python theme={null} 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 ``` Таким образом, мы можем получить результат: ```json theme={null} { "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 выглядит следующим образом: ```shell theme={null} 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 выглядит следующим образом: ```python theme={null} 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) ``` ## Асинхронный режим (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/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", "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": "03AFcWeA5mfdNlQD0RGX9PTWPs0l65QukjwbYObCue5hygRuA6......" } ``` Условия оплаты: в асинхронном режиме создание задачи и опрос «в процессе обработки» не подлежат оплате; **оплата производится только один раз при успешном получении результата** (по цене, аналогичной синхронному режиму). Поэтому отмена незавершенных задач в ротации не приведет к расходам. `/captcha/tasks` универсален для всех интерфейсов капчи (серии token и 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" } ``` ## Заключение С помощью этого документа вы узнали, как использовать API для распознавания протокола Recaptcha3, позволяя пользователям не распознавать и не нажимать на изображения капчи Recaptcha3, а просто отправив Website Key, чтобы реализовать автоматическую декодировку на сервере и завершить проверку. Надеемся, что этот документ поможет вам лучше интегрировать и использовать этот API. Если у вас есть какие-либо вопросы, пожалуйста, не стесняйтесь обращаться в нашу техническую поддержку.