API-referens

Gränssnitt för utvecklare: offentliga slutpunkter, chattwidget, inloggning och REST-API:et med API-nycklar.

API-referensen beskriver Zentor Apps gränssnitt som du kan anropa från dina egna webbplatser och program: offentliga slutpunkter för formulär, produktkonfiguratorn och innehåll, chattwidgeten, demo-chattboten samt inloggning, inklusive enkel inloggning (SSO). Varje slutpunktssida anger metod, sökväg, autentisering, parametrar, ett exempel på förfrågan och svar samt de dokumenterade felkoderna.

Autentisering: slutpunkterna för formulär, produktkonfiguratorn och innehåll kan nås utan inloggning. Chattwidgetens slutpunkter förväntar sig din widgets inbäddningstoken i headern `X-Widget-Token` och accepterar endast anrop från de domäner som godkänts för widgeten. Inloggningsslutpunkterna utfärdar en åtkomsttoken (JWT) och en refresh-token för användarsessioner.

API-åtkomst med API-nyckel: för dina egna program och server-till-server-integrationer finns REST-API:et tillgängligt på bas-URL:en `https://zentor-app.de/api/v1`. Zentor aktiverar API-åtkomst för ditt konto på begäran. Därefter skapar administratörer egna nycklar i kontrollpanelen under ”API-nycklar” och definierar deras behörigheter (scopes) – för möten och bokningar, chattbot, kommunikation, filer, kunskapsdatabas, rapporter och webbdata. För varje område finns ett läs-scope (`<område>.read`, endast GET) och ett skriv-scope (`<område>.write`, inkluderar läsning), till exempel `appointments.read` eller `knowledge.write`. Skicka nyckeln i headern `Authorization: Bearer <API-nyckel>` eller alternativt i headern `X-API-Key`. Med `GET /api/v1/me` kontrollerar du vilket konto och vilka scopes en nyckel tillhör.

Den fullständiga nyckeln visas bara en gång, vid skapandet. Förvara den säkert och enbart på serversidan, aldrig i webbläsarkod eller mobilappar. Nycklar kan få ett utgångsdatum, roteras och återkallas. Via REST-API:et är endast funktioner som ingår i ditt paket tillgängliga, och alla data är begränsade till ditt konto. Typiska fel: 401 `API_KEY_INVALID`, `API_KEY_EXPIRED` eller `API_KEY_REVOKED` (nyckeln saknas, är felaktig, utgången eller återkallad), 403 `API_ACCESS_NOT_ENABLED` (API-åtkomst inte aktiverad för kontot), 403 `API_SCOPE_MISSING` (nyckeln saknar nödvändigt scope), 403 `TENANT_NOT_ACTIVE` eller `TENANT_LOCKED` (kontot är inte aktivt eller är låst) och 404 `API_ENDPOINT_NOT_AVAILABLE` (slutpunkten är inte tillgänglig via REST-API:et).

Svar och gränser: alla slutpunkter svarar i JSON. Ett lyckat svar har en 2xx-status och `"ok": true`; ett felsvar innehåller en maskinläsbar felkod (i fältet `error` eller `error.code`) och ett meddelande. Per IP-adress är 2 000 förfrågningar inom 15 minuter möjliga; för formulär-, bekräftelse- och inloggningsslutpunkter gäller striktare gränser, som anges på respektive sida. Vid överskridande svarar servern med 429 `RATE_LIMIT_EXCEEDED`. Slutpunkter som är markerade som inte idempotenta bör inte upprepas automatiskt efter ett anslutningsavbrott, eftersom detta kan skapa duplicerade förfrågningar eller meddelanden.

Överför lösenord, tokens, API-nycklar och bekräftelsekoder endast i förfrågans kropp eller i headrar via HTTPS – aldrig i URL:er, loggar eller supportförfrågningar.

Autentisering (5)Inloggning, tokenförnyelse, återställning av lösenord, SSO-avslutning – och API-åtkomst med API-nyckel.Offentliga formulär (11)Kontakt, rådgivningsförfrågan, åtkomstbegäran, betalning och kontoaktivering.Produktkonfigurator (5)Paketkatalog, prisförhandsvisning, e-postbekräftelse och inlämning av konfiguration.Offentligt innehåll (6)Juridiska texter, marknadsföringssidor, webbplatsens tema och textfärger.Chattwidget (9)Alla slutpunkter som den inbäddade chattwidgeten på din webbplats använder.Demo-chattbot och SSO (13)Den offentliga demo-chattboten samt slutpunkterna för enkel inloggning (SAML/OIDC).
← Tillbaka till översikten