Skip to main content
В этой статье будет представлена инструкция по интеграции API распознавания протокола Cloudflare Turnstile, которая позволяет пользователям обойтись без распознавания и нажатия на капчу Turnstile, просто отправив Website Key для автоматической декодировки на сервере и завершения проверки.

​
Процесс Заявки

Чтобы использовать API распознавания протокола Cloudflare Turnstile, сначала перейдите в консоль Ace Data Cloud и получите ваш API Token для резервного копирования. Если вы еще не вошли в систему или не зарегистрированы, вы будете автоматически перенаправлены на страницу входа, где вас пригласят зарегистрироваться и войти. После завершения вы будете автоматически возвращены на текущую страницу. Один API Token позволяет вызывать все сервисы платформы, не нужно запрашивать отдельный токен для каждого сервиса. При первом запросе предоставляется бесплатный лимит для тестирования; если лимит исчерпан, вы можете пополнить общий баланс в консоли.
📘 Полная документация: Cloudflare Turnstile Протокол Распознавания API →

​
Основное Использование

Сначала ознакомьтесь с основным способом использования, который заключается в вводе URL сайта, на котором необходимо обработать капчу Turnstile, чтобы получить обработанный результат. Сначала нужно просто передать поле website_url, наш пример сайта: https://react-turnstile.vercel.app, нам нужно получить website_key на странице website_url. Для этого откройте эту веб-страницу, нажмите F12 для входа в консоль, выполните глобальный поиск по элементам на странице cf-turnstile, и вы найдете контейнерный элемент, содержащий Turnstile, где строка, соответствующая data-sitekey, является значением website_key. Установленные заголовки запроса включают:
  • accept: формат ответа, который вы хотите получить, здесь укажите application/json, то есть формат JSON.
  • authorization: ключ для вызова API, который можно выбрать из выпадающего списка после запроса.
Также установленное тело запроса включает:
  • website_url: URL сайта, на котором необходимо обработать капчу.
  • website_key: идентификатор сайта (sitekey) в Cloudflare Turnstile.
  • action: необязательный параметр, который нужно передавать только если целевой сайт настроил пользовательский action для компонента Turnstile.
  • cdata: необязательный параметр, который нужно передавать только если целевой сайт настроил пользовательский cData для компонента Turnstile.
Нажмите кнопку «Попробовать», чтобы провести тестирование, и мы получим следующий результат:
Возвращаемый результат содержит несколько полей, описание которых приведено ниже:
  • token: результат проверки после обработки задачи капчи Cloudflare Turnstile.
  • started_at, finished_at: время начала обработки запроса и получения результата, Unix временная метка (секунды, с плавающей точкой).
  • elapsed: общее время обработки (секунды).
Мы видим, что получили результат проверки капчи Turnstile, который затем можно использовать для POST или имитации отправки на целевой сайт, одноразовое использование, срок действия 120 секунд, рекомендуется использовать в течение 60 секунд. При отправке обычно этот токен передается как параметр cf-turnstile-response на целевой сайт, код Python для вызова проверки токена приведен ниже:
Если вы хотите сгенерировать соответствующий код интеграции, вы можете просто скопировать его, например, код CURL будет следующим:
Код интеграции на Python будет следующим:

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

По умолчанию API является синхронным и блокирующим: один запрос будет ждать, пока токен не будет обработан, прежде чем вернуться. Если вы делаете многократную ротацию кодов (multi-solver rotation) и хотите «получить task_id сразу после отправки задачи, чтобы сначала переключиться на другие кодеры, а затем вернуться за результатом», вы можете передать async: true в теле запроса. После передачи async: true интерфейс немедленно вернет task_id, не блокируя ожидание:
Если вы хотите активно отслеживать прогресс, вы можете использовать этот task_id для запроса POST /captcha/tasks (рекомендуется каждые 3-5 секунд). Этот интерфейс не будет инициировать или продвигать обработку задачи; даже если вы не запрашиваете, теряете соединение или выходите из клиента, сервер продолжит обработку:
Во время обработки будет возвращен status: processing; по завершении обработки будет возвращен status: ready и токен:
Условия оплаты: в асинхронном режиме создание задачи и чтение статуса «в обработке» не подлежат оплате; клиент оплачивает один раз при первом успешном чтении результата (что соответствует существующему поведению и ценам в синхронном режиме). Сервер будет самостоятельно продвигать задачу, но не будет взимать плату заранее, если задача завершится на сервере. Если задача не будет успешно завершена в течение 120 секунд, она будет завершена с HTTP 504 timeout, без оплаты. /captcha/tasks не отвечает за продвижение задач.
Примечание: Cloudflare Turnstile в настоящее время не поддерживает собственные прокси (Bring Your Own Proxy), поэтому этот интерфейс не принимает параметр proxy; если он будет передан, будет возвращена ошибка 400 invalid_proxy.

​
Обработка Ошибок

При вызове API, если возникнет ошибка, API вернет соответствующий код ошибки и информацию. Например:
  • 400 token_mismatched：Неверный запрос, возможно из-за отсутствующих или недействительных параметров.
  • 400 invalid_proxy：Неверный запрос, прокси не поддерживается для этого типа капчи.
  • 401 invalid_token：Неавторизован, недействительный или отсутствующий токен авторизации.
  • 429 too_many_requests：Слишком много запросов, вы превысили лимит частоты.
  • 500 api_error：Внутренняя ошибка сервера, что-то пошло не так на сервере.

​
Пример ответа с ошибкой

​
Заключение

С помощью данного документа вы узнали, как использовать API распознавания протокола Cloudflare Turnstile, чтобы пользователи могли проходить проверку Turnstile без распознавания и нажатия на капчу, просто отправляя Website Key для автоматического фонового декодирования и завершения проверки. Надеемся, что этот документ поможет вам лучше интегрировать и использовать данный API. Если у вас возникнут вопросы, пожалуйста, свяжитесь с нашей технической поддержкой.