Skip to main content
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, aby uzyskać swój token API, który należy zachować na przyszłość. 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.
📘 Pełna dokumentacja: Cloudflare Turnstile Protokół Rozpoznawania API →

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:
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:
Jeśli chcesz wygenerować odpowiedni kod integracyjny, możesz go bezpośrednio skopiować, na przykład kod CURL wygląda następująco:
Kod integracyjny w Pythonie wygląda następująco:

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:
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ć:
W trakcie przetwarzania zwróci status: processing; po zakończeniu przetwarzania zwróci status: ready i token:
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

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.