API-verwysing
Koppelvlakke vir ontwikkelaars: openbare eindpunte, kletswidget, aanmelding en REST-API met API-sleutels.
Die API-verwysing beskryf die koppelvlakke van Zentor App wat u uit eie webwerwe en programme kan aanspreek: openbare eindpunte vir vorms, produkkonfigurator en inhoud, die kletswidget, die demo-kletsbot asook die aanmelding insluitend enkelaanmelding. Elke eindpuntblad noem die metode, pad, verifikasie, parameters, 'n voorbeeld van versoek en antwoord en die gedokumenteerde foutkodes.
Verifikasie: die eindpunte vir vorms, produkkonfigurator en inhoud is sonder aanmelding bereikbaar. Die eindpunte van die kletswidget verwag die inbedtoken van u widget in die header `X-Widget-Token` en aanvaar slegs oproepe van die vir die widget goedgekeurde domeine. Die aanmeld-eindpunte gee vir gebruikerssessies 'n toegangstoken (JWT) en 'n vernuwingstoken uit.
API-toegang met API-sleutel: vir eie programme en bediener-na-bediener-koppelings is die REST-API by die basis-URL `https://zentor-app.de/api/v1` beskikbaar. Zentor skakel die API-toegang op versoek vir u rekening vry. Daarna skep administrateurs in die kontrolepaneel onder „API-sleutels“ eie sleutels en bepaal hul regte (scopes) – vir afsprake en besprekings, kletsbot, kommunikasie, lêers, kennisbasis, verslae en webdata. Per gebied is daar 'n leesscope (`<gebied>.read`, slegs GET) en 'n skryfscope (`<gebied>.write`, sluit lees in), byvoorbeeld `appointments.read` of `knowledge.write`. Stuur die sleutel in die header `Authorization: Bearer <API-sleutel>` of alternatiewelik in die header `X-API-Key`. Met `GET /api/v1/me` kontroleer u aan welke rekening en welke scopes 'n sleutel toegewys is.
Die volledige sleutel word slegs een keer by die skepping getoon. Bewaar dit veilig en uitsluitlik serverkant, nooit in blaaierkode of mobiele toepassings nie. Sleutels kan 'n verstryksdatum kry, geroteer en herroep word. Via die REST-API is slegs funksies bereikbaar wat in u pakket ingesluit is, en alle data bly tot u rekening beperk. Tipiese foute: 401 `API_KEY_INVALID`, `API_KEY_EXPIRED` of `API_KEY_REVOKED` (sleutel ontbreek, is verkeerd, verstryk of herroep), 403 `API_ACCESS_NOT_ENABLED` (API-toegang vir die rekening nie vrygeskakel nie), 403 `API_SCOPE_MISSING` (die sleutel het nie die nodige scope nie), 403 `TENANT_NOT_ACTIVE` of `TENANT_LOCKED` (rekening nie aktief of gesluit nie) en 404 `API_ENDPOINT_NOT_AVAILABLE` (eindpunt is nie via die REST-API beskikbaar nie).
Antwoorde en perke: alle eindpunte antwoord met JSON. 'n Suksesvolle antwoord het 'n 2xx-status en `"ok": true`; 'n foutantwoord bevat 'n masjienleesbare foutkode (in die veld `error` of `error.code`) en 'n boodskap. Per IP-adres is 2 000 versoeke binne 15 minute moontlik; vir vorm-, bevestigings- en aanmeld-eindpunte geld strenger perke, wat op die betrokke bladsy genoem word. By oorskryding antwoord die bediener met 429 `RATE_LIMIT_EXCEEDED`. Eindpunte wat as nie-idempotent gemerk is, behoort ná 'n verbindingsonderbreking nie outomaties herhaal te word nie, omdat dit anders dubbele versoeke of boodskappe kan skep.
Stuur wagwoorde, tokens, API-sleutels en bevestigingskodes slegs in die versoekliggaam of in headers via HTTPS – nie in URL's, logs of ondersteuningsnavrae nie.