REST-API (/v1) Verfügbar (v1)
Die öffentliche REST-API liegt unter der Basis https://ingest.visz.ai/v1;
alle Endpoints sind /v1/…-Pfade (der nackte Host https://ingest.visz.ai/
liefert kein Dokument). Sie ist die HTTP-Ingest-Oberfläche, also dieselben
Endpoints, die das Tracking-Snippet unter der Haube aufruft. Die meisten fassen
sie nie direkt an (nimm stattdessen die JavaScript-API);
für server-seitige Ingestion und eigene Clients ist sie hier aber vollständig
dokumentiert.
Authentifizierung
Alle /v1/ingest/*-Routen brauchen deinen öffentlichen Tracking-Key
(vz_…), am besten im X-Tracking-Key-Header. Der Server nimmt ihn
ersatzweise auch als Feld tracking_key im JSON-Body an. Der Key steckt in
deinem Snippet und ist bewusst öffentlich.
POST /v1/ingest/event-batch HTTP/1.1
Host: ingest.visz.ai
Content-Type: application/json
X-Tracking-Key: vz_your_key/v1/health und die öffentlichen /v1/share/{token}-Routen brauchen keine
Authentifizierung.
Herkunftsprüfung
Schickt ein Request einen Origin- oder Referer-Header, muss dessen Host zur
Domain der Website passen (die Domain selbst, ihre www.-Variante oder eine
Subdomain). Ein fremder Host bekommt 403 mit ORIGIN_NOT_ALLOWED. Requests
ganz ohne diese Header, etwa von deinem Server, lässt die API durch.
Consent-Gate
Die API erzwingt Consent beim session-start: Ist consent.state nicht
"granted", antwortet der Server mit 202 und legt weder Besucher noch Sitzung
an. Gespeichert wird dann nur ein Consent-Protokolleintrag als Nachweis der
Entscheidung, ohne Besucherkennung.
Interaktive Referenz
Die vollständige, interaktive Referenz unten wird aus der OpenAPI-3.1-Spezifikation der Ingest-API erzeugt: jeder Endpoint, jedes Schema, jedes Beispiel und jeder Error-Code.
Rate-Limits & Fehler
Jede Route ist über Redis rate-limitiert, je Zeitfenster und je Tracking-Key
plus anonymisierter IP oder je Tracking-Key plus Sitzung. Überschreitest du das
Limit, bekommst du 429 mit dem Code RATE_LIMITED und einem
Retry-After-Header. Alle Fehler teilen sich eine Hülle:
{
"error": {
"code": "INVALID_TRACKING_KEY",
"message": "Der Tracking-Schlüssel ist unbekannt oder deaktiviert.",
"request_id": "0192f3a4-b5c6-7d8e-9f01-23456789abcd",
"retry_after": null
}
}request_id ist die Kennung des Requests; schickst du einen
X-Request-Id-Header mit, übernimmt die API dessen Wert. retry_after nennt
bei 429 die Wartezeit in Sekunden. Bei Validierungsfehlern kommt ein Feld
details hinzu. Der Text in message ist auf Deutsch; verzweige über code,
nicht über message. Häufige Codes sind INVALID_TRACKING_KEY,
ORIGIN_NOT_ALLOWED, RATE_LIMITED und SHARE_NOT_FOUND. Die vollständige
Liste je Endpoint steht in der interaktiven Referenz oben.
Zuletzt aktualisiert: