Skip to main content
У цьому документі буде представлено опис інтеграції API для ідентифікації протоколу Cloudflare Turnstile, який дозволяє користувачам проходити перевірку без необхідності розпізнавання та натискання на CAPTCHA Turnstile, просто подавши Website Key для автоматичного декодування на сервері.

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

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

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

Спочатку розгляньте основний спосіб використання, а саме введіть URL сайту, для якого потрібно обробити CAPTCHA Turnstile, щоб отримати оброблений результат. Спочатку потрібно просто передати поле website_url, наш приклад сайту: https://react-turnstile.vercel.app, нам потрібно отримати website_key на сторінці website_url, для цього відкрийте цю веб-сторінку, натисніть F12 для входу в консоль, на вкладці Element виконайте глобальний пошук cf-turnstile, ви знайдете контейнерний елемент, що містить Turnstile, де data-sitekey відповідає рядку, що є значенням website_key. Налаштовані заголовки запиту включають:
  • accept: формат відповіді, який ви хочете отримати, тут вказується application/json, тобто формат JSON.
  • authorization: ключ для виклику API, після подачі заявки ви можете вибрати його зі списку.
Крім того, налаштовано тіло запиту, яке включає:
  • website_url: URL сайту, для якого потрібно обробити CAPTCHA.
  • website_key: ідентифікатор сайту в Cloudflare Turnstile (sitekey).
  • action: необов’язковий параметр, передається лише тоді, коли цільовий сайт має налаштовану користувацьку action для компонента Turnstile.
  • cdata: необов’язковий параметр, передається лише тоді, коли цільовий сайт має налаштовану користувацьку cData для компонента Turnstile.
Натисніть кнопку «Спробувати», щоб провести тестування, і ми отримаємо наступний результат:
У повернутому результаті є кілька полів, описаних нижче:
  • token, результат перевірки для обробленої CAPTCHA Turnstile.
  • started_at, finished_at: час початку обробки запиту та отримання результату, Unix-час (секунди, з плаваючою комою).
  • elapsed: загальний час обробки (секунди).
Ми отримали результат перевірки CAPTCHA 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, а лише подавати ключ веб-сайту для автоматичного декодування на сервері та завершення перевірки. Сподіваємося, що цей документ допоможе вам краще інтегрувати та використовувати цей API. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої команди технічної підтримки.