Concetti

Quattro parole. Chi le confonde non riceve un errore: riceve i dati sbagliati, che e' peggio. Vale la pena leggere questa pagina una volta.

Cliente

E' l'azienda che ha comprato il sistema — l'organizzazione intera. Ogni cliente ha i propri dati, tenuti separati da quelli di tutti gli altri: non esiste una chiamata che possa attraversare il confine fra due clienti.

Non devi indicarlo. Il cliente e' deciso dalle credenziali con cui fai il login e viaggia dentro il token. Non c'e' un parametro per sceglierlo, ed e' voluto: se ci fosse, un errore di battitura ti farebbe leggere i dati di qualcun altro.

Azienda

Dentro un cliente ci possono essere piu' aziende — tipicamente le ragioni sociali che convivono nello stesso gestionale (per esempio DEMO). Questa la scegli tu, al login, col campo company.

Per lavorare su due aziende servono due token, uno per azienda. Non si cambia azienda a meta' sessione.

Token

E' il lasciapassare: lo ottieni da POST /api/auth/login e lo rimandi a ogni chiamata nell'intestazione Authorization: Bearer <token>. Dentro ci sono gia' l'utente, il cliente e l'azienda, percio' le chiamate restano pulite.

Ha una scadenza. Quando e' scaduto le chiamate rispondono 401: si rinnova con POST /api/auth/refresh, senza rifare il login.

Licenza

Non tutti i clienti hanno comprato tutto. Le funzioni disponibili dipendono dai prodotti che quel cliente ha in licenza, e la licenza viene verificata dal sistema, non dichiarata da chi chiama.

In pratica: una rotta puo' esistere nel riferimento ed essere comunque chiusa per quel cliente. Non e' un guasto ed e' inutile ritentare — si risolve con un contratto, non con il codice. Quali prodotti sono attivi lo dice GET /api/moduli.

Permessi

Oltre alla licenza c'e' l'utente: ogni utente ha i propri permessi, ereditati dai gruppi a cui appartiene nel gestionale. Due utenti dello stesso cliente, sulla stessa azienda, possono ricevere risposte diverse dalla stessa rotta.

Per questo conviene un utente dedicato all'integrazione, con esattamente i permessi che servono: e' l'unico modo per sapere con certezza cosa il tuo programma puo' fare.

In breve