API-referanse
Grensesnitt for utviklere: offentlige endepunkter, chat-widget, innlogging og REST API-et med API-nøkler.
API-referansen beskriver grensesnittene til Zentor App som du kan kalle fra dine egne nettsteder og programmer: offentlige endepunkter for skjemaer, produktkonfigurator og innhold, chat-widgeten, demo-chatboten samt innlogging, inkludert enkel pålogging (SSO). Hver endepunktside angir metode, sti, autentisering, parametre, et eksempel på forespørsel og svar samt de dokumenterte feilkodene.
Autentisering: endepunktene for skjemaer, produktkonfigurator og innhold er tilgjengelige uten innlogging. Chat-widgetens endepunkter forventer innbyggingstokenet til widgeten din i headeren `X-Widget-Token` og godtar bare kall fra domenene som er godkjent for widgeten. Innloggingsendepunktene utsteder et tilgangstoken (JWT) og et refresh-token for brukersesjoner.
API-tilgang med API-nøkkel: for dine egne programmer og server-til-server-integrasjoner er REST API-et tilgjengelig på base-URL-en `https://zentor-app.de/api/v1`. Zentor aktiverer API-tilgang for kontoen din på forespørsel. Deretter opprettheter administratorer sine egne nøkler i dashbordet under «API-nøkler» og fastsetter deres rettigheter (scopes) – for avtaler og bestillinger, chatbot, kommunikasjon, filer, kunnskapsbase, rapporter og webdata. For hvert område finnes et lese-scope (`<område>.read`, bare GET) og et skrive-scope (`<område>.write`, inkluderer lesing), for eksempel `appointments.read` eller `knowledge.write`. Send nøkkelen i headeren `Authorization: Bearer <API-nøkkel>` eller alternativt i headeren `X-API-Key`. Med `GET /api/v1/me` kontrollerer du hvilken konto og hvilke scopes en nøkkel tilhører.
Den fullstendige nøkkelen vises bare én gang, når den opprettes. Lagre den sikkert og kun på serversiden, aldri i nettleserkode eller mobilapper. Nøkler kan få en utløpsdato, roteres og tilbakekalles. Via REST API-et er bare funksjoner som er inkludert i pakken din tilgjengelige, og alle data er begrenset til kontoen din. Typiske feil: 401 `API_KEY_INVALID`, `API_KEY_EXPIRED` eller `API_KEY_REVOKED` (nøkkelen mangler, er feil, utløpt eller tilbakekalt), 403 `API_ACCESS_NOT_ENABLED` (API-tilgang ikke aktivert for kontoen), 403 `API_SCOPE_MISSING` (nøkkelen mangler det nødvendige scope), 403 `TENANT_NOT_ACTIVE` eller `TENANT_LOCKED` (kontoen er ikke aktiv eller er låst) og 404 `API_ENDPOINT_NOT_AVAILABLE` (endepunktet er ikke tilgjengelig via REST API-et).
Svar og grenser: alle endepunkter svarer i JSON. Et vellykket svar har en 2xx-status og `"ok": true`; et feilsvar inneholder en maskinlesbar feilkode (i feltet `error` eller `error.code`) og en melding. Per IP-adresse er 2000 forespørsler innen 15 minutter mulig; for skjema-, bekreftelses- og innloggingsendepunkter gjelder strengere grenser, som er angitt på den respektive siden. Ved overskridelse svarer serveren med 429 `RATE_LIMIT_EXCEEDED`. Endepunkter som er merket som ikke idempotente, bør ikke gjentas automatisk etter et tilkoblingsavbrudd, siden dette kan skape dupliserte forespørsler eller meldinger.
Overfør passord, tokener, API-nøkler og bekreftelseskoder bare i forespørselskroppen eller i headere via HTTPS – aldri i URL-er, logger eller supportforespørsler.