API-referentie
Interfaces voor ontwikkelaars: publieke endpoints, chatwidget, aanmelding en de REST API met API-sleutels.
De API-referentie beschrijft de interfaces van Zentor App die u vanuit uw eigen websites en programma's kunt aanroepen: publieke endpoints voor formulieren, de productconfigurator en content, de chatwidget, de demo-chatbot en aanmelding inclusief single sign-on (SSO). Elke endpointpagina vermeldt de methode, het pad, de authenticatie, de parameters, een voorbeeld van verzoek en antwoord, en de gedocumenteerde foutcodes.
Authenticatie: de endpoints voor formulieren, productconfigurator en content zijn zonder aanmelding bereikbaar. De endpoints van de chatwidget verwachten het embed-token van uw widget in de header `X-Widget-Token` en accepteren alleen aanroepen vanaf de voor de widget goedgekeurde domeinen. De aanmeldendpoints geven voor gebruikerssessies een toegangstoken (JWT) en een refresh-token uit.
API-toegang met API-sleutel: voor uw eigen programma's en server-naar-server-koppelingen is de REST API beschikbaar op de basis-URL `https://zentor-app.de/api/v1`. Zentor geeft de API-toegang voor uw account op aanvraag vrij. Vervolgens maken beheerders in het dashboard onder “API-sleutels” eigen sleutels aan en leggen de bijbehorende rechten (scopes) vast – voor afspraken en boekingen, chatbot, communicatie, bestanden, kennisbank, rapporten en webgegevens. Per gebied is er een leesscope (`<gebied>.read`, alleen GET) en een schrijfscope (`<gebied>.write`, inclusief lezen), bijvoorbeeld `appointments.read` of `knowledge.write`. Stuur de sleutel in de header `Authorization: Bearer <API-sleutel>` of, als alternatief, in de header `X-API-Key`. Gebruik `GET /api/v1/me` om te controleren bij welk account en welke scopes een sleutel behoort.
De volledige sleutel wordt slechts eenmaal getoond, bij het aanmaken. Bewaar hem veilig en uitsluitend serverzijdig, nooit in browsercode of mobiele apps. Sleutels kunnen een vervaldatum krijgen en kunnen worden geroteerd en ingetrokken. Via de REST API zijn alleen functies bereikbaar die in uw pakket zijn opgenomen, en alle gegevens blijven beperkt tot uw account. Typische fouten: 401 `API_KEY_INVALID`, `API_KEY_EXPIRED` of `API_KEY_REVOKED` (sleutel ontbreekt, is onjuist, verlopen of ingetrokken), 403 `API_ACCESS_NOT_ENABLED` (API-toegang voor het account niet geactiveerd), 403 `API_SCOPE_MISSING` (de sleutel mist de benodigde scope), 403 `TENANT_NOT_ACTIVE` of `TENANT_LOCKED` (account niet actief of geblokkeerd) en 404 `API_ENDPOINT_NOT_AVAILABLE` (endpoint niet beschikbaar via de REST API).
Antwoorden en limieten: alle endpoints antwoorden met JSON. Een succesvol antwoord heeft een 2xx-status en `"ok": true`; een foutantwoord bevat een machineleesbare foutcode (in het veld `error` of `error.code`) en een melding. Per IP-adres zijn 2.000 aanvragen binnen 15 minuten mogelijk; voor formulier-, bevestigings- en aanmeldendpoints gelden strengere limieten, vermeld op de betreffende pagina. Bij overschrijding antwoordt de server met 429 `RATE_LIMIT_EXCEEDED`. Endpoints die als niet-idempotent zijn gemarkeerd, mogen na een verbindingsonderbreking niet automatisch opnieuw worden geprobeerd, anders kunnen dubbele aanvragen of berichten ontstaan.
Verzend wachtwoorden, tokens, API-sleutels en bevestigingscodes alleen in de requestbody of in headers via HTTPS — nooit in URL's, logs of supportaanvragen.