API-Referenz
Schnittstellen für Entwickler: öffentliche Endpunkte, Chat-Widget, Anmeldung und REST-API mit API-Schlüssel.
Die API-Referenz beschreibt die Schnittstellen von Zentor App, die Sie aus eigenen Websites und Programmen ansprechen können: öffentliche Endpunkte für Formulare, Produktkonfigurator und Inhalte, das Chat-Widget, den Demo-Chatbot sowie die Anmeldung einschließlich Single Sign-On. Jede Endpunktseite nennt Methode, Pfad, Authentifizierung, Parameter, ein Beispiel für Anfrage und Antwort und die dokumentierten Fehlercodes.
Authentifizierung: Die Endpunkte für Formulare, Produktkonfigurator und Inhalte sind ohne Anmeldung erreichbar. Die Endpunkte des Chat-Widgets erwarten den Embed-Token Ihres Widgets im Header `X-Widget-Token` und nehmen Aufrufe nur von den für das Widget freigegebenen Domains an. Die Anmelde-Endpunkte geben für Benutzersitzungen ein Zugangstoken (JWT) und ein Refresh-Token aus.
API-Zugang mit API-Schlüssel: Für eigene Programme und Server-zu-Server-Anbindungen steht die REST-API unter der Basis-URL `https://zentor-app.de/api/v1` zur Verfügung. Zentor schaltet den API-Zugang auf Anfrage für Ihr Konto frei. Danach erzeugen Administratoren im Dashboard unter „API-Schlüssel“ eigene Schlüssel und legen deren Berechtigungen (Scopes) fest – für Termine und Buchungen, Chatbot, Kommunikation, Dateien, Wissensdatenbank, Berichte und Webdaten. Je Bereich gibt es einen Lese-Scope (`<bereich>.read`, nur GET) und einen Schreib-Scope (`<bereich>.write`, schließt Lesen ein), zum Beispiel `appointments.read` oder `knowledge.write`. Senden Sie den Schlüssel im Header `Authorization: Bearer <API-Schlüssel>` oder alternativ im Header `X-API-Key`. Mit `GET /api/v1/me` prüfen Sie, welchem Konto und welchen Scopes ein Schlüssel zugeordnet ist.
Der vollständige Schlüssel wird nur einmal beim Erzeugen angezeigt. Bewahren Sie ihn sicher und ausschließlich serverseitig auf, nie in Browser-Code oder mobilen Apps. Schlüssel können ein Ablaufdatum erhalten, rotiert und widerrufen werden. Über die REST-API sind nur Funktionen erreichbar, die in Ihrem Paket enthalten sind, und alle Daten bleiben auf Ihr Konto beschränkt. Typische Fehler: 401 `API_KEY_INVALID`, `API_KEY_EXPIRED` oder `API_KEY_REVOKED` (Schlüssel fehlt, ist falsch, abgelaufen oder widerrufen), 403 `API_ACCESS_NOT_ENABLED` (API-Zugang für das Konto nicht freigeschaltet), 403 `API_SCOPE_MISSING` (dem Schlüssel fehlt der nötige Scope), 403 `TENANT_NOT_ACTIVE` oder `TENANT_LOCKED` (Konto nicht aktiv oder gesperrt) und 404 `API_ENDPOINT_NOT_AVAILABLE` (Endpunkt ist über die REST-API nicht verfügbar).
Antworten und Limits: Alle Endpunkte antworten mit JSON. Eine erfolgreiche Antwort hat einen 2xx-Status und `"ok": true`; eine Fehlerantwort enthält einen maschinenlesbaren Fehlercode (im Feld `error` bzw. `error.code`) und eine Meldung. Je IP-Adresse sind 2.000 Anfragen innerhalb von 15 Minuten möglich; für Formular-, Bestätigungs- und Anmelde-Endpunkte gelten strengere Limits, die auf der jeweiligen Seite genannt sind. Bei Überschreitung antwortet der Server mit 429 `RATE_LIMIT_EXCEEDED`. Endpunkte, die als nicht idempotent gekennzeichnet sind, sollten nach einem Verbindungsabbruch nicht automatisch wiederholt werden, da sonst doppelte Anfragen oder Nachrichten entstehen können.
Übertragen Sie Passwörter, Tokens, API-Schlüssel und Bestätigungscodes nur im Request-Body bzw. in Headern über HTTPS – nicht in URLs, Protokollen oder Support-Anfragen.