> ## 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 Protokół Rozpoznawania API Instrukcja Integracji

> Cloudflare Turnstile Captcha Service API guide - Ace Data Cloud

Niniejszy dokument przedstawia instrukcję integracji API rozpoznawania protokołu Cloudflare Turnstile, która umożliwia użytkownikom automatyczne dekodowanie w tle bez konieczności rozpoznawania i klikania na CAPTCHA Turnstile, wystarczy przesłać klucz witryny (Website Key).

## Proces Aplikacji

Aby korzystać z API rozpoznawania protokołu Cloudflare Turnstile, najpierw przejdź do [Konsoli Ace Data Cloud](https://platform.acedata.cloud/console/applications), aby uzyskać swój token API, który należy zachować na przyszłość.

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

Jeśli nie jesteś zalogowany lub zarejestrowany, automatycznie zostaniesz przekierowany na stronę logowania, aby zarejestrować się i zalogować, a po zakończeniu zostaniesz automatycznie przekierowany z powrotem na bieżącą stronę.

**Jeden token API wystarczy do wywołania wszystkich usług platformy, nie ma potrzeby składania osobnych wniosków dla każdej usługi.** Przy pierwszym wniosku otrzymasz darmowy limit, aby móc go przetestować; w przypadku niewystarczającego limitu możesz doładować saldo ogólne w [konsoli](https://platform.acedata.cloud/console/coin).

> 📘 Pełna dokumentacja: [Cloudflare Turnstile Protokół Rozpoznawania API →](https://platform.acedata.cloud/documents/captcha-token-turnstile)

## Podstawowe Użycie

Najpierw zapoznaj się z podstawowym sposobem użycia, polegającym na wprowadzeniu URL witryny, która wymaga przetworzenia CAPTCHA Turnstile, aby uzyskać przetworzony wynik. Najpierw musisz przekazać prosty parametr `website_url`, nasza przykładowa witryna to: `https://react-turnstile.vercel.app`, musimy uzyskać `website_key` na stronie `website_url`, otwierając tę stronę, naciskając F12, aby wejść do konsoli, a następnie przeszukując globalnie stronę Element w poszukiwaniu `cf-turnstile`, gdzie znajdziesz element kontenera zawierającego Turnstile, a ciąg znaków odpowiadający `data-sitekey` to wartość `website_key`.

Ustawione nagłówki żądania obejmują:

* `accept`: format odpowiedzi, który chcesz otrzymać, tutaj wpisz `application/json`, czyli format JSON.
* `authorization`: klucz do wywołania API, po złożeniu wniosku możesz go bezpośrednio wybrać z rozwijanej listy.

Dodatkowo ustawiono ciało żądania, które obejmuje:

* `website_url`: URL witryny, która wymaga przetworzenia CAPTCHA.
* `website_key`: identyfikator klucza witryny w Cloudflare Turnstile (sitekey).
* `action`: opcjonalny parametr, który należy przekazać tylko wtedy, gdy docelowa witryna ma ustawioną niestandardową `action` dla komponentu Turnstile.
* `cdata`: opcjonalny parametr, który należy przekazać tylko wtedy, gdy docelowa witryna ma ustawioną niestandardową `cData` dla komponentu Turnstile.

Kliknij przycisk „Try”, aby przeprowadzić test, a otrzymamy następujący wynik:

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

Zwrócony wynik zawiera wiele pól, które są opisane poniżej:

* `token`, wynik weryfikacji po przetworzeniu zadania CAPTCHA Cloudflare Turnstile.
* `started_at`, `finished_at`: czas rozpoczęcia przetwarzania i uzyskania wyniku, znacznik czasu Unix (sekundy, liczba zmiennoprzecinkowa).
* `elapsed`: całkowity czas przetwarzania (sekundy).

Możemy zobaczyć, że otrzymaliśmy wynik weryfikacji CAPTCHA Turnstile, który możemy wykorzystać do przesłania POST lub symulacji przesyłania do docelowej witryny, jest to jednorazowe użycie, ważne przez 120s, zaleca się użycie w ciągu 60s. Podczas przesyłania zazwyczaj token jest przesyłany jako parametr `cf-turnstile-response` do docelowej witryny, kod Pythona do wywołania weryfikacji tokena wygląda następująco:

```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)
```

Jeśli chcesz wygenerować odpowiedni kod integracyjny, możesz go bezpośrednio skopiować, na przykład kod CURL wygląda następująco:

```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"
}'
```

Kod integracyjny w Pythonie wygląda następująco:

```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)
```

## Tryb Asynchroniczny (async)

Domyślnie API działa w trybie synchronicznym: jedno żądanie będzie czekać, aż przetwarzanie tokena zostanie zakończone, zanim zwróci wynik. Jeśli wykonujesz rotację wielu rozwiązań (multi-solver rotation) i chcesz „natychmiast uzyskać task\_id po złożeniu zadania, aby najpierw zlecić inne rozwiązania, a później wrócić po wyniki”, możesz przekazać `async: true` w ciele żądania.

Po przekazaniu `async: true`, interfejs natychmiast zwróci `task_id`, nie czekając na zakończenie przetwarzania:

```json theme={null}
{
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab"
}
```

Aby aktywnie sprawdzić postęp, możesz użyć `task_id` do zapytania `POST /captcha/tasks` (zaleca się co 3-5 sekund). Ten interfejs nie uruchomi ani nie przyspieszy przetwarzania zadań; nawet jeśli nie zapytasz, stracisz połączenie lub wyjdziesz z klienta, serwer nadal będzie przetwarzać:

```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"
}'
```

W trakcie przetwarzania zwróci `status: processing`; po zakończeniu przetwarzania zwróci `status: ready` i token:

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

Informacje o rozliczeniach: w trybie asynchronicznym tworzenie zadań i odczytywanie statusu „w przetwarzaniu” nie są obciążane opłatami; **opłata jest naliczana tylko przy pierwszym odczycie pomyślnego wyniku przez klienta** (zgodnie z obecnym zachowaniem i cenami w trybie synchronicznym). Serwer samodzielnie przyspiesza przetwarzanie zadań, ale nie nalicza opłat, gdy zadanie zostanie zakończone w tle. Jeśli zadanie nie zakończy się pomyślnie w ciągu 120 sekund, zostanie zakończone jako HTTP 504 `timeout`, bez opłat. `/captcha/tasks` nie odpowiada za przyspieszanie zadań.

> Uwaga: Cloudflare Turnstile obecnie nie obsługuje własnych proxy (Bring Your Own Proxy), dlatego ten interfejs nie akceptuje parametru `proxy`; jeśli zostanie przekazany, zwróci `400 invalid_proxy`.

## Obsługa Błędów

Podczas wywoływania API, jeśli wystąpi błąd, API zwróci odpowiedni kod błędu i informację. Na przykład:

* `400 token_mismatched`：Złe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów.
* `400 invalid_proxy`：Złe żądanie, proxy nie jest obsługiwane dla tego typu captcha.
* `401 invalid_token`：Nieautoryzowany, nieprawidłowy lub brakujący token autoryzacyjny.
* `429 too_many_requests`：Zbyt wiele żądań, przekroczyłeś limit szybkości.
* `500 api_error`：Błąd wewnętrzny serwera, coś poszło nie tak na serwerze.

### Przykład odpowiedzi błędu

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

## Wnioski

Dzięki temu dokumentowi zrozumiałeś, jak używać API rozpoznawania protokołu Cloudflare Turnstile, aby użytkownicy nie musieli rozpoznawać i klikać na captcha Turnstile, wystarczy, że prześlą klucz witryny, aby zrealizować automatyczne dekodowanie w tle i zakończyć weryfikację. Mamy nadzieję, że ten dokument pomoże Ci lepiej zintegrować i korzystać z tego API. W razie jakichkolwiek pytań, skontaktuj się z naszym zespołem wsparcia technicznego.


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