> ## 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 Protokoll Erkennungs-API Integrationsanleitung

> Cloudflare Turnstile Captcha Service API guide - Ace Data Cloud

Dieser Artikel beschreibt eine Cloudflare Turnstile Protokoll Erkennungs-API-Integrationsanleitung, die es Benutzern ermöglicht, Turnstile-Captchas ohne Erkennung und Auswahl zu umgehen, indem sie einfach den Website-Schlüssel einreichen, um die automatische Dekodierung im Hintergrund durchzuführen und die Verifizierung abzuschließen.

## Antragsprozess

Um die Cloudflare Turnstile Protokoll Erkennungs-API zu verwenden, gehen Sie zunächst zur [Ace Data Cloud Konsole](https://platform.acedata.cloud/console/applications), um Ihr API-Token zu erhalten und es für zukünftige Verwendung zu speichern.

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

Wenn Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, die Sie zur Registrierung und Anmeldung einlädt. Nach Abschluss werden Sie automatisch zur aktuellen Seite zurückgeleitet.

**Ein API-Token reicht aus, um auf alle Dienste der Plattform zuzugreifen, ohne dass für jeden Dienst separat beantragt werden muss.** Bei der ersten Beantragung erhalten Sie ein kostenloses Kontingent, um es kostenlos auszuprobieren; wenn das Kontingent erschöpft ist, können Sie im [Dashboard](https://platform.acedata.cloud/console/coin) Ihr Guthaben aufladen.

> 📘 Vollständige Dokumentation: [Cloudflare Turnstile Protokoll Erkennungs-API →](https://platform.acedata.cloud/documents/captcha-token-turnstile)

## Grundlegende Nutzung

Zunächst sollten Sie die grundlegende Nutzung verstehen, indem Sie die URL der Website eingeben, die das Turnstile-Captcha verarbeitet, um das verarbeitete Ergebnis zu erhalten. Zuerst müssen Sie einfach ein `website_url`-Feld übergeben. Unsere Beispielwebsite ist: `https://react-turnstile.vercel.app`, und wir müssen den `website_key` auf der `website_url`-Seite abrufen. Öffnen Sie diese Webseite, drücken Sie F12, um die Konsole zu öffnen, und suchen Sie im Element-Bereich global nach `cf-turnstile`. Dort finden Sie das Container-Element, das Turnstile enthält, wobei der Wert von `data-sitekey` die Zeichenfolge ist, die dem `website_key` entspricht.

Die festgelegten Request-Header umfassen:

* `accept`: In welchem Format Sie die Antwort erhalten möchten, hier eingetragen als `application/json`, also im JSON-Format.
* `authorization`: Der Schlüssel zur API-Nutzung, den Sie nach der Beantragung direkt auswählen können.

Zusätzlich wurde der Request-Body festgelegt, der Folgendes umfasst:

* `website_url`: Die URL der Website, die das Captcha verarbeiten soll.
* `website_key`: Der Website-Schlüssel-Identifikator (sitekey) in Cloudflare Turnstile.
* `action`: Optionales Parameter, das nur übergeben werden muss, wenn die Zielwebsite eine benutzerdefinierte `action` für das Turnstile-Element festgelegt hat.
* `cdata`: Optionales Parameter, das nur übergeben werden muss, wenn die Zielwebsite eine benutzerdefinierte `cData` für das Turnstile-Element festgelegt hat.

Klicken Sie auf die Schaltfläche „Try“, um einen Test durchzuführen, und wir erhalten folgendes Ergebnis:

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

Die Rückgabe enthält mehrere Felder, die wie folgt beschrieben werden:

* `token`, das Ergebnis der Verifizierung des Turnstile-Captcha-Auftrags.
* `started_at`, `finished_at`: Die Zeit, zu der die Anfrage bearbeitet und das Ergebnis erzeugt wurde, Unix-Zeitstempel (Sekunden, Fließkomma).
* `elapsed`: Die gesamte Bearbeitungszeit (Sekunden).

Wir können sehen, dass wir das Verifizierungsergebnis des Turnstile-Captchas erhalten haben, das wir dann für POST oder zur Simulation der Einreichung an die Zielwebsite verwenden können, einmalige Verwendung, Gültigkeit 120s, empfohlen innerhalb von 60s zu verwenden. Bei der Einreichung wird dieser Token normalerweise als `cf-turnstile-response`-Parameter zusammen mit an die Zielwebsite gesendet. Der Python-Code zur Verifizierung des Tokens sieht wie folgt aus:

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

Wenn Sie außerdem den entsprechenden Integrationscode generieren möchten, können Sie ihn direkt kopieren, zum Beispiel sieht der CURL-Code wie folgt aus:

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

Der Python-Integrationscode sieht wie folgt aus:

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

## Asynchroner Modus (async)

Standardmäßig ist die API synchron blockierend: Eine Anfrage wartet, bis die Tokenverarbeitung abgeschlossen ist, bevor sie zurückgegeben wird. Wenn Sie eine Multi-Solver-Rotation durchführen und „nach der Einreichung der Aufgabe sofort die task\_id erhalten möchten, um andere Solver zu planen und später zurückzukehren, um die Ergebnisse abzurufen“, können Sie im Anfragekörper `async: true` übergeben.

Nach der Übergabe von `async: true` gibt die Schnittstelle sofort eine `task_id` zurück, ohne zu blockieren:

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

Um den Fortschritt aktiv zu überprüfen, können Sie diese `task_id` verwenden, um `POST /captcha/tasks` abzufragen (empfohlen alle 3-5 Sekunden). Diese Schnittstelle löst oder beschleunigt die Aufgabenbearbeitung nicht; selbst wenn Sie nicht abfragen, die Verbindung unterbrochen wird oder der Client beendet wird, wird der Server weiterhin die Verarbeitung durchführen:

```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ährend der Verarbeitung wird `status: processing` zurückgegeben; nach Abschluss der Verarbeitung wird `status: ready` und der Token zurückgegeben:

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

Abrechnungsinformationen: Im asynchronen Modus werden die Erstellung von Aufgaben und das Abrufen des „verarbeiteten“ Status nicht berechnet; **der Client wird einmal berechnet, wenn er das erste erfolgreiche Ergebnis abruft** (entspricht dem aktuellen Verhalten und den Preisen im synchronen Modus). Der Server wird die Aufgaben selbstständig vorantreiben, aber es wird keine Gebühr erhoben, nur weil die Verarbeitung im Hintergrund abgeschlossen ist. Wenn die Aufgabe innerhalb von 120 Sekunden nicht erfolgreich ist, wird sie mit HTTP 504 `timeout` beendet, ohne Gebühren. `/captcha/tasks` ist nicht dafür verantwortlich, die Aufgaben voranzutreiben.

> Hinweis: Cloudflare Turnstile unterstützt derzeit keine eigenen Proxys (Bring Your Own Proxy), daher akzeptiert diese Schnittstelle keinen `proxy`-Parameter; wenn übergeben, wird `400 invalid_proxy` zurückgegeben.

## Fehlerbehandlung

Wenn beim Aufruf der API ein Fehler auftritt, gibt die API den entsprechenden Fehlercode und die Informationen zurück. Zum Beispiel:

* `400 token_mismatched`：Ungültige Anfrage, möglicherweise aufgrund fehlender oder ungültiger Parameter.
* `400 invalid_proxy`：Ungültige Anfrage, Proxy wird für diesen Captcha-Typ nicht unterstützt.
* `401 invalid_token`：Unbefugt, ungültiger oder fehlender Autorisierungstoken.
* `429 too_many_requests`：Zu viele Anfragen, Sie haben das Rate-Limit überschritten.
* `500 api_error`：Interner Serverfehler, etwas ist auf dem Server schiefgegangen.

### Fehlerantwort Beispiel

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

## Fazit

Durch dieses Dokument haben Sie gelernt, wie Sie die Cloudflare Turnstile-Protokoll-Identifizierungs-API verwenden, um Benutzern die Identifizierung und das Klicken auf das Turnstile-Captcha zu ersparen, indem Sie lediglich den Website-Schlüssel einreichen, um die automatische Dekodierung im Hintergrund durchzuführen und die Überprüfung abzuschließen. Wir hoffen, dass dieses Dokument Ihnen hilft, die API besser zu integrieren und zu nutzen. Bei Fragen wenden Sie sich bitte jederzeit an unser technisches Support-Team.


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