Riferimento API
Interfacce per sviluppatori: endpoint pubblici, widget di chat, accesso e API REST con chiavi API.
Il riferimento API descrive le interfacce di Zentor App che potete chiamare dai vostri siti web e programmi: endpoint pubblici per moduli, configuratore di prodotto e contenuti, il widget di chat, il chatbot demo, oltre all'accesso, incluso il Single Sign-On (SSO). Ogni pagina di endpoint indica il metodo, il percorso, l'autenticazione, i parametri, un esempio di richiesta e risposta, e i codici di errore documentati.
Autenticazione: gli endpoint per moduli, configuratore di prodotto e contenuti sono accessibili senza accesso. Gli endpoint del widget di chat si aspettano il token di incorporamento del vostro widget nell'header `X-Widget-Token` e accettano solo chiamate dai domini approvati per quel widget. Gli endpoint di accesso rilasciano un token di accesso (JWT) e un token di rinnovo (refresh token) per le sessioni utente.
Accesso API con chiave API: per i vostri programmi e le connessioni server-to-server, l'API REST è disponibile all'URL base `https://zentor-app.de/api/v1`. Zentor attiva l'accesso API per il vostro account su richiesta. Gli amministratori creano poi le proprie chiavi nella dashboard, in «Chiavi API», e ne definiscono i permessi (scope) – per appuntamenti e prenotazioni, chatbot, comunicazione, file, base di conoscenza, report e dati web. Ogni area dispone di uno scope di lettura (`<area>.read`, solo GET) e di uno scope di scrittura (`<area>.write`, che include la lettura), ad esempio `appointments.read` o `knowledge.write`. Inviate la chiave nell'header `Authorization: Bearer <chiave API>` oppure, in alternativa, nell'header `X-API-Key`. Usate `GET /api/v1/me` per verificare a quale account e a quali scope è associata una chiave.
La chiave completa viene mostrata solo una volta, alla creazione. Conservatela in modo sicuro ed esclusivamente lato server, mai nel codice del browser o in app mobili. Alle chiavi può essere assegnata una data di scadenza, possono essere ruotate e revocate. Tramite l'API REST sono accessibili solo le funzioni incluse nel vostro pacchetto, e tutti i dati restano limitati al vostro account. Errori tipici: 401 `API_KEY_INVALID`, `API_KEY_EXPIRED` o `API_KEY_REVOKED` (chiave mancante, errata, scaduta o revocata), 403 `API_ACCESS_NOT_ENABLED` (accesso API non attivato per l'account), 403 `API_SCOPE_MISSING` (alla chiave manca lo scope necessario), 403 `TENANT_NOT_ACTIVE` o `TENANT_LOCKED` (account non attivo o bloccato) e 404 `API_ENDPOINT_NOT_AVAILABLE` (endpoint non disponibile tramite l'API REST).
Risposte e limiti: tutti gli endpoint rispondono con JSON. Una risposta riuscita ha uno stato 2xx e `"ok": true`; una risposta di errore contiene un codice di errore leggibile dalla macchina (nel campo `error` o `error.code`) e un messaggio. Per indirizzo IP sono possibili 2.000 richieste in 15 minuti; per gli endpoint di moduli, conferma e accesso valgono limiti più stretti, indicati sulla pagina corrispondente. In caso di superamento, il server risponde 429 `RATE_LIMIT_EXCEEDED`. Gli endpoint contrassegnati come non idempotenti non dovrebbero essere ritentati automaticamente dopo un'interruzione della connessione, altrimenti possono crearsi richieste o messaggi duplicati.
Trasmettete password, token, chiavi API e codici di conferma solo nel corpo della richiesta o negli header tramite HTTPS, mai in URL, log o richieste di supporto.