API-Übersicht

Pro Plan

Die Zenovay API bietet programmatischen Zugriff auf Ihre Analysedaten. Erstellen Sie benutzerdefinierte Integrationen, automatisieren Sie Workflows und erweitern Sie die Funktionen von Zenovay.

Was Sie tun können

Externe API (API-Key-Authentifizierung)

Funktion	Endpoint
Analyseübersicht	GET /api/external/v1/analytics/:websiteId
Besucherdaten	GET /api/external/v1/analytics/:websiteId/visitors
Seitenanalysen	GET /api/external/v1/analytics/:websiteId/pages
Länderdaten	GET /api/external/v1/analytics/:websiteId/countries
Technologie-Aufschlüsselung	GET /api/external/v1/analytics/:websiteId/technology
Websites auflisten	GET /api/external/v1/websites
Website-Details	GET /api/external/v1/websites/:websiteId
API-Nutzung	GET /api/external/v1/usage
Heatmap-Seiten	GET /api/external/v1/heatmaps/:websiteId/pages
Sitzungsaufzeichnungen	GET /api/external/v1/replays/:websiteId/sessions
Fehlergruppen	GET /api/external/v1/errors/:websiteId/groups

Tracking (Öffentlich)

Diese Endpoints werden vom Tracking-Script verwendet — kein API-Key erforderlich.

Funktion	Endpoint
Seitenaufruf/Event tracken	POST /e/:trackingCode
Live-Besucherzahl	GET /e/live/:trackingCode
Heartbeat	POST /e/heartbeat/:trackingCode

API-Zugriff nach Tarif

Die REST API ist eine bezahlte Funktion. Kostenlose Arbeitsbereiche können keine API-Keys erstellen oder verwenden — die oben aufgelisteten nicht authentifizierten Tracking-Endpoints bleiben bei jedem Tarif verfügbar.

Tarif	API-Zugriff	Anfragen/Minute	Monatliches Limit
Free	Nicht verfügbar	—	—
Pro	Vollständig	30	10.000
Scale	Vollständig	60	100.000
Enterprise	Vollständig	120	1.000.000

Basis-URL

Die Basis-URL der externen API lautet:

https://api.zenovay.com/api/external/v1

Authentifizierung

API-Keys

Authentifizieren Sie sich mit API-Keys über den X-API-Key-Header oder den Authorization: Bearer-Header:

curl https://api.zenovay.com/api/external/v1/websites \
  -H "X-API-Key: zv_YOUR_API_KEY"

Oder mit Bearer-Authentifizierung:

curl https://api.zenovay.com/api/external/v1/websites \
  -H "Authorization: Bearer zv_YOUR_API_KEY"

API-Keys beginnen immer mit dem Präfix zv_.

Ihren API-Key erhalten

1. Gehen Sie zu Einstellungen → Sicherheit und öffnen Sie den Bereich API-Keys
2. Klicken Sie auf „API-Key erstellen"
3. Benennen Sie Ihren Key
4. Legen Sie den Umfang fest (alle Websites oder eine einzelne Website)
5. Kopieren Sie den Key (wird nur einmal angezeigt)

API-Keys erfordern einen Pro-Tarif oder höher. Bei einem kostenlosen Tarif ist die Schaltfläche zum Erstellen deaktiviert.

Weitere Details finden Sie unter Authentifizierung.

Schnellstart

Ihre Websites auflisten

curl https://api.zenovay.com/api/external/v1/websites \
  -H "X-API-Key: zv_YOUR_API_KEY"

Analyseübersicht abrufen

Analyse-Endpoints benötigen eine Website-ID (eine UUID — kopieren Sie diese aus der obigen Antwort von „Ihre Websites auflisten") und einen optionalen range (einer von 24h, 7d, 30d, 90d, 1y):

curl "https://api.zenovay.com/api/external/v1/analytics/YOUR_WEBSITE_ID?range=30d" \
  -H "X-API-Key: zv_YOUR_API_KEY"

API-Nutzung prüfen

curl https://api.zenovay.com/api/external/v1/usage \
  -H "X-API-Key: zv_YOUR_API_KEY"

Anfrageformat

Header

Erforderliche Header (verwenden Sie eine Form):

Authorization: Bearer YOUR_API_KEY

X-API-Key: YOUR_API_KEY

Senden Sie Content-Type: application/json bei POST-Anfragen mit JSON-Body.

Optionaler Header:

X-Request-ID: your-unique-id (wird zur Fehlersuche zurückgegeben)

Query-Parameter

Häufige Parameter bei Analyse-Endpoints:

Parameter	Beschreibung	Beispiel
range	Zeitfenster: 24h, 7d, 30d, 90d, 1y (Standard 7d)	?range=30d
limit	Max. Zeilen zum Zurückgeben	?limit=50
offset	Zeilen überspringen (für Paginierung)	?offset=100

Antwortformat

Erfolgreiche Antwort

Erfolgreiche Antworten sind in einer success/data-Hülle verpackt:

{
  "success": true,
  "data": { ... },
  "timestamp": "2026-06-13T00:00:00.000Z"
}

Die Form des data-Objekts hängt vom Endpoint ab (z. B. gibt die Analyseübersicht website, summary und daily_stats zurück). Endpoints, die ihre Ergebnisse seitennummerieren, enthalten ein pagination-Objekt in data.

Fehlerantwort

{
  "success": false,
  "error": {
    "message": "Rate limit exceeded (30 requests/minute). Try again in 12 seconds",
    "code": "RATE_LIMIT_EXCEEDED",
    "timestamp": "2026-06-13T00:00:00.000Z"
  }
}

HTTP-Statuscodes

Code	Bedeutung
200	Erfolg
201	Erstellt
400	Fehlerhafte Anfrage
401	Nicht autorisiert
403	Verboten
404	Nicht gefunden
429	Rate-Limit erreicht
500	Serverfehler

Client-Bibliotheken

Zenovay bietet keine offiziellen SDK-Pakete an. Verwenden Sie stattdessen das CDN-Tracking-Script für browserseitiges Tracking und Standard-HTTP-Anfragen (fetch, requests, curl usw.) für serverseitigen API-Zugriff.

JavaScript (Browser)

Fügen Sie das Tracking-Script zu Ihrem HTML hinzu:

<script defer data-tracking-code="YOUR_TRACKING_CODE" src="https://api.zenovay.com/z.js"></script>

Verwenden Sie dann die globale zenovay-Funktion:

// Events tracken
zenovay('track', 'signup', { plan: 'pro' });

JavaScript (Serverseitig)

Verwenden Sie fetch, um die externe API direkt aufzurufen:

const response = await fetch('https://api.zenovay.com/api/external/v1/analytics/WEBSITE_ID', {
  headers: {
    'X-API-Key': 'zv_YOUR_API_KEY',
  },
});
const data = await response.json();

Python (mit requests)

import requests

response = requests.get(
    'https://api.zenovay.com/api/external/v1/analytics/WEBSITE_ID',
    headers={'X-API-Key': 'zv_YOUR_API_KEY'}
)
data = response.json()

Häufige Anwendungsfälle

Benutzerdefinierte Dashboards

Erstellen Sie interne Dashboards:

• Aggregierte Metriken abrufen
• Benutzerdefinierte Visualisierungen erstellen
• Mit anderen Daten kombinieren

Automatisierte Berichterstattung

Erstellen Sie benutzerdefinierte Berichte:

• Wöchentliche Stakeholder-Berichte
• Echtzeit-Benachrichtigungen
• Schwellenwert-Überwachung

CRM-Integration

Verbindung mit Ihrem CRM:

• Besucherdaten übertragen
• Kontaktdatensätze aktualisieren
• Workflows auslösen

Rate-Limits

Die Rate-Limits der externen API gelten pro API-Key, pro Minute, und hängen vom Tarif des Teams ab, zu dem der Key gehört:

Tarif	Anfragen/Minute	Monatliches Limit
Pro	30	10.000
Scale	60	100.000
Enterprise	120	1.000.000

Rate-Limit-Header

Antworten enthalten Nutzungs- und Rate-Limit-Header:

X-RateLimit-Limit: 30
X-Usage-Monthly: 4521
X-Usage-Limit: 10000
X-Usage-Reset: 2026-07-01T00:00:00.000Z

X-RateLimit-Remaining wird einbezogen, wenn verfügbar. Wenn Sie ein Limit überschreiten, gibt die API 429 mit einem Retry-After-Header zurück.

Weitere Informationen finden Sie unter Rate-Limits.

Best Practices

Effiziente Anfragen

• Nur benötigte Felder anfordern
• Datumsfilter verwenden
• Große Ergebnisse paginieren
• Wenn möglich cachen

Fehlerbehandlung

• Wiederholungsversuche implementieren
• Rate-Limits behandeln
• Fehler protokollieren
• Erfolgsraten überwachen

Sicherheit

• Keys geheim halten
• Minimale Berechtigungen verwenden
• Keys regelmäßig rotieren
• Key-Nutzung überprüfen

Testen

Es gibt keine separate Sandbox — testen Sie mit einem dedizierten Key gegen Produktion:

1. Gehen Sie zu Einstellungen → Sicherheit und öffnen Sie den Bereich API-Keys
2. Erstellen Sie einen Key und geben Sie ihm einen erkennbaren Namen (z. B. „Test")
3. Beschränken Sie ihn auf eine einzelne Test-Website, falls möglich
4. Verwenden Sie die Standard-API-URL: https://api.zenovay.com/api/external/v1/
5. Löschen Sie den Key nach Abschluss

Support

Hilfe erhalten

• API-Dokumentation: docs.zenovay.com/api
• E-Mail: [email protected]

Changelog

Verfolgen Sie Produkt- und API-Änderungen unter docs.zenovay.com/changelog.

Nächste Schritte

• Authentifizierung & API-Keys
• REST-API-Referenz
• Rate-Limits