Betrugsprävention Daten-API

Die Daten-API ist das serverseitige Gegenstück zum Web-SDK. Nutzen Sie sie, um Urteile abzurufen, Statistiken zu aggregieren und Daten für Reporting und Abstimmung zu exportieren — um die Zahlen abzurufen, auf die sich Ihre eigenen Systeme einigen.

Basis-URL

https://verify.captcha.la

Authentifizierung

Alle Daten-API-Anfragen werden mit Ihren Betrugsprävention-Anwendungsanmeldedaten authentifiziert, gesendet als Header:

X-App-Key:    YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

WARNING

X-App-Secret ist nur serverseitig. Geben Sie es niemals an Browser, mobile Apps oder öffentliche Repositories weiter. Das Seiten-SDK verwendet stets nur den öffentlichen appKey.

Endpunkte

Ein Urteil abrufen

Rufen Sie das Urteil für einen einzelnen Besuch ab (z. B. um einen bestimmten Besuch abzustimmen). Übergeben Sie genau einen Bezeichner: verdict_id (aus dem Urteil, das die Seite erhalten hat) oder cid (die Klick-ID, für Click-Token-Traffic).

bash

GET /v1/bot/verdict?verdict_id=VERDICT_ID
GET /v1/bot/verdict?cid=CID_OF_THE_VISIT
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

found gibt an, ob ein Urteil gefunden wurde. Ist es true, enthält data die in der Verdict-Referenz beschriebenen Urteilsfelder:

json

{
  "found": true,
  "data": {
    "cid": null,
    "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
    "is_bot": true,
    "score": 87,
    "level": "high",
    "action": "flag",
    "reasons": ["automation", "network"],
    "consistency": { "ok": false },
    "degraded": false,
    "created_at": "2026-06-25 00:00:00"
  }
}

Gibt es keinen Treffer, lautet die Antwort {"found": false}. Eine Anfrage ohne verdict_id und ohne cid wird mit HTTP 400 abgelehnt.

TIP

Urteile werden wenige Sekunden nach ihrer Erzeugung gespeichert, daher kann eine Abfrage direkt nach dem Besuch found: false liefern. Um einen Besuch in Echtzeit zu prüfen, verwenden Sie stattdessen Ein Verdict-Token verifizieren.

Ein Verdict-Token verifizieren

Prüfen Sie ein verdict_token, das Ihre Seite vom Web-SDK erhalten hat. Damit schützen Sie Inhalte auf Ihrem Server (siehe Serverseitige Verifizierung). Die Prüfung wird sofort beantwortet und hängt nicht von gespeicherten Daten ab.

bash

POST /v1/bot/verdict/verify
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "token": "vt1.eyJ2Ijoi...", "ip": "203.0.113.7", "consume": false }

Parameter	Erforderlich	Beschreibung
`token`	ja	Das `verdict_token` aus dem Urteil.
`ip`	nein	Die IP-Adresse des Besuchers, wie Ihr Server sie sieht. Wenn angegeben, muss das Token aus demselben Netzwerk wie der Besuch stammen. Empfohlen.
`consume`	nein	`true` = das Token kann nur einmal verwendet werden; eine zweite Prüfung liefert `already_used`. Standard `false`: das Token kann bis zum Ablauf erneut geprüft werden.

json

{
  "valid": true,
  "error": null,
  "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
  "expired": false,
  "expires_at": 1767225600,
  "ip_match": true,
  "verdict": {
    "is_bot": false,
    "level": "low",
    "action": "record_only",
    "score": 12,
    "degraded": false,
    "reasons": [],
    "issued_at": 1767225000
  }
}

