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://apiv1.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).

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

Die Antwort data ist ein BotVerdict-Objekt:

{
  "code": 0,
  "data": {
    "is_bot": true,
    "score": 87,
    "level": "high",
    "action": "flag",
    "consistency": { "ok": false },
    "degraded": false
  }
}

Aggregierte Statistiken

Rufen Sie gebündelte Zählungen über einen Zeitraum ab — Gesamtwerte, Bot-Anteil und die Aufschlüsselung nach action/level — für Dashboards und Qualitätsberichte.

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

{
  "code": 0,
  "data": {
    "from": "2026-06-01",
    "to": "2026-06-30",
    "total": 124500,
    "bots": 18230,
    "bot_rate": 0.146,
    "by_action": { "record_only": 102100, "flag": 19800, "challenge": 2600 },
    "by_level":  { "low": 100300, "medium": 16900, "high": 6200, "critical": 1100 }
  }
}

Export

Exportieren Sie Urteilszeilen pro Besuch für einen Zeitraum, für Offline-Abstimmung.

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

Jede Zeile trägt den Bezeichner des Besuchs, den Zeitstempel und die Urteilsfelder (is_bot, score, level, action), sodass Sie sie wieder mit Ihren eigenen Logs verknüpfen können.

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). Eine cid kann nur einmal eingelöst werden (Replay-geschützt). 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)}`

Nächste Schritte

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