Consentire ad altri software di leggere i tuoi dati

API Studio: pubblicazione di una schermata alla volta, emissione di una chiave, associazione a un indirizzo e la stessa pubblicazione come server MCP per un agente di intelligenza artificiale.

Prima o poi, qualcosa al di fuori di TRANXACT richiederà i tuoi dati: uno strumento di reporting, il sistema di un partner, un sito web che necessita del listino prezzi, un agente di intelligenza artificiale a cui è stata posta una domanda sulla tua attività. L'API Studio, nella sezione Piattaforma, è il luogo in cui decidi cosa è consentito condividere, una schermata alla volta, una colonna alla volta.

Nulla è accessibile dall'esterno finché qualcuno non lo pubblica. Non esiste un'impostazione che apra tutto né una chiave che permetta di accedere a tutto. Una nuova implementazione non ha alcuna interfaccia API, ed è proprio questo il punto di partenza ideale, piuttosto che qualcosa da attivare in un secondo momento.

Le quattro decisioni, in ordine

Che cosa	Cosa decide	Chi lo fa di solito?
Un'esposizione	Quello schermo potrebbe addirittura lasciare l'azienda: quali colonne, quali righe, e se sarà possibile scriverci qualcosa.	Chiunque possieda i dati
Un cliente	Quel software esiste, come si chiama, chi contattare per informazioni e quale utente rappresenta.	Chiunque gestisca l’integrazione
Una sovvenzione	Affinché questo cliente possa raggiungere tale visibilità, con questi verbi.	Chiunque gestisca l’integrazione
Un indirizzo consentito	La chiave può essere presentata da diverse fonti: un browser, un host, un indirizzo server o una rete.	Chiunque gestisca l’integrazione

La piattaforma prevede tre ruoli per questo scopo, volutamente separati. Un API Publisher decide cosa può essere esportato ma non può rilasciare una chiave. Un API Registrar rilascia chiavi ma non può creare un'esposizione. Un API Reviewer legge tutto ma non apporta modifiche. Gestito da un'unica persona, la pubblicazione della tabella delle buste paga e l'emissione di una chiave per accedervi costituiscono un percorso di esportazione completo e non verificato, in cui ogni passaggio appare come una normale modifica amministrativa.

Pubblicare uno schermo

Apri Piattaforma → API Studio e scegli una schermata. L'elenco contiene tutte le schermate presenti nella console, lette direttamente dal prodotto; quindi, una schermata inclusa in questa versione sarà presente nell'elenco.
Seleziona le colonne che possono essere inviate. Nulla di ciò che non è selezionato viene mai inviato: né in un elenco, né in un singolo record, né in ciò che viene restituito da una scrittura. Nulla viene selezionato fin dall'inizio, deliberatamente.
Scegli i verbi. La lettura è attiva per impostazione predefinita; creare, modificare ed eliminare sono decisioni separate, perché consentire al loro sistema di leggere i dati anagrafici dell'articolo e consentirgli di eliminarli non sono la stessa cosa.
È possibile, facoltativamente, limitare le righe: solo le fatture registrate, solo per quest'anno. Si tratta dello stesso filtro utilizzato in ogni schermata di elenco, applicato sul server a ogni chiamata, e nulla di ciò che un chiamante può inviare può ampliarlo.
Salvalo. È una bozza, e una bozza non porta a nulla. Pubblicalo quando sarai davvero pronto.
Fai clic su Anteprima prima di fornire a chiunque una chiave. Mostra esattamente cosa riceverà il partner e quante colonne sono state nascoste.

Registrazione del software

Un client è un record di un software: come si chiama, di cosa si tratta, chi contattare per informazioni e, soprattutto, quale utente rappresenta. Ogni chiamata effettuata dalla chiave viene effettuata a nome di quell'utente. Qualsiasi cosa l'utente non possa fare, la chiave potrebbe non essere in grado di farla neanche.

Questo è il campo più importante in assoluto sullo schermo, ed è il motivo per cui un'esposizione può solo restringere l'accesso e mai ampliarlo. Puntate una chiave a un utente creato appositamente per quello scopo, che detiene il ruolo più specifico necessario per svolgere il lavoro, non a un vero amministratore solo perché è più comodo.

La chiave viene mostrata una sola volta, al momento del rilascio, e mai più. Il rilascio di una nuova chiave disattiva immediatamente la precedente. È possibile revocare una chiave senza eliminare il client, quindi il registro continua a indicare chi ha avuto accesso e quando è stato revocato.

Dove è possibile utilizzare una chiave da

Una chiave senza indirizzi consentiti non raggiunge nulla. Nessun indirizzo specificato viene letto come non ancora raggiungibile e mai come raggiungibile da nessuna parte, perché una chiave trapelata che funziona da qualsiasi laptop al mondo rappresenta l'intero rischio. Quattro tipi di voce: un'origine del browser, un host di riferimento, un singolo indirizzo o una rete in formato CIDR.

Un client può essere contrassegnato come utilizzabile da qualsiasi luogo, e a volte è corretto: un partner il cui indirizzo di uscita cambia effettivamente. Si tratta di un'impostazione intenzionale, accompagnata da un avviso, anziché essere l'impostazione predefinita.

Cosa inviare a chiunque stia integrando

Lo studio stampa i quattro indirizzi. La base è /api/v1, la chiave va nell'intestazione Authorization: Bearer, /api/v1/resources elenca a cosa può accedere questa chiave e /api/v1/openapi.json è l'equivalente di un documento OpenAPI 3.1.

Entrambi vengono generati dalla chiave che li richiede. A un partner non viene mai consegnato un documento che elenca quaranta endpoint che non può chiamare: il suo descrive esattamente ciò che può chiamare e nient'altro, e non può descrivere un percorso che verrebbe rifiutato, perché è costruito a partire dalle stesse righe che il gestore delle richieste controlla.

Gli stessi dati per un agente di intelligenza artificiale

L'indirizzo /api/v1/mcp è un server Model Context Protocol. A un agente che si connette ad esso viene offerto uno strumento per ogni azione consentita dalla chiave e nient'altro: nessuno strumento per dati non pubblicati, nessuno strumento per un verbo non concesso. Si tratta della stessa pubblicazione, descritta per un modello anziché per uno sviluppatore, in modo che i due non possano mai essere incoerenti.

Scrivi le istruzioni MCP sul client. È l'unico punto in cui a un modello viene indicato che questi strumenti accedono a un registro reale anziché a un ambiente di test, ed è l'unico punto in cui puoi specificare che per "ordini" si intendono gli ordini di acquisto e non gli ordini di vendita.

Cosa succede ad ogni chiamata?

Una chiamata pubblicata non è una scorciatoia per accedere al database. Viene autenticata, verificata rispetto all'esposizione e all'autorizzazione, e quindi eseguita come l'utente con cui si esegue la chiamata tramite l'API della piattaforma, lo stesso percorso utilizzato dalla console. Ambito aziendale, ambito di unità aziendale, restrizioni di luogo, periodi di chiusura, regole di pubblicazione, campi personalizzati, logica personalizzata, modificabilità e registro delle attività sono tutti applicabili, perché si tratta dello stesso codice in esecuzione.

Ogni chiamata viene registrata, autorizzata o rifiutata, con la relativa motivazione. Il registro si trova in Piattaforma → API Studio → Registro chiamate API, e la riga più interessante che produce riguarda una chiave presentata da un indirizzo non autorizzato.

Quando non funziona

Ciò che vede il partner	Cosa significa
La chiave API non è riconosciuta	Chiave errata oppure ne è stata emessa una nuova in seguito.
Questa chiave API non ha indirizzi consentiti	Nessuno ha ancora detto dove potrebbe essere utilizzato.
Non è consentito utilizzare questa chiave API da qui	Indica l'origine e l'indirizzo effettivo di arrivo, solitamente perché il partner ha spostato i propri server.
Nulla viene pubblicato qui come X	Il nome è errato, oppure l'esposizione non è concessa per questa chiave, oppure si tratta ancora di una bozza.
Questa chiave potrebbe non creare X	L'esposizione o la sovvenzione non consentono quel verbo.
Non hai l'autorizzazione per visualizzare X	La concessione del permesso va bene, ma l'utente con cui si esegue l'operazione non va bene. Lo studio elenca questi dettagli prima che un partner debba trovarli.

L'elenco dei client mostra una colonna di disponibilità anziché solo uno stato, perché un client può essere attivo, possedere una chiave e non raggiungere comunque nulla: nessun utente con cui eseguire l'operazione, nessun indirizzo consentito, nessuna autorizzazione concessa. Leggere "attivo" mentre ogni chiamata viene rifiutata è così che trascorre un pomeriggio.