# TrueScreen Public API

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

## 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  utilizzati per . 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


## Autenticazione

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.

**Esempio:** se la tua API key è `ts_live_abc123...`, l'header sarà:
`Authorization: Bearer ts_live_abc123...`

## Guide

- [Flusso di chiamate True Flow](/true-flow-workflow) — Creazione semplice, con dati prepopolati, allegati e firmatari.


Per il riferimento degli endpoint e degli schemi, usa la [specifica OpenAPI](/openapi) e la documentazione interattiva.