Feld	Beschreibung
`valid`	`true`, wenn das Token echt ist, zu Ihrer App gehört, nicht abgelaufen ist, zu `ip` passt (falls angegeben) und bei `consume` noch nicht verwendet wurde. `valid` sagt nur, dass das Token echt ist. Es sagt nicht, dass der Besucher ein Mensch ist, prüfen Sie also auch `verdict`.
`error`	`null` oder der Grund, warum das Token ungültig ist: `malformed`, `bad_signature`, `expired`, `ip_mismatch`, `already_used`, `unavailable` (die Einmalprüfung konnte nicht abgeschlossen werden; erneut versuchen).
`expired` / `expires_at`	Ablaufstatus und Ablaufzeit (Unix-Sekunden).
`ip_match`	`true` / `false`, wenn `ip` angegeben wurde, sonst `null`.
`verdict`	Das signierte Urteil: `is_bot`, `level`, `action`, `score`, `degraded`, `reasons`, `issued_at`. `null`, wenn das Token nicht gelesen werden konnte.

Ein typisches Gate liefert den Inhalt aus, wenn valid true und verdict.is_botfalse ist. Entscheiden Sie selbst, wie Sie verdict.degraded und Anfragen ganz ohne Token behandeln. Bei „fail open“ kommen echte Besucher auch während eines Ausfalls durch. Bei „fail closed“ kommt ohne gültiges Token nichts durch.

Tokens laufen standardmäßig nach 10 Minuten ab. Führen Sie das SDK erneut aus (zum Beispiel beim nächsten Seitenaufruf), um ein neues zu erhalten.

Aggregierte Statistiken

Rufen Sie Zählungen über einen Zeitraum ab (Gesamtwerte, Bots und die Aufschlüsselung nach level und nach Tag) für Dashboards und Qualitätsberichte.

bash

GET /v1/bot/stats?from=2026-06-01&to=2026-06-30
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

json

{
  "from": "2026-06-01",
  "to": "2026-06-30",
  "cleaned": true,
  "total": 124500,
  "bots": 18230,
  "by_level": { "low": 100300, "medium": 16900, "high": 6200, "critical": 1100 },
  "by_day": [
    { "date": "2026-06-01", "total": 4100, "bots": 590 }
  ]
}

from / to sind standardmäßig die letzten 7 Tage.

Export

Exportieren Sie Urteilszeilen pro Besuch für einen Zeitraum, für Offline-Abstimmung. Die Zeilen werden seitenweise zurückgegeben, die neuesten zuerst.

bash

GET /v1/bot/export?from=2026-06-01&to=2026-06-30&limit=1000
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

Parameter	Beschreibung
`from` / `to`	Datumsbereich (`YYYY-MM-DD`). Optional.
`limit`	Zeilen pro Seite, 1–5000 (Standard 1000).
`cursor`	Übergeben Sie den `next_cursor` der vorherigen Seite, um die nächste Seite zu erhalten.

json

{
  "rows": [
    {
      "id": 1042, "cid": null, "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
      "is_bot": false, "score": 12, "level": "low", "action": "record_only",
      "reasons": [], "consistency": { "ok": true }, "degraded": false,
      "created_at": "2026-06-25 00:00:00", "rescored": false
    }
  ],
  "next_cursor": 1042
}

Jede Zeile trägt die Bezeichner des Besuchs, den Zeitstempel und die Urteilsfelder, sodass Sie sie wieder mit Ihren eigenen Logs verknüpfen können. next_cursor ist auf der letzten Seite null.

Bereinigte Zahlen

Statistiken und Exporte werden standardmäßig auf bereinigter Basis ausgewiesen: Datenverkehr, der später als ungültig erkannt wird, wird fortlaufend neu bewertet und aus den Zahlen entfernt. Dies geschieht asynchron, sodass sich Zahlen für sehr aktuelle Zeiträume noch leicht ändern können. Übergeben Sie ?raw=1, um die unbereinigten Zahlen zu sehen; in export trägt jede Zeile zusätzlich ein rescored-Flag.

Per-Klick-Abstimmung

