> ## 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.

# Cloudflare Turnstile протокол ідентифікації API інтеграція

> Cloudflare Turnstile Captcha Service API guide - Ace Data Cloud

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

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

Щоб використовувати API для ідентифікації протоколу Cloudflare Turnstile, спочатку перейдіть до [консолі Ace Data Cloud](https://platform.acedata.cloud/console/applications) для отримання вашого API Token, зберігайте його для подальшого використання.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, щоб запросити реєстрацію та вхід, після чого ви будете автоматично повернені на цю сторінку.

**Один API Token дозволяє викликати всі послуги платформи, не потрібно окремо подавати заявку на кожну послугу.** Перший запит на отримання токена надає безкоштовний ліміт для тестування; якщо ліміт вичерпано, ви можете поповнити загальний баланс у [консолі](https://platform.acedata.cloud/console/coin).

> 📘 Повна документація: [Cloudflare Turnstile протокол ідентифікації API →](https://platform.acedata.cloud/documents/captcha-token-turnstile)

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

Спочатку розгляньте основний спосіб використання, а саме введіть 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.

Натисніть кнопку «Спробувати», щоб провести тестування, і ми отримаємо наступний результат:

```json theme={null}
{
  "token": "0.mNQ2f9uP6mQ0y3H5Q8bqO7iM......",
  "started_at": 1784885653.0,
  "finished_at": 1784885665.4,
  "elapsed": 12.4
}
```

У повернутому результаті є кілька полів, описаних нижче:

* `token`, результат перевірки для обробленої CAPTCHA Turnstile.
* `started_at`, `finished_at`: час початку обробки запиту та отримання результату, Unix-час (секунди, з плаваючою комою).
* `elapsed`: загальний час обробки (секунди).

Ми отримали результат перевірки CAPTCHA Turnstile, який можна використовувати для POST або імітації подачі на цільовий сайт, одноразове використання, термін дії 120 секунд, рекомендується використовувати протягом 60 секунд. Під час подачі зазвичай передають цей токен як параметр `cf-turnstile-response` на цільовий сайт, код Python для виклику перевірки токена виглядає так:

```python theme={null}
import requests

token = '{token}'

data = {
    'cf-turnstile-response': token
}

response = requests.post('https://react-turnstile.vercel.app', data=data)

if response.status_code == 200:
    print(response.text)
```

Крім того, якщо ви хочете згенерувати відповідний код інтеграції, ви можете просто скопіювати його, наприклад, код CURL виглядає так:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/captcha/token/turnstile' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "website_key": "0x4AAAAAAADnPIDROrmt1Wwj",
  "website_url": "https://react-turnstile.vercel.app"
}'
```

Код інтеграції на Python виглядає так:

```python theme={null}
import requests

url = "https://api.acedata.cloud/captcha/token/turnstile"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "website_key": "0x4AAAAAAADnPIDROrmt1Wwj",
    "website_url": "https://react-turnstile.vercel.app"
}

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}
{
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab"
}
```

Щоб активно перевірити прогрес, ви можете використовувати цей `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`; після завершення обробки буде повернуто `status: ready` і токен:

```json theme={null}
{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "ready",
  "token": "0.mNQ2f9uP6mQ0y3H5Q8bqO7iM......"
}
```

Опис тарифікації: в асинхронному режимі створення завдання та читання статусу «в обробці» не підлягають тарифікації; **клієнт буде тарифікуватися один раз при першому успішному читанні результату** (так само, як і в поточній поведінці та ціні синхронного режиму). Сервер самостійно просуває завдання, але не буде стягувати плату за те, що завдання завершено на сервері раніше. Якщо завдання не буде успішно завершено протягом 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`：Внутрішня помилка сервера, щось пішло не так на сервері.

### Приклад помилкового відповіді

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## Висновок

Через цей документ ви дізналися, як використовувати API Cloudflare Turnstile для ідентифікації, щоб користувачі не повинні були розпізнавати та натискати на капчу Turnstile, а лише подавати ключ веб-сайту для автоматичного декодування на сервері та завершення перевірки. Сподіваємося, що цей документ допоможе вам краще інтегрувати та використовувати цей API. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої команди технічної підтримки.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.