{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-@l10n/it/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"TrueScreen Public API","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"truescreen-public-api","__idx":0},"children":["TrueScreen Public API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Documentazione della Public API TrueScreen per integrazioni esterne. Qui trovi le definizioni delle entità principali e le guide d'uso."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"autenticazione","__idx":1},"children":["Autenticazione"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["L'autenticazione avviene tramite ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API key"]},". Ogni richiesta agli endpoint della Public API deve includere la propria API key nell'header ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer <api_key>"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["La API key si ottiene dal portale (TBD) TrueScreen ed è associata a un workspace. Richieste senza API key valida ricevono risposta ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["401 Unauthorized"]},". La API key determina il workspace (e quindi i flow template e le risorse) accessibili."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["La stessa API key può essere usata anche per configurare i server MCP di TrueScreen. Vedi ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/it/mcp-integration"},"children":["Integrazione MCP"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"definizioni","__idx":2},"children":["Definizioni"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"true-flow","__idx":3},"children":["True Flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Un ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["True Flow"]}," è un'istanza di flusso di raccolta dati. Serve a generare ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["certificazione"]},"."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Viene ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["creato"]}," con ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /true-flows"]}," a partire da un ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Flow Template"]}," (identificato dal ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["template_token"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Può includere dati prepopolati (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flow_data"]},"), firmatari (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sign_data"]},") e allegati (token da ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /true-flows-attachments"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["La risposta contiene il ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["trueLink"]}," (deeplink) da inviare all'utente per compilare il form."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"flow-template","__idx":4},"children":["Flow Template"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Un ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Flow Template"]}," è il ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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.)."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["È creato e gestito da TrueScreen."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["È identificato da un ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["template_token"]}," univoco e stabile nel tempo (anche se il template evolve)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["I Flow Template disponibili per la tua API key formano un ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["catalogo"]},": puoi ottenerne l'elenco e lo schema dei campi con ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["GET /templates"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Per creare un True Flow usi il ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["template_token"]}," nel body di ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["POST /true-flows"]},", senza dover richiamare GET /templates a ogni creazione."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"flow-data","__idx":5},"children":["Flow Data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Un oggetto che descrive tramite ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://json-schema.org/"},"children":["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:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["se il campo ha l'attributo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["readOnly"]}," a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," non potrà essere modificato"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["se il campo ha l'attributo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["format"]}," a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hidden"]}," non sarà visibile dall'utente"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"sign-data","__idx":6},"children":["Sign Data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Un array di oggetti che descrive tramite ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://json-schema.org/"},"children":["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:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["se il campo ha l'attributo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["readOnly"]}," a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," non potrà essere modificato"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["se il campo ha l'attributo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["format"]}," a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hidden"]}," non sarà visibile dall'utente"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"certificazione","__idx":7},"children":["Certificazione"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Una ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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à:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Certificazione dati"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/data-certifications"]},") — il client invia dati chiave-valore in formato stringa nel campo obbligatorio ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]},". Nessun file né hash. Costo: 1 credito per certificazione."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Certificazione hash"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/hash-certifications"]},") — il client invia nomi file e hash SHA-256. Nessun upload di file. Costo: 1 credito per hash inviato."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Certificazione file"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/file-certifications-attachments"]}," + upload + ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/file-certifications"]},") — il client carica i file originali. Costo: 1 credito per file."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["La generazione è ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["asincrona"]},": puoi ricevere il risultato tramite ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["webhook"]}," o consultando ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/certifications/{reportId}"]},". Se l’elaborazione ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["fallisce dopo la creazione"]},", attenditi uno stato HTTP di errore e ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/problem+json"]},"; le callback webhook seguono la specifica ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.standardwebhooks.com"},"children":["Standard Webhooks"]}]},": il payload usa un envelope standard (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timestamp"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]},") e ogni callback è firmata con header HMAC-SHA256 (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook-id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook-timestamp"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook-signature"]},") per la verifica di autenticità. Per i dettagli, vedi le guide sotto."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"guide","__idx":8},"children":["Guide"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"true-flow-1","__idx":9},"children":["True Flow"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/it/true-flow-workflow"},"children":["Flusso di chiamate True Flow"]}," — Creazione semplice, con dati prepopolati, allegati e firmatari."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"certificazione-1","__idx":10},"children":["Certificazione"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/it/certification-overview"},"children":["Certificazione — Panoramica"]}," — Concetti, modalità (hash vs file), artefatti prodotti, processo asincrono, crediti e metadati."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/it/certification-workflow"},"children":["Flusso di chiamate Certificazione"]}," — Guida operativa con sequenze di chiamate API per hash e certificazione file."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"mcp","__idx":11},"children":["MCP"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/it/mcp-integration"},"children":["Integrazione MCP"]}," — Scegli tra server MCP remoto e locale e installa la configurazione corretta per il tuo client."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"riferimenti-generali","__idx":12},"children":["Riferimenti generali"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/it/errors"},"children":["Errori API"]}," — Formato RFC 9457, elenco codici e pagine di dettaglio per ogni tipo di errore."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Per il riferimento degli endpoint e degli schemi, usa la ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/it/openapi"},"children":["specifica OpenAPI"]}," e la documentazione interattiva."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"small","attributes":{},"children":["Versione 1.7"]}]}]},"headings":[{"value":"TrueScreen Public API","id":"truescreen-public-api","depth":1},{"value":"Autenticazione","id":"autenticazione","depth":2},{"value":"Definizioni","id":"definizioni","depth":2},{"value":"True Flow","id":"true-flow","depth":3},{"value":"Flow Template","id":"flow-template","depth":3},{"value":"Flow Data","id":"flow-data","depth":3},{"value":"Sign Data","id":"sign-data","depth":3},{"value":"Certificazione","id":"certificazione","depth":3},{"value":"Guide","id":"guide","depth":2},{"value":"True Flow","id":"true-flow-1","depth":3},{"value":"Certificazione","id":"certificazione-1","depth":3},{"value":"MCP","id":"mcp","depth":3},{"value":"Riferimenti generali","id":"riferimenti-generali","depth":3}],"frontmatter":{"seo":{"title":"TrueScreen Public API"}},"lastModified":"2026-06-25T15:58:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/it","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}