JSON API per applicazioni mobili ed esterne

Un’integrazione non deve dipendere dal markup di una pagina web

Una piattaforma aziendale smette di essere un sito isolato quando vi si collegano un’applicazione mobile, la postazione di un autista, un portale interno, un terminale o il servizio di un partner. Tentare di usare le pagine HTML crea presto una dipendenza fragile dal design. L’accesso diretto al database è ancora più pericoloso: il client esterno inizia a ripetere le regole aziendali, ignorare i controlli di accesso e dipendere dalla struttura interna di archiviazione.

Sapphire I.C.D.S. offre un ambiente di integrazione distinto per queste attività: una JSON API su HTTPS. Riceve richieste strutturate e restituisce risposte elaborabili dalle macchine, senza renderizzare pagine utente né richiedere al client di conoscere l’organizzazione del database server. Il Roadmap pubblico registra questo ambiente come base rilasciata per client nativi e integrazioni aziendali.

JSON è il formato di scambio, non l’intera architettura

JSON da solo non rende affidabile un’integrazione. Contano chi definisce il comando disponibile, come viene convalidato l’utente e dove si svolge la verifica aziendale. In Sapphire I.C.D.S., l’API di sistema gestisce l’autenticazione e i moduli pubblicano i comandi di dominio tramite un contratto separato. Il client indica un’azione e i dati, ma il server seleziona il modulo responsabile, verifica la richiesta e forma il risultato.

In questo modo, interfaccia web, applicazione mobile e sistema esterno possono utilizzare la stessa logica di dominio. Per esempio, la registrazione dell’esito di una consegna deve verificare nello stesso modo giro, negozio, merce e diritti dell’operatore, indipendentemente dalla schermata di origine. Il client offre un’interfaccia comoda; il modulo garantisce la correttezza del processo.

Il server verifica sessione e identità

L’API supporta il ciclo essenziale di una sessione client: accesso, ottenimento dell’utente corrente confermato, rinnovo dell’accesso e uscita. Dopo un accesso riuscito, il client riceve un token di accesso di breve durata e un token di rinnovo separato. Al rinnovo, la coppia viene sostituita; l’applicazione deve quindi salvarla atomicamente e non ripetere con il vecchio valore un’operazione già riuscita.

Il principio critico è che i campi utente, gruppo o oggetto presenti nel JSON non dimostrano alcun potere. Il server ricava l’identità dalla sessione convalidata e solo allora stabilisce l’ambito dei dati accessibili. Un modulo logistico, per esempio, non deve mostrare un altro giro perché il client ha inviato l’identificatore di un altro autista. Il collegamento con il ruolo aziendale viene risolto sul server.

I moduli pubblicano soltanto azioni esplicite

L’API dedicata non apre automaticamente tutte le funzioni di Sapphire I.C.D.S. Il modulo deve offrire un provider API ed elencare i comandi supportati. Le integrazioni possono così essere rilasciate per gradi: prima letture sicure, poi modifiche circoscritte e, dopo la verifica, processi più complessi. Un modulo privo di contratto esterno non diventa accessibile solo perché è installato.

I comandi che cambiano lo stato devono usare richieste previste per la modifica, mentre la lettura può rimanere un’operazione distinta. Il server restituisce codici chiari per richiesta errata, sessione scaduta, divieto, metodo non corretto o indisponibilità temporanea di una dipendenza. L’applicazione client riceve un ramo definito da gestire, non una pagina HTML di errore.

• Il client mobile invia solo i dati necessari e conserva i token nell’archivio protetto del dispositivo.
• L’ambiente API convalida la sessione, il metodo della richiesta e la dimensione consentita dell’input.
• Il modulo verifica regole di dominio, ambito dell’utente e transizione di stato ammessa.
• Il database rimane dietro il livello server e non viene mai pubblicato direttamente al client.

Scenari aziendali adatti

La JSON API è particolarmente utile quando il dipendente lavora fuori dal back-office principale. Nella logistica può offrire l’elenco dei giri assegnati, i dati di un punto e la registrazione di quantità consegnate, resi o stato dei documenti. Nella contabilità può fornire un catalogo e ricevere un’operazione confermata. In un’applicazione esterna consente di leggere uno stato autorizzato e avviare un comando preciso senza imitare le azioni del browser.

Il Roadmap pubblico indica logistica, contabilità e attività sul campo come naturali direzioni di sviluppo. Ciò non significa che esista già un endpoint universale per ogni scenario. La disponibilità dipende dai comandi API del modulo installato. Prima di un progetto di integrazione occorre preparare una matrice di operazioni, dati, ruoli e versioni.

La JSON API non è l’MCP esterno

Entrambi gli ambienti usano dati strutturati, ma servono classi di client differenti. La JSON API è destinata ad applicazioni mobili e aziendali con un processo utente progettato in anticipo. L’MCP esterno, che rimane in developer alpha ed è stato verificato solo con l’attuale integrazione ChatGPT su sapphire-project.com, è destinato a client AI compatibili che scoprono strumenti e li richiamano in una sessione agentica. I rispettivi diritti e le regole di pubblicazione non sono intercambiabili.

L’API non è nemmeno una console SQL remota, un generatore arbitrario di report o una promessa di accesso a tutte le tabelle. Fornisce comandi aziendali sotto la responsabilità di un modulo. Questo livello di astrazione resiste meglio ai cambiamenti dello schema dati ed è più sicuro per la manutenzione di lungo periodo.

Che cosa è richiesto all’applicazione client

Un client nativo deve gestire correttamente scadenza del token di accesso, sostituzione del token di rinnovo, uscita, assenza di rete e nuovi tentativi. Per le operazioni che modificano lo stato è particolarmente importante distinguere un rifiuto confermato da un risultato di trasporto incerto: senza un’idempotenza concordata non si può ripetere automaticamente un’azione forse già eseguita. La cache locale non deve essere considerata la fonte dei diritti correnti.

Il team tecnico definisce inoltre versionamento dei contratti, registrazione, limiti delle richieste e strategia di compatibilità. La piattaforma offre un ambiente modulare comune, ma la qualità di uno specifico prodotto mobile dipende dalla disciplina del client e dalla completezza del contratto aziendale pubblicato.

Percorso di adozione

Il lavoro dovrebbe iniziare dall’inventario degli scenari utente, non da un elenco di tabelle. Per ogni passaggio si definiscono campi in ingresso, risposta, ruolo, ambito dei dati, transizioni ammesse e comportamento in caso di ripetizione. Il modulo pubblica quindi l’insieme minimo di comandi, il team mobile costruisce l’interfaccia e i test congiunti verificano casi consentiti e vietati.

Per l’imprenditore, il risultato è la possibilità di sviluppare applicazioni proprie senza copiare la logica del server. Per la direzione tecnica, è un confine di integrazione governato con autenticazione comune e comandi modulari. La JSON API estende Sapphire I.C.D.S. oltre l’interfaccia web, ma mantiene dati, diritti e regole del processo nell’ambiente autorevole del server.