Zum Inhalt springen

API-Referenz

Anti-Fraud-API

Ein Browser-SDK für die Identifikation, signierte Webhooks für Echtzeit-Events und eine Workspace-Management-API. Alles, was Sie brauchen, um Betrug auf Geräteebene zu stoppen.

API-Schlüssel erhaltenAPI-Playground

Endpunkte

SDK@tracio/sdk

Identifizieren Sie einen Besucher im Browser mit dem Client-SDK. Gibt eine stabile Besucher-ID und ein Bot-Verdict ohne Server-Roundtrip zurück. Der öffentliche Schlüssel kann gefahrlos in clientseitigem Code ausgeliefert werden.

Anfrage

import { Tracio } from '@tracio/sdk'
const tracio = Tracio.init({ publicKey: '5ca175fc...' })
const result = await tracio.getResult()

Antwort

{
  "visitorId": "X7fh2Hg9LkMn3pQr",
  "bot": {
    "detected": false,
    "confidence": 2,
    "reasons": []
  }
}
POST/webhook/tracio

TRACIO liefert bei jeder Identifikation ein signiertes Event an Ihren Endpunkt. Verifizieren Sie den Header X-Tracio-Signature und reagieren Sie dann auf die flache JSON-Payload. Dies ist die serverseitige Event-Schnittstelle — es gibt kein Poll-by-requestId per REST-Abruf.

Anfrage

POST /webhook/tracio HTTP/1.1
Host: your-server.com
Content-Type: application/json
X-Tracio-Signature: t=1710432000,v1=5257a869e7ecebed...

Antwort

{
  "requestId": "1710432000_abc123",
  "visitorId": "X7fh2Hg9LkMn3pQr",
  "bot": { "result": "human", "type": "", "score": 0.02 },
  "identification": { "confidence": 0.95, "visitType": "returning" },
  "network": { "vpn": false, "proxy": false, "tor": false, "datacenter": false },
  "decision": { "action": "allow", "riskScore": 4 }
}
POST/api/v1/workspaces/{workspaceId}/webhooks

Registrieren Sie einen Webhook-Endpunkt über die Workspace-Management-API. Authentifiziert mit dem JWT Ihrer Dashboard-Session (Clerk) und geprüft gegen Ihre Workspace-Rolle. Das Signing Secret wird bei der Erstellung einmalig zurückgegeben.

Anfrage

curl -X POST \
  https://app.tracio.ai/api/v1/workspaces/{workspaceId}/webhooks \
  -H "Authorization: Bearer <clerk-session-jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-server.com/webhook/tracio", "events": [] }'

Antwort

{
  "ok": true,
  "data": {
    "id": "wh_abc123",
    "url": "https://your-server.com/webhook/tracio",
    "events": [],
    "signingSecret": "f3a9…<hex>",
    "status": "active",
    "createdAt": "2024-03-12T16:00:00Z"
  }
}
GET/api/v1/workspaces/{workspaceId}/visitors/{visitorId}

Rufen Sie die gespeicherte Historie eines Besuchers über die Workspace-Management-API ab, authentifiziert mit dem JWT Ihrer Dashboard-Session (Clerk). Unterstützt Auskunftsersuchen (Auskunftsrecht) nach der DSGVO.

Anfrage

curl \
  https://app.tracio.ai/api/v1/workspaces/{workspaceId}/visitors/X7fh2Hg9LkMn3pQr \
  -H "Authorization: Bearer <clerk-session-jwt>"

Antwort

{
  "ok": true,
  "data": {
    "visitorId": "X7fh2Hg9LkMn3pQr",
    "firstSeenAt": "2024-03-01T08:11:00Z",
    "lastSeenAt": "2024-03-16T14:22:01Z",
    "visits": 12
  }
}

Authentifizierung

TRACIO verwendet drei Arten von Anmeldedaten, je eine pro Schnittstelle: einen öffentlichen Schlüssel für das Browser-SDK, das JWT Ihrer Dashboard-Session (Clerk) für die Workspace-Management-API und ein HMAC-Signing-Secret zur Verifikation von Webhook-Zustellungen. Es gibt kein eigenständiges API-Secret.

# Client SDK — public key (safe to ship in the browser)
Tracio.init({ publicKey: '5ca175fc...' })
# Workspace management API — dashboard session (Clerk) JWT,
# additionally checked against your workspace role (RBAC)
Authorization: Bearer <clerk-session-jwt>
# Webhook verification — HMAC-SHA256 over "<t>.<rawBody>"
X-Tracio-Signature: t=<unix>,v1=<hmac_sha256_hex>

Rate-Limits

Die Limits gelten pro Workspace. Antworten der Management-API enthalten die Header X-RateLimit-Limit, X-RateLimit-Remaining und Retry-After.

TarifIdentifikationenWebhook-EventsManagement-APIBesucher-Abfragen
Free100/day100/day50/day100/day
Pro1,000/min1,000/min500/min1,000/min
Enterprise10,000/min10,000/min5,000/min10,000/min

Fehlercodes

Alle Fehler geben einen JSON-Body mit den Feldern code, message und details zurück.

400Bad RequestFehlerhafter Anfrage-Body oder fehlende Pflichtfelder.
401UnauthorizedFehlende oder ungültige Anmeldedaten — öffentlicher Schlüssel (SDK), Clerk-JWT (Management-API) oder Webhook-Signatur.
403ForbiddenIhrer Workspace-Rolle (RBAC) fehlt die Berechtigung für diesen Vorgang.
404Not FoundBesucher-ID oder Webhook in Ihrem Workspace nicht gefunden.
429Rate LimitedZu viele Anfragen. Prüfen Sie den Header Retry-After und die Limits Ihres Tarifs.
500Internal ErrorServerfehler. Wiederholen Sie den Vorgang mit exponentiellem Backoff. Bei anhaltendem Fehler wenden Sie sich an den Support.

Format der Fehlerantwort

{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded",
    "details": "1000 requests per minute limit reached for this workspace",
    "retryAfter": 12
  }
}

Jetzt entwickeln

Holen Sie sich Ihren API-Schlüssel und senden Sie Ihre erste Identifikationsanfrage in unter 5 Minuten.

API-Schlüssel erhaltenVollständige API-Dokumentation