Für Szenarien mit bezahltem Datenverkehr kann ein einzelner Besuch auf einen bestimmten gelieferten Klick zurückgeführt werden, sodass zwei Parteien sich darauf einigen können. Das nutzt ein Click-Token und wird im Leitfaden Anzeigenbetrug behandelt.

Click-Token-Referenz (für Traffic-Anbieter)

Ein Traffic-Anbieter signiert ein Click-Token auf seinem eigenen Server und fügt es der Ziel-URL hinzu, sodass das Verdict für den daraus resultierenden Besuch dem Anbieter zugeordnet wird. Die Signierung erfolgt offline — kein API-Aufruf.

Signaturschlüssel abrufen

Öffnen Sie im Dashboard Ihre App → Fraud Prevention → Signaturschlüssel ausstellen. Sie erhalten:

bot_kid — Ihre öffentliche Schlüssel-ID (wird im Token zu pkid).
bot_hmac_secret — Ihr Signatur-Secret, einmalig angezeigt. Bewahren Sie es serverseitig auf.

Token-Format

ct.<base64url(payload)>.<base64url(HMAC_SHA256(body, bot_hmac_secret))>

body ist die base64url-Kodierung des JSON-Payloads; die Signatur wird über diese body-Zeichenkette berechnet.

Payload-Felder

Feld	erforderlich	Beschreibung
`pkid`	ja	Ihre `bot_kid`; das Backend verwendet sie, um Ihr Secret nachzuschlagen und die Signatur zu prüfen
`cid`	ja	eindeutige ID für diesen Klick; der Abgleichsschlüssel. Erzeugen Sie pro Klick einen neuen, eindeutigen Wert
`aud`	nein	der `app_key` des Ziel-Advertisers. Wenn gesetzt, wird das Token nur auf der Seite dieses Advertisers akzeptiert. Weglassen, damit jede Advertiser-Seite es akzeptiert
`click_ts`	nein	Unix-Sekunden, zu denen der Klick erfolgte
`exp`	nein	Unix-Sekunden Ablaufzeit; abgelaufene Tokens werden abgelehnt

Zum Link hinzufügen

Hängen Sie das Token als Query-Parameter _ctk an die Ziel-URL des Advertisers an:

https://advertiser.example/lp?_ctk=ct.<...>.<...>

Das SDK des Advertisers liest _ctk automatisch aus (konfigurierbar über tokenParam). Jede cid ist Replay-geschützt: Lädt derselbe Besucher die Seite neu, ist das in Ordnung, ein anderswo wiederverwendetes Token wird jedoch markiert. Siehe das Sicherheitsmodell.

Beispiel (Pseudocode)

const payload = { pkid, cid, aud: advertiserAppKey, click_ts: now, exp: now + 900 }
const body  = base64url(JSON.stringify(payload))
const sig   = base64url(hmacSha256(body, botHmacSecret))
const token = `ct.${body}.${sig}`
const url   = `${destination}?_ctk=${encodeURIComponent(token)}`

Postback (Server-zu-Server)

Anstatt die Daten-API abzufragen, können Sie sich Urteile in dem Moment, in dem sie entstehen, an Ihren eigenen Endpunkt pushen lassen — praktisch für Affiliate-Tracker und Advertiser-Backends, die jeden Besuch in Echtzeit erfassen oder abgleichen möchten.

Aktivieren

Öffnen Sie im Dashboard Ihre App → Fraud Prevention → setzen Sie die Postback-URL (bot_postback_url). Sobald sie gesetzt ist, wird jedes Urteil kurz nach seiner Erzeugung per POST an diese URL gesendet. Die Zustellung erfolgt asynchron und isoliert — ein langsamer oder fehlerhafter Endpunkt beeinflusst niemals das Urteil, das bereits an das Seiten-SDK zurückgegeben wurde.

Wann er ausgelöst wird

Bei jeder Verifizierung, die ein Urteil für die App erzeugt. Die Zustellung erfolgt nach bestem Bemühen mit einigen automatischen Wiederholungen; behandeln Sie sie als at-least-once und deduplizieren Sie anhand von verdict_id.

Anfrage

POST <your bot_postback_url>
Content-Type: application/json
X-Bot-Signature: t=<unix_ts>,v=<hex>

Body (JSON):

json

{
  "cid": "CID_OF_THE_VISIT",
  "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
  "is_bot": 1,
  "score": 87,
  "level": "high",
  "action": "flag",
  "advertiser_app_id": 12,
  "provider_app_id": 34,
  "created_at": "2026-06-25 00:00:00"
}

Feld	Beschreibung
`cid`	Abgleichsschlüssel für den Besuch (kann `null` sein, wenn kein Click-Token vorhanden war)
`verdict_id`	ID des Urteils; derselbe Wert, den die Seite erhalten hat
`is_bot`	`1` / `0`
`score`	Risikobewertung
`level`	`low` / `medium` / `high` / `critical`
`action`	serverseitig maßgebliche Aktion (`record_only` / `flag` / `challenge` / `deny`)
`advertiser_app_id`	ID der App, für die die Verifizierung lief
`provider_app_id`	ID des Traffic-Anbieters bei Zuordnung über ein Click-Token, sonst `null`
`created_at`	Zeitpunkt des Urteils (UTC)

Signatur prüfen

Mit dem Header X-Bot-Signature können Sie bestätigen, dass die Anfrage wirklich von uns stammt. Er hat die Form t=<unix_ts>,v=<hex>, wobei:

hex = HMAC_SHA256( "<unix_ts>." + raw_request_body , bot_hmac_secret )

bot_hmac_secret ist dasselbe Signatur-Secret, das Sie unter Fraud Prevention → Signaturschlüssel ausstellen erzeugen. Berechnen Sie zur Prüfung den HMAC über den rohen empfangenen Body neu (serialisieren Sie das JSON nicht erneut) und vergleichen Sie in konstanter Zeit. Optional können Sie Anfragen ablehnen, deren t zu weit von Ihrer Uhr abweicht, um Replays einzugrenzen.

// Express example
const [tsPart, vPart] = req.get('X-Bot-Signature').split(',')
const ts = tsPart.slice(2)             // "t=" prefix
const v  = vPart.slice(2)              // "v=" prefix
const expected = crypto
  .createHmac('sha256', BOT_HMAC_SECRET)
  .update(ts + '.' + rawBody)          // rawBody is the unparsed request body
  .digest('hex')
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v))

Nächste Schritte

Verdict-Referenz — die von diesen Endpunkten zurückgegebenen Felder
Web-SDK — Urteile auf Ihrer Seite sammeln

Betrugsprävention Daten-API ​

Basis-URL ​

Authentifizierung ​

Endpunkte ​

Ein Urteil abrufen ​

Ein Verdict-Token verifizieren ​

Aggregierte Statistiken ​

Export ​

Click-Token-Referenz (für Traffic-Anbieter) ​

Signaturschlüssel abrufen ​

Token-Format ​

Payload-Felder ​

Zum Link hinzufügen ​

Beispiel (Pseudocode) ​

Postback (Server-zu-Server) ​

Aktivieren ​

Wann er ausgelöst wird ​

Anfrage ​

Signatur prüfen ​

Nächste Schritte ​

Betrugsprävention Daten-API

Basis-URL

Authentifizierung

Endpunkte

Ein Urteil abrufen

Ein Verdict-Token verifizieren

Aggregierte Statistiken

Export

Click-Token-Referenz (für Traffic-Anbieter)

Signaturschlüssel abrufen

Token-Format

Payload-Felder

Zum Link hinzufügen

Beispiel (Pseudocode)

Postback (Server-zu-Server)

Aktivieren

Wann er ausgelöst wird

Anfrage

Signatur prüfen

Nächste Schritte