Widget chat
Tutti gli endpoint utilizzati dal widget chat incorporato nei siti dei clienti.
Questo gruppo riunisce tutti gli endpoint pubblici utilizzati dal widget chat incorporato nei siti clienti: controllo raggiungibilità (`GET /api/public/widget/health`), recupero della configurazione pubblica Widget (`GET /api/public/widget/config/:widget_code`) nonché invio e cronologia messaggi (`POST /api/public/widget/message`, `GET /api/public/widget/history`). L'autorizzazione dominio viene gestita da Zentor alla creazione del widget; non esiste un'interfaccia di impostazione nel dashboard Tenant. In caso di Origin non autorizzata può comparire il codice errore `WIDGET_ORIGIN_DENIED`. La creazione del widget è riservata al Master Admin, mentre il Tenant riceve il codice di incorporamento finito.
Non esiste un sistema Developer API Key generale. `health` e `config` sono raggiungibili senza autenticazione perché servono all'inizializzazione del widget nel browser. `message` e `history` richiedono invece l'header `X-Widget-Token` e vengono inoltre verificati contro una Origin Allowlist lato server. L'Embed Token viene mostrato in chiaro una sola volta alla creazione del widget e non deve comparire in repository pubblici, screenshot supporto o log browser.
Ogni pagina di dettaglio di questo gruppo descrive separatamente metodo, percorso, autenticazione, idempotenza e codici errore documentati del rispettivo endpoint. Una chiamata riuscita a un endpoint non dimostra automaticamente che anche un altro endpoint dello stesso gruppo funzionerà — in particolare un `health` verde non conferma né un widget valido, né una Origin autorizzata, né la raggiungibilità di un provider IA.
Il limite API confermato a livello piattaforma è 2.000 richieste in 15 minuti. Un limite diverso per un singolo endpoint Widget viene indicato solo se esplicitamente dimostrato per quell'endpoint. `message` non è idempotente; un client non deve ritentare automaticamente un invio interrotto in modo ambiguo senza prima verificare se il primo messaggio sia già stato elaborato.
La verifica tecnica di questo gruppo si basa sulla Registry in `app/frontend/src/content/api-reference/groups/widget.ts` e sulle relative route Backend. Ogni pagina di dettaglio indica se è stato verificato live un percorso di successo, un percorso negativo oppure soltanto un'analogia di codice — questa distinzione vale per l'intero gruppo e non deve essere sostituita da affermazioni generiche di successo.