Referință API
Interfețe pentru dezvoltatori: endpointuri publice, widget de chat, autentificare și API REST cu chei API.
Referința API descrie interfețele Zentor App pe care le puteți apela din propriile site-uri și programe: endpointuri publice pentru formulare, configuratorul de produs și conținut, widgetul de chat, chatbotul demo, precum și autentificarea, inclusiv autentificarea unică (SSO). Fiecare pagină de endpoint indică metoda, calea, autentificarea, parametrii, un exemplu de cerere și răspuns, și codurile de eroare documentate.
Autentificare: endpointurile pentru formulare, configuratorul de produs și conținut sunt accesibile fără autentificare. Endpointurile widgetului de chat se așteaptă la tokenul de încorporare al widgetului dumneavoastră în antetul `X-Widget-Token` și acceptă apeluri doar din domeniile aprobate pentru acel widget. Endpointurile de autentificare emit un token de acces (JWT) și un token de reîmprospătare (refresh token) pentru sesiunile utilizatorilor.
Acces API cu cheie API: pentru propriile programe și conexiunile server-la-server, API-ul REST este disponibil la URL-ul de bază `https://zentor-app.de/api/v1`. Zentor activează accesul API pentru contul dumneavoastră la cerere. Administratorii creează apoi propriile chei în panoul de control, la „Chei API”, și stabilesc permisiunile acestora (scopuri) – pentru programări și rezervări, chatbot, comunicare, fișiere, bază de cunoștințe, rapoarte și date web. Fiecare domeniu are un scop de citire (`<domeniu>.read`, doar GET) și un scop de scriere (`<domeniu>.write`, care include citirea), de exemplu `appointments.read` sau `knowledge.write`. Trimiteți cheia în antetul `Authorization: Bearer <cheie API>` sau, alternativ, în antetul `X-API-Key`. Folosiți `GET /api/v1/me` pentru a verifica cărui cont și căror scopuri este asociată o cheie.
Cheia completă este afișată o singură dată, la creare. Păstrați-o în siguranță și exclusiv pe server, niciodată în codul browserului sau în aplicații mobile. Cheile pot primi o dată de expirare, pot fi rotite și revocate. Prin API-ul REST sunt accesibile doar funcțiile incluse în pachetul dumneavoastră, iar toate datele rămân limitate la contul dumneavoastră. Erori tipice: 401 `API_KEY_INVALID`, `API_KEY_EXPIRED` sau `API_KEY_REVOKED` (cheie lipsă, incorectă, expirată sau revocată), 403 `API_ACCESS_NOT_ENABLED` (acces API neactivat pentru cont), 403 `API_SCOPE_MISSING` (cheii îi lipsește scopul necesar), 403 `TENANT_NOT_ACTIVE` sau `TENANT_LOCKED` (cont inactiv sau blocat) și 404 `API_ENDPOINT_NOT_AVAILABLE` (endpoint indisponibil prin API-ul REST).
Răspunsuri și limite: toate endpointurile răspund cu JSON. Un răspuns de succes are un status 2xx și `"ok": true`; un răspuns de eroare conține un cod de eroare care poate fi citit de o maşină (în câmpul `error` sau `error.code`) și un mesaj. Pe adresă IP sunt posibile 2.000 de cereri în 15 minute; pentru endpointurile de formulare, confirmare și autentificare se aplică limite mai stricte, indicate pe pagina respectivă. În caz de depășire, serverul răspunde cu 429 `RATE_LIMIT_EXCEEDED`. Endpointurile marcate ca neidempotente nu ar trebui reluate automat după o întrerupere a conexiunii, altfel pot apărea cereri sau mesaje duplicate.
Transmiteți parolele, tokenurile, cheile API și codurile de confirmare doar în corpul cererii sau în anteturi prin HTTPS – niciodată în URL-uri, jurnale sau cereri de asistență.