# TrueScreen Public API Documentazione della Public API TrueScreen per integrazioni esterne. Qui trovi le definizioni delle entità principali e le guide d'uso. ## Autenticazione L'autenticazione avviene tramite **API key**. Ogni richiesta agli endpoint della Public API deve includere la propria API key nell'header **`Authorization: Bearer `** 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](/it/mcp-integration). ## Definizioni ### True Flow 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. ### Flow Template 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. ### Flow Data Un oggetto che descrive tramite [JSON Schema](https://json-schema.org/) 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 ### Sign Data Un array di oggetti che descrive tramite [JSON Schema](https://json-schema.org/) 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 ### Certificazione 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](https://www.standardwebhooks.com)**: 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. ## Guide ### True Flow - [Flusso di chiamate True Flow](/it/true-flow-workflow) — Creazione semplice, con dati prepopolati, allegati e firmatari. ### Certificazione - [Certificazione — Panoramica](/it/certification-overview) — Concetti, modalità (hash vs file), artefatti prodotti, processo asincrono, crediti e metadati. - [Flusso di chiamate Certificazione](/it/certification-workflow) — Guida operativa con sequenze di chiamate API per hash e certificazione file. ### MCP - [Integrazione MCP](/it/mcp-integration) — Scegli tra server MCP remoto e locale e installa la configurazione corretta per il tuo client. ### Riferimenti generali - [Errori API](/it/errors) — 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](/it/openapi) e la documentazione interattiva. Versione 1.7