Referencia API

Rozhrania pre vývojárov: verejné endpointy, chatovací widget, prihlásenie a REST API s API kľúčmi.

Referenčná dokumentácia API popisuje rozhrania Zentor App, ktoré môžete volať z vlastných webov a programov: verejné endpointy pre formuláre, konfigurátor produktu a obsah, chatovací widget, demo chatbota a prihlásenie vrátane jednotného prihlásenia (SSO). Každá stránka endpointu uvádza metódu, cestu, autentifikáciu, parametre, príklad požiadavky a odpovede a zdokumentované chybové kódy.

Autentifikácia: endpointy pre formuláre, konfigurátor produktu a obsah sú dostupné bez prihlásenia. Endpointy chatovacieho widgetu očakávajú vkladací token vášho widgetu v hlavičke `X-Widget-Token` a prijímajú volania len z domén schválených pre daný widget. Prihlasovacie endpointy vydávajú pre používateľské relácie prístupový token (JWT) a token na obnovu (refresh token).

Prístup k API s API kľúčom: pre vlastné programy a spojenia server–server je k dispozícii REST API na základnej URL `https://zentor-app.de/api/v1`. Zentor aktivuje prístup k API pre váš účet na požiadanie. Administrátori potom vytvárajú vlastné kľúče v dashboarde v časti „API kľúče“ a stanovujú ich oprávnenia (scopes) – pre termíny a rezervácie, chatbota, komunikáciu, súbory, znalostnú databázu, reporty a webové dáta. Pre každú oblasť existuje scope na čítanie (`<oblasť>.read`, iba GET) a scope na zápis (`<oblasť>.write`, zahŕňa čítanie), napríklad `appointments.read` alebo `knowledge.write`. Kľúč odošlite v hlavičke `Authorization: Bearer <API kľúč>` alebo alternatívne v hlavičke `X-API-Key`. Pomocou `GET /api/v1/me` skontrolujete, ku ktorému účtu a akým scopes je kľúč priradený.

Úplný kľúč sa zobrazí len raz, pri vytvorení. Uchovávajte ho bezpečne a výhradne na strane servera, nikdy v kóde prehliadača alebo v mobilných aplikáciách. Kľúčom možno nastaviť dátum expirácie, možno ich rotovať a odvolať. Cez REST API sú dostupné len funkcie obsiahnuté vo vašom balíku a všetky dáta zostávajú obmedzené na váš účet. Typické chyby: 401 `API_KEY_INVALID`, `API_KEY_EXPIRED` alebo `API_KEY_REVOKED` (kľúč chýba, je nesprávny, expirovaný alebo odvolaný), 403 `API_ACCESS_NOT_ENABLED` (prístup k API pre účet nie je aktivovaný), 403 `API_SCOPE_MISSING` (kľúču chýba potrebný scope), 403 `TENANT_NOT_ACTIVE` alebo `TENANT_LOCKED` (účet nie je aktívny alebo je uzamknutý) a 404 `API_ENDPOINT_NOT_AVAILABLE` (endpoint nie je cez REST API dostupný).

Odpovede a limity: všetky endpointy odpovedajú formátom JSON. Úspešná odpoveď má stav 2xx a `"ok": true`; chybová odpoveď obsahuje strojovo čitateľný chybový kód (v poli `error` alebo `error.code`) a správu. Na IP adresu je možných 2 000 požiadaviek za 15 minút; pre formulárové, potvrdzovacie a prihlasovacie endpointy platia strožšie limity uvedené na príslušnej stránke. Pri prekročení server odpovie 429 `RATE_LIMIT_EXCEEDED`. Endpointy označené ako neidempotentné by sa po výpadku spojenia nemali automaticky opakovať, inak môžu vzniknúť duplicitné požiadavky alebo správy.

Heslá, tokeny, API kľúče a potvrdzovacie kódy prenášajte iba v tele požiadavky alebo v hlavičkách cez HTTPS – nikdy v URL, protokoloch alebo žiadostiach o podporu.

Autentifikácia (5)Prihlásenie, obnovenie tokenu, reset hesla, dokončenie SSO – a prístup k API pomocou API kľúčov.Verejné formuláre (11)Kontakt, žiadosť o poradenstvo, žiadosť o prístup, platba a aktivácia účtu.Konfigurátor produktu (5)Katalóg balíkov, náhľad ceny, potvrdenie e-mailom a odoslanie konfigurácie.Verejný obsah (6)Právne texty, marketingové stránky, téma a farby textu webu.Chatový widget (9)Všetky endpointy, ktoré používa vložený chatový widget na vašom webe.Demo chatbot a SSO (13)Verejný demo chatbot a endpointy pre jednotné prihlásenie (SAML/OIDC).
← Späť na prehľad