Superficie server, domini esposti e integrazioni
API e endpoint
Xedul espone una superficie di endpoint server organizzata per dominio, sotto /api. Questa pagina ne descrive l'impianto; non è un riferimento esaustivo campo per campo.
Principi
- Un dominio, un gruppo di endpoint. La struttura delle route rispecchia quella dei domini applicativi.
- Logica nei controller. I gestori di route restano sottili; la logica di business vive in controller dedicati.
- Autenticazione sempre. Ogni endpoint di lavoro richiede una sessione valida; l'organizzazione dell'utente determina l'ambito dei dati.
- Tipizzazione end-to-end. Le risposte sono tipizzate dal database fino al client.
Domini esposti
| Gruppo | Ambito |
|---|---|
| `auth` | Sessione, accesso, recupero password |
| `organization` | Dati e impostazioni dello studio |
| `users` | Gestione utenti dell'organizzazione |
| `invite-user` | Invito di nuove persone |
| `employees` | Anagrafica delle persone dello studio |
| `customers` | Clienti |
| `contacts` | Contatti e lead |
| `projects` / `deals` | Pratiche e relativa pipeline |
| `tasks` | Attività |
| `statuses` | Stati configurabili |
| `documents` | Documenti e allegati |
| `comments` | Commenti sulle entità di lavoro |
| `mentions` | Menzioni delle persone nei commenti |
| `notifications` | Notifiche |
| `reminders` | Promemoria e ricorrenze |
| `reference-data` | Settori, fonti dei lead, dimensioni |
| `health` | Stato del servizio |
Endpoint delle integrazioni email
Le integrazioni hanno un proprio gruppo di endpoint, perché il loro modello di autenticazione è distinto da quello dell'applicazione web.
Gmail
| Endpoint | Ruolo |
|---|---|
| `gmail/auth/login` | Accesso a Xedul da estensione o componente aggiuntivo |
| `gmail/auth/refresh` | Rinnovo silenzioso della sessione dell'integrazione |
| `gmail/draft` | Salvataggio e lettura della bozza temporanea |
| `gmail/draft/import` | Importazione differita degli allegati |
L'endpoint di lettura della bozza non restituisce il blocco di autorizzazione usato per accedere agli allegati: quel dato è di sola competenza del server.
Outlook
Il gruppo outlook gestisce l'autenticazione dal riquadro attività e il ciclo di vita della bozza generata dal componente aggiuntivo.
Il ciclo di vita di una bozza
Le due integrazioni condividono lo stesso schema:
- Il client di posta raccoglie i dati del messaggio.
- Li invia a Xedul come bozza temporanea, evitando di trasportare tutto nell'URL.
- Xedul apre la pagina attività con il riferimento alla bozza.
- Il browser richiede l'importazione degli allegati, se prevista.
- Il modulo si presenta precompilato; l'utente conferma.
- L'attività viene creata.
La bozza è deliberatamente temporanea: non è un'attività, non compare nelle liste e non genera notifiche. Diventa lavoro reale solo alla conferma dell'utente.
Tempo reale
Oltre agli endpoint, il client si sottoscrive alle modifiche tramite Supabase Realtime. Le due strade sono complementari: le API servono le operazioni esplicite, le sottoscrizioni mantengono allineate le viste aperte.
Note per chi integra
- L'ambito dei dati non si passa come parametro: deriva dalla sessione. Non esiste un modo di richiedere dati di un'altra organizzazione.
- Le sessioni delle integrazioni email sono separate da quelle dell'applicazione web: autenticarsi in una non autentica nell'altra.
- I tipi di file caricabili sono soggetti a un elenco di formati ammessi, che si applica anche alle importazioni automatiche.
Questa pagina descrive l'impianto, non un contratto pubblico stabile. Per un'integrazione di terze parti conviene concordare gli endpoint e le relative garanzie prima di costruirci sopra.