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.

Avtentikacija (5)Prijava, obnovitev žetona, ponastavitev gesla, zaključek SSO – in dostop API s ključem API.Javni obrazci (11)Kontakt, zahteva za svetovanje, zahteva za dostop, plačilo in aktivacija računa.Konfigurator izdelka (5)Katalog paketov, predogled cene, potrditev e-poštnega naslova in oddaja konfiguracije.Javne vsebine (6)Pravna besedila, marketinške strani, tema in barve besedila spletnega mesta.Klepetalni gradnik (9)Vse končne točke, ki jih uporablja vdelan klepetalni gradnik na vašem spletnem mestu.Demo klepetalni robot in SSO (13)Javni demo klepetalni robot ter končne točke za enotno prijavo (SAML/OIDC).
← Nazaj na pregled