TrueScreen Public API

Documentazione della Public API TrueScreen per integrazioni esterne. Qui trovi le definizioni delle entità principali e le guide d'uso.

L'autenticazione avviene tramite API key. Ogni richiesta agli endpoint della Public API deve includere la propria API key nell'header Authorization: Bearer <api_key>

La API key si ottiene dal portale (TBD) TrueScreen ed è associata a un workspace. Richieste senza API key valida ricevono risposta 401 Unauthorized. La API key determina il workspace (e quindi i flow template e le risorse) accessibili.

La stessa API key può essere usata anche per configurare i server MCP di TrueScreen. Vedi Integrazione MCP.

Un True Flow è un'istanza di flusso di raccolta dati. Serve a generare form di inserimento e raccolta dati che l'utente finale compila tramite l'interfaccia web o mobile di TrueScreen. L'interfaccia è raggiungibile tramite un link univoco (trueLink). I dati vengono poi processati dall'app TrueScreen e alla fine è possibile ottenere una certificazione.

• Viene creato con POST /true-flows a partire da un Flow Template (identificato dal template_token).
• Può includere dati prepopolati (flow_data), firmatari (sign_data) e allegati (token da POST /true-flows-attachments).
• La risposta contiene il trueLink (deeplink) da inviare all'utente per compilare il form.

Un Flow Template è il modello che definisce come i dati vengono raccolti. Descrive la struttura del form che l'utente finale vedrà nell'app TrueScreen (step, campi, tipi di input, allegati, firma, ecc.).

• È creato e gestito da TrueScreen.
• È identificato da un template_token univoco e stabile nel tempo (anche se il template evolve).
• I Flow Template disponibili per la tua API key formano un catalogo: puoi ottenerne l'elenco e lo schema dei campi con GET /templates.
• Per creare un True Flow usi il template_token nel body di POST /true-flows, senza dover richiamare GET /templates a ogni creazione.

Un oggetto che descrive tramite JSON Schema i campi del True Flow che possono prepopolati. Questi campi saranno inclusi nel report e nel file jsonData della certificazione. Potranno essere visibili e modificabili dall'utente che certifica in base alle configurazioni:

• se il campo ha l'attributo readOnly a true non potrà essere modificato
• se il campo ha l'attributo format a hidden non sarà visibile dall'utente

Un array di oggetti che descrive tramite JSON Schema i campi del True Flow che indicano i firmatari della pratica. A seconda della configurazione del True Flow, questi campi possono essere utilizzati per inviare la mail di richiesta firma. Potranno essere visibili e modificabili dall'utente che certifica in base alle configurazioni:

• se il campo ha l'attributo readOnly a true non potrà essere modificato
• se il campo ha l'attributo format a hidden non sarà visibile dall'utente

Una certificazione è il processo con cui uno o più file digitali vengono certificati crittograficamente per attestarne esistenza, integrità e provenienza a un determinato momento. Il risultato è un insieme di artefatti firmati digitalmente (jsonData, report PDF opzionale, XML firmato con marca temporale). La Public API offre tre modalità:

• Certificazione dati (POST /v1/data-certifications) — il client invia dati chiave-valore in formato stringa nel campo obbligatorio data. Nessun file né hash. Costo: 1 credito per certificazione.
• Certificazione hash (POST /v1/hash-certifications) — il client invia nomi file e hash SHA-256. Nessun upload di file. Costo: 1 credito per hash inviato.
• Certificazione file (POST /v1/file-certifications-attachments + upload + POST /v1/file-certifications) — il client carica i file originali. Costo: 1 credito per file.

La generazione è asincrona: puoi ricevere il risultato tramite webhook o consultando GET /v1/certifications/{reportId}. Se l’elaborazione fallisce dopo la creazione, attenditi uno stato HTTP di errore e application/problem+json; le callback webhook seguono la specifica Standard Webhooks: il payload usa un envelope standard (type, timestamp, data) e ogni callback è firmata con header HMAC-SHA256 (webhook-id, webhook-timestamp, webhook-signature) per la verifica di autenticità. Per i dettagli, vedi le guide sotto.

• Flusso di chiamate True Flow — Creazione semplice, con dati prepopolati, allegati e firmatari.

• Certificazione — Panoramica — Concetti, modalità (hash vs file), artefatti prodotti, processo asincrono, crediti e metadati.
• Flusso di chiamate Certificazione — Guida operativa con sequenze di chiamate API per hash e certificazione file.

• Integrazione MCP — Scegli tra server MCP remoto e locale e installa la configurazione corretta per il tuo client.

• Errori API — Formato RFC 9457, elenco codici e pagine di dettaglio per ogni tipo di errore.

Per il riferimento degli endpoint e degli schemi, usa la specifica OpenAPI e la documentazione interattiva.

Versione 1.7