Referenca API
Vmesniki za razvijalce: javne končne točke, klepetalni gradnik, prijava in REST API s ključi API.
Referenčna dokumentacija API opisuje vmesnike Zentor App, ki jih lahko kličete iz lastnih spletnih mest in programov: javne končne točke za obrazce, konfigurator izdelkov in vsebine, klepetalni gradnik, demo klepetalni robot ter prijavo, vključno z enotno prijavo (SSO). Stran vsake končne točke navaja metodo, pot, avtentikacijo, parametre, primer zahteve in odgovora ter dokumentirane kode napak.
Avtentikacija: končne točke za obrazce, konfigurator izdelkov in vsebine so dosegljive brez prijave. Končne točke klepetalnega gradnika pričakujejo žeton za vdelavo vašega gradnika v glavi `X-Widget-Token` in sprejemajo klice samo z domen, odobrenih za ta gradnik. Končne točke za prijavo za uporabniške seje izdajo dostopni žeton (JWT) in žeton za obnovitev.
Dostop do API s ključem API: za lastne programe in povezave strežnik-strežnik je na voljo REST API na osnovnem naslovu URL `https://zentor-app.de/api/v1`. Zentor na zahtevo omogoči dostop do API za vaš račun. Nato administratorji na nadzorni plošči pod „Ključi API“ ustvarijo lastne ključe in določijo njihova pooblastila (scope) – za termine in rezervacije, klepetalnega robota, komunikacijo, datoteke, bazo znanja, poročila in spletne podatke. Za vsako področje obstaja scope za branje (`<področje>.read`, samo GET) in scope za pisanje (`<področje>.write`, vključuje branje), na primer `appointments.read` ali `knowledge.write`. Ključ pošljite v glavi `Authorization: Bearer <ključ API>` ali alternativno v glavi `X-API-Key`. S `GET /api/v1/me` preverite, kateremu računu in katerim scope-om je ključ dodeljen.
Celoten ključ se prikaže samo enkrat, ob ustvarjanju. Shranite ga varno in izključno na strani strežnika, nikoli v kodi brskalnika ali mobilnih aplikacijah. Ključi lahko dobijo datum poteka, se lahko rotirajo in prekličejo. Prek REST API so dosegljive samo funkcije, vključene v vaš paket, vsi podatki pa so omejeni na vaš račun. Tipične napake: 401 `API_KEY_INVALID`, `API_KEY_EXPIRED` ali `API_KEY_REVOKED` (ključ manjka, je napačen, potekel ali preklican), 403 `API_ACCESS_NOT_ENABLED` (dostop do API za račun ni omogočen), 403 `API_SCOPE_MISSING` (ključu manjka potreben scope), 403 `TENANT_NOT_ACTIVE` ali `TENANT_LOCKED` (račun ni aktiven ali je zaklenjen) in 404 `API_ENDPOINT_NOT_AVAILABLE` (končna točka ni dosegljiva prek REST API).
Odgovori in omejitve: vse končne točke odgovarjajo v obliki JSON. Uspešen odgovor ima status 2xx in `"ok": true`; odgovor z napako vsebuje mašinsko berljivo kodo napake (v polju `error` oziroma `error.code`) in sporočilo. Na IP-naslov je mogočih 2000 zahtev v 15 minutah; za končne točke obrazcev, potrditve in prijave veljajo strožje omejitve, navedene na posamezni strani. Ob prekoračitvi strežnik odgovori s 429 `RATE_LIMIT_EXCEEDED`. Končnih točk, označenih kot neidempotentnih, po prekinitvi povezave ne smete samodejno ponavljati, saj lahko to povzroči podvojene zahteve ali sporočila.
Gesla, žetone, ključe API in potrditvene kode prenašajte samo v telesu zahteve oziroma v glavah prek HTTPS – nikoli v URL-jih, dnevnikih ali podpornih zahtevkih.