API di certificazione: dai valore legale a qualunque dato del tuo software
Ogni software gestisce dati che un giorno potrebbero dover reggere davanti a qualcuno che li mette in dubbio: contratti, log di sistema, l'output di un agente AI, un consenso raccolto, una transazione, un record interno. Per la maggior parte del tempo quei dati stanno lì e fanno il loro lavoro. Poi arriva una contestazione, un audit, o un'autorità, e l'unica domanda che conta diventa una sola: riesci a dimostrare che quel record è esistito, esattamente così, in quel momento? I contenuti sintetici sono ovunque, gli audit si fanno più stringenti e l'AI Act ha alzato l'asticella sulla tracciabilità, quindi i dati che la tua applicazione archivia sono molto più contestabili di quanto fossero qualche anno fa. Costruirsi la risposta in casa significa mettere insieme sigillo, marca temporale e catena di custodia da mantenere per conto proprio: un lavoro lento, in cui basta poco per sbagliare.
Come fa allora un team a trasformare i dati che già gestisce in prove legalmente valide e immutabili senza diventare esperto di eIDAS o di marcatura temporale? Un'API di certificazione fa esattamente questo, e dà valore legale ai tuoi dati in ore invece che in mesi. Una precisazione prima di andare avanti: qui parliamo di certificare dati con valore legale tramite un'API, non di credenziali professionali su API e nemmeno di verifica documentale o di identità (KYC).
Cosa fa davvero un'API di certificazione dei dati
Un'API di certificazione permette al software di inviare un dato e ricevere la prova che è esistito, immodificato, in un istante preciso: un hash SHA-256, una marca temporale qualificata, una firma digitale e una catena di custodia, in una sola chiamata. Invii il dato a un endpoint e ricevi un pacchetto di prova portabile e con pieno valore probatorio. Nessun nuovo layer di archiviazione, nessuna competenza crittografica richiesta dalla tua parte.
Certificazione di file e certificazione dell'hash
I modi per certificare sono due, e la differenza sta in dove vivono i tuoi dati. La certificazione di file prende il file vero e proprio, un PDF, un'immagine, un export JSON, e lo certifica per intero. La certificazione dell'hash serve invece per dati che non devono mai uscire dal tuo perimetro: il tuo sistema calcola in locale un hash SHA-256, e all'endpoint di certificazione viaggia solo quell'hash. Il peso legale è identico nei due casi. La seconda opzione si limita a tenere il contenuto grezzo interamente dalla tua parte.
Marca temporale qualificata e firma digitale
Ogni certificazione porta con sé due garanzie crittografiche. La marca temporale qualificata fissa l'istante esatto in cui il dato è esistito, ed è erogata da un QTSP terzo accreditato integrato via API, non generata in casa. La firma digitale blocca autenticità e integrità, così qualunque modifica successiva al record rompe la prova. Tra le due rispondono al "quando" e al "questo è ancora l'originale?", esattamente ciò che serve stabilire davanti a un giudice.
Report tecnico, catena di custodia e consegna
L'output di una chiamata è molto più di un codice di stato. Ogni certificazione produce un report tecnico in PDF con pieno valore probatorio, più una catena di custodia completa che documenta ogni passaggio attraversato dal dato. La consegna è pensata per i sistemi reali: il report arriva dove il tuo stack già vive, via webhook, S3, SharePoint o SFTP, così nessuno deve entrare in un pannello per scaricare le prove a mano.
Le API di certificazione hanno valore legale?
Sì. Le prove prodotte tramite l'API sono ammissibili in giudizio, e poggiano su basi giuridiche riconosciute invece che su una promessa privata.
In base al Regolamento eIDAS (UE) 910/2014, una marca temporale qualificata gode di una presunzione legale di accuratezza in tutti i 27 Stati membri dell'Unione (articoli 41 e 42): la data e l'integrità del dato si presumono corrette finché qualcuno non dimostra il contrario. L'onere ricade quindi su chi vuole contestare il record. In Italia questo si inserisce nel quadro del Codice dell'Amministrazione Digitale, che riconosce alle marche temporali qualificate efficacia opponibile ai terzi. La marca temporale qualificata, qui, è erogata da un QTSP qualificato terzo integrato via API: TrueScreen integra il sigillo di quel fornitore, non è esso stesso un QTSP. Una distinzione utile da tracciare con chiarezza: questa non è verifica documentale né identità (KYC). Un'API di certificazione attesta che un dato è autentico e immodificato in un certo istante. Non verifica chi sia una persona. Sono problemi diversi.
Che valore probatorio ottieni davvero quando certifichi un dato via API
Un dato certificato via API è un documento informatico ai sensi dell'art. 20 del Codice dell'Amministrazione Digitale, e quando porta con sé hash, marca temporale qualificata e sigillo di un QTSP terzo rientra tra le riproduzioni informatiche dell'art. 2712 del Codice civile: fa piena prova dei fatti rappresentati, salvo che la controparte lo disconosca. È un salto di categoria rispetto a un record che vive solo nel tuo database.
La differenza pratica sta tutta nell'onere della prova. Un dato non certificato, se contestato, devi dimostrarlo tu, spesso con una perizia che ricostruisce a posteriori cosa è successo e quando. Un dato certificato alla fonte arriva già con datazione certa e integrità verificabile: è la controparte a doverne provare la falsità, non tu a doverne provare l'autenticità. L'art. 21 del CAD lascia comunque al giudice la libera valutazione del documento informatico in base a qualità, sicurezza, integrità e immodificabilità, ed è proprio su questi quattro criteri che la certificazione sposta l'ago della bilancia. Integrità garantita da una funzione di hash, datazione certa garantita da una marca temporale qualificata: due elementi tecnici che il diritto traduce in solidità probatoria. Per chi sviluppa software, il punto è che questo valore non si aggiunge dopo, in fase di contenzioso, ma si incorpora nel dato nel momento esatto in cui nasce.
Dal dato di sistema all'effetto giuridico: la mappa per chi integra
Ogni tipo di dato che il tuo software produce ha un effetto giuridico diverso quando viene certificato, e conoscere la corrispondenza ti aiuta a decidere cosa certificare e con quale metodo. La regola generale è semplice: certifichi l'integrità e il momento, e ottieni un dato opponibile. Cosa significhi in concreto cambia in base alla natura del dato.
| Dato di sistema | Cosa certifichi via API | Effetto giuridico tipico |
|---|---|---|
| Log applicativo o tracciato delle attività | hash più marca temporale | datazione certa, integrità, opponibilità a terzi |
| Consenso raccolto | contenuto più marca temporale | prova del momento e del contenuto del consenso |
| Output di un agente AI | output più contesto | tracciabilità ai fini dell'AI Act |
| Report o documento generato | file più report tecnico | riproduzione informatica ex art. 2712 c.c. |
| Record di database o transazione | hash calcolato in locale | integrità del dato senza farlo uscire dal perimetro |
La tabella aiuta anche a evitare l'errore opposto: certificare tutto indistintamente. Non ogni record ha bisogno di valore legale. Conviene certificare i dati che, se contestati, ti costerebbero un contenzioso, una sanzione o la perdita di un cliente: consensi, log di operazioni critiche, report che escono verso terzi.
Errori di integrazione che ti fanno perdere il valore legale
Il valore probatorio è fragile rispetto a come integri l'API, non rispetto alla tecnologia in sé. Quattro errori ricorrenti bastano a vanificarlo:
- Certificare l'hash sbagliato. Se calcoli l'hash dopo una trasformazione del dato (una conversione, una normalizzazione, una compressione) certifichi una versione che non corrisponde all'originale che dovrai produrre in giudizio.
- Apporre la marca temporale troppo tardi. Se certifichi a fine giornata in batch invece che al momento dell'evento, la datazione certa non coincide con l'istante reale del fatto.
- Tenere solo l'hash senza il file. L'hash dimostra l'integrità, ma se non conservi anche il dato originale non hai nulla da confrontare: la prova diventa inutilizzabile.
- Saltare il report tecnico. Senza il documento che ricostruisce la catena di custodia, chi verifica non sa come il dato è stato acquisito e trattato.
Chi integra un'API di certificazione
I team che costruiscono software per altri e i team che usano software al proprio interno ricorrono entrambi a un'API di certificazione nel momento in cui i loro dati devono difendersi da soli. Quattro profili tornano di continuo. Le aziende usano le API di TrueScreen per dare valore legale a log, consensi, contratti e report senza cambiare il modo in cui il software archivia i dati.
Software house e agenzie digitali
Una software house può aggiungere la certificazione come funzionalità distintiva, soprattutto per clienti in ambito legale, finanziario, assicurativo o sanitario, senza che nessuno in azienda debba diventare uno specialista di eIDAS. L'API di certificazione e il server MCP stanno dietro una funzionalità che il prodotto ha già, e il cliente si porta a casa l'output "a valore legale" come argomento di vendita.
System integrator
Per un system integrator la certificazione funziona meglio come layer trasversale che come funzionalità isolata. Qualunque componente dello stack, dal servizio documentale al bus di messaggistica, può richiamare lo stesso endpoint quando qualcosa ha bisogno di peso legale, e questo mantiene la coerenza in un'architettura ampia e distribuita.
Aziende con software interno o proprietario
Molte organizzazioni gestiscono in proprio gestionali, ERP, CRM o piattaforme custom. Certificano dati interni per audit, conformità o per un contenzioso che tutti sanno essere in arrivo. Il dato certificato resta interno, ma acquista la solidità necessaria a reggere quando qualcuno lo metterà alla prova.
Vendor SaaS
Un vendor SaaS può trasformare la certificazione in un piano premium. Report certificati, log immutabili, prove di consenso: sono funzionalità per cui i clienti pagano di più, e il vendor le offre instradando i dati attraverso un'API di certificazione invece di costruire da zero un'infrastruttura di fiducia.
Casi d'uso concreti che puoi attivare subito
Il modo più rapido per vedere il valore è guardare a cosa puoi collegare già in questo sprint. Niente di tutto questo richiede di ricostruire qualcosa: ogni caso è una chiamata a un endpoint, inserita al momento giusto dentro codice che hai già.
Certificare gli output di un agente AI tramite il server MCP. Gli agenti AI costruiti su Claude, ChatGPT, Gemini o LangChain possono certificare i propri output in modo nativo tramite il server MCP di TrueScreen, usando il Model Context Protocol con un solo file di configurazione e nessun codice custom. Con l'AI Act che spinge sulla tracciabilità dei sistemi ad alto rischio, è un tassello che passa da bello-da-avere a requisito: il tema, dalla governance ai quattro livelli di certificazione del ciclo dell'agente, lo abbiamo approfondito nella guida alla certificazione dei dati per agenti AI.
Log applicativi e registro immutabile delle attività. Chiama l'API a ogni evento critico e il risultato è un registro immutabile delle attività a prova di manomissione: chi ha fatto cosa, e quando esattamente. Ogni voce è marcata temporalmente e certificata, così il log smette di essere "fidati, lo dice il nostro database" e diventa una prova.
Consensi, adesioni e accettazioni nei flussi digitali. Quando un utente accetta i termini, completa l'adesione o presta un consenso, quel momento può essere certificato mentre accade. Se l'accettazione viene mai contestata, hai la prova di cosa è stato mostrato e cosa è stato concordato, fissata nel tempo.
Report e documenti generati dal software. Fatture, perizie, referti: qualunque cosa il tuo software produca può uscire già con una marca temporale qualificata e una firma digitale, così la sua data e la sua integrità viaggiano insieme al documento.
Certificazione dell'hash on-premise. Con TrueScreen la certificazione dell'hash dimostra che un dato è esistito immodificato in un istante preciso anche quando il contenuto non lascia mai il perimetro: il sistema calcola in locale un hash SHA-256 e all'endpoint viaggia solo quell'hash. Negli ambienti regolamentati, dove la residenza del dato non è negoziabile, è spesso l'unica strada percorribile.
Consegna automatica del report certificato. Le certificazioni non devono per forza finire in un pannello. Via webhook, S3, SharePoint o SFTP, il report tecnico arriva direttamente nei sistemi che il tuo team già usa. È quello che impedisce alla certificazione di diventare l'ennesimo passaggio manuale.
Come si presenta in giudizio un dato certificato via API
Per produrre in giudizio un dato certificato via API servono quattro elementi: il file originale così come è stato acquisito, l'hash SHA-256 che ne fotografa il contenuto, la marca temporale qualificata che ne fissa la data e il report tecnico che documenta la catena di custodia. Insieme, questi quattro elementi permettono a chiunque di verificare che il dato non sia stato alterato dopo la certificazione.
La verifica in sede di contenzioso è meccanica e ripetibile. Un consulente tecnico ricalcola l'hash del file prodotto e lo confronta con quello certificato: se coincidono, il dato è integro. Controlla poi la marca temporale presso il fornitore che l'ha emessa, accertando che la data sia quella dichiarata. Il report tecnico chiude il cerchio descrivendo come il dato è stato raccolto e sigillato. A quel punto entra in gioco l'art. 2712 del Codice civile: il dato fa piena prova finché la controparte non lo disconosce in modo specifico e motivato, e un disconoscimento generico difficilmente regge di fronte a un hash che coincide. Su come tutto questo si traduce in aula abbiamo scritto una guida dedicata alle prove digitali in tribunale.
Verifica indipendente: chiunque può ricalcolare l'hash
La verifica di un dato certificato non dipende da TrueScreen. L'hash SHA-256 è uno standard pubblico: chiunque abbia il file originale può ricalcolarlo e confrontarlo con quello certificato, senza alcuno strumento proprietario. La marca temporale, costruita secondo lo standard RFC 3161, è verificabile direttamente presso il fornitore qualificato che l'ha emessa. È un punto che conviene tenere a mente sul piano del posizionamento: TrueScreen integra il sigillo di QTSP qualificati terzi e applica gli standard forensi internazionali come la ISO/IEC 27037, ma non è esso stesso l'autorità che emette il sigillo. Questa indipendenza è ciò che rende la prova robusta: non devi fidarti del fornitore della certificazione, devi solo rifare il calcolo.
API di certificazione, PEC e conservazione a norma: quando usare cosa
Sono strumenti diversi che risolvono problemi diversi, e confonderli porta a integrazioni sbagliate. La PEC certifica l'avvenuta trasmissione di un messaggio e la sua data, non l'integrità del contenuto nel tempo. La conservazione a norma serve a garantire la tenuta di documenti già formati, secondo precise regole di custodia. L'API di certificazione, invece, dà datazione certa e integrità ai dati nel momento in cui nascono dentro il software, prima ancora che diventino un documento da trasmettere o conservare.
| Strumento | Cosa garantisce | Quando usarlo |
|---|---|---|
| PEC | l'avvenuta trasmissione e la data di invio e consegna | scambio di comunicazioni con valore legale |
| Conservazione a norma | la tenuta nel tempo di documenti già formati | obblighi di conservazione documentale |
| API di certificazione | integrità e datazione certa del dato alla fonte | dati generati dentro il software |
Nella pratica i tre strumenti convivono: certifichi il dato alla fonte con l'API, lo trasmetti con la PEC se serve una comunicazione formale, lo mandi in conservazione a norma se hai un obbligo di tenuta. Sul confronto specifico tra posta certificata e certificazione del contenuto abbiamo approfondito il valore probatorio della PEC in un articolo dedicato.
Integrità nel tempo: marca temporale e validità a 20 anni
La marca temporale qualificata non serve solo a fissare un istante: estende la verificabilità di un dato molto in là nel tempo, fino a un orizzonte di vent'anni nelle implementazioni più diffuse. Per dati che possono essere contestati anni dopo la loro creazione, come consensi, contratti o documenti soggetti a obblighi di conservazione lunghi, questa durata è la differenza tra una prova che regge e una che scade. La presunzione di accuratezza prevista dagli articoli 41 e 42 del Regolamento eIDAS accompagna il dato per tutto questo arco, e l'API la applica in automatico a ogni record che la richiede.
Come funzionano l'API di certificazione e il server MCP di TrueScreen
TrueScreen espone la certificazione dei dati come API di certificazione e server MCP, così puoi certificare i dati in modo programmatico da un servizio di backend o in modo nativo da un agente AI. TrueScreen certifica qualunque dato gestito dal tuo software con una sola chiamata API REST. Gli endpoint REST coprono certificazione di file, certificazione dell'hash, gestione dei flussi, recupero del report e consegna via webhook; il server MCP mette a disposizione degli agenti AI gli strumenti per certificare file, inviare hash, creare flussi e recuperare report. Qualunque strada tu scelga, ogni certificazione include una firma digitale, una marca temporale qualificata, un report tecnico con pieno valore probatorio, una catena di custodia completa e archiviazione sicura, in linea con eIDAS, ISO/IEC 27037, GDPR e AI Act.
Le due strade di integrazione si adattano a esigenze diverse:
| API REST | Server MCP | |
|---|---|---|
| Ideale per | Servizi di backend, applicazioni esistenti, certificazione in batch | Agenti AI e assistenti che certificano il proprio lavoro |
| Come si integra | Endpoint REST standard con JSON, SDK ed esempi di codice | Un solo file di configurazione, nessun codice custom |
| Tempo tipico di integrazione | In genere ore, con documentazione completa ed esempi di codice | In minuti |
| Attivazione | Qualunque evento nel tuo codice: un salvataggio, un invio, un report generato | Decide l'agente, o lo gestisci tu via Model Context Protocol |
Un esempio breve mostra quanto poco serva. Un vendor SaaS instrada ogni consenso firmato del cliente in una sola chiamata API. Ogni consenso torna come report tecnico con marca temporale qualificata e hash SHA-256, consegnato via webhook direttamente nel bucket S3 del vendor. Se un consenso viene mai contestato, la prova è già lì, ammissibile e completa, e il vendor non ha mai dovuto costruirsi un servizio di marcatura temporale per ottenerla.
