# Flusso di chiamate True Flow Questa guida descrive come creare un True Flow tramite la Public API. In sintesi hai **tre possibilità**: 1. **Creazione semplice** — Una sola chiamata a `POST /true-flows` con `template_token` e `name`. Il flusso parte con i valori di default del template; l'utente finale riceverà il link e compila il form dall'inizio alla fine. 2. **Creazione con dati precompilati e/o firmatari** — Sempre `POST /true-flows`, ma arricchito con `flow_data` (campi del form già valorizzati) e/o `sign_data` (elenco firmatari). Utile quando integri con i tuoi sistemi e vuoi precompilare dati anagrafici, riferimenti pratica o inviti alla firma. 3. **Creazione con allegati** — Il template prevede documenti da caricare. Prima ottieni un token e un URL di upload (`POST /true-flows-attachments`), carichi il file con una `PUT`, poi crei il True Flow con `POST /true-flows` passando i token degli allegati in `flow_data`. Le prime due operazioni vanno eseguite in sequenza per ogni file. Puoi anche **combinare** le opzioni: ad esempio dati prepopolati, firmatari e allegati nella stessa creazione (prima gli upload, poi una sola `POST /true-flows` con tutto). Le sezioni seguenti entrano nel dettaglio di ogni caso. ## Riferimento rapido | Scenario | Chiamate principali | | --- | --- | | [Semplice](#1-creazione-true-flow-semplice) | POST /true-flows | | [Con prepopolazione](#2-creazione-true-flow-con-dati-prepopolati) | POST /true-flows con `flow_data` | | [Con allegati](#3-creazione-true-flow-con-allegati) | POST /true-flows-attachments → PUT upload_url → POST /true-flows con token in `flow_data` | | [Con firmatari](#4-creazione-true-flow-con-firmatari) | POST /true-flows con `sign_data` | In tutti i casi le richieste devono includere l'[autenticazione](#autenticazione) con API key. Per il contesto sui token usati nelle chiamate, vedi [Flow template token](#flow-template-token); per combinare più opzioni in un'unica creazione, vedi [Combinazione di più opzioni](#combinazione-di-pi%C3%B9-opzioni). ## True Flow tramite MCP Le operazioni True Flow sono disponibili anche tramite MCP. - `truescreen_list_templates` e `truescreen_create_true_flow` sono disponibili sia sul server MCP **remoto** sia su quello **locale**. - L'upload di allegati per un True Flow è disponibile solo sul server MCP **locale** tramite `truescreen_create_true_flow_attachment`. Vedi [Integrazione MCP](/it/mcp-integration) per installazione e scelta del canale. ## Flow template token Il **flow template token** è l'identificativo del modello di flusso che vuoi istanziare. È creato e gestito da TrueScreen: non lo generi tu, ma lo **usi** nelle chiamate di creazione del True Flow. Il token è **univoco per quel tipo di flusso** e resta valido anche se il template evolve nel tempo: non è quindi necessario richiamare **GET /templates** a ogni creazione. I flow template sono un **catalogo** tra cui scegliere: una volta che conosci il `template_token` (e, se serve, lo schema dei campi), puoi riusarlo per tutte le istanze che crei. ### Come ottenere il flow template token 1. **GET /templates** — Chiama questo endpoint quando devi consultare il catalogo: restituisce l'elenco dei flow template disponibili per la tua API key. 2. La risposta include, per ogni template, il **template_token**. 3. La risposta include, quando previsto, lo **schema o l'elenco dei campi** che puoi valorizzare in `flow_data` e `sign_data` (campi precompilabili del form e struttura firmatari). La forma esatta è definita nella specifica OpenAPI per `GET /templates`. In sintesi: usi **GET /templates** quando ti serve scoprire o aggiornare il catalogo e i campi compilabili; per creare un True Flow usi sempre **POST /true-flows** con il **template_token** già in tuo possesso. ## Casi d'uso ### 1. Creazione True Flow semplice Si crea un True Flow passando solo il token del flow template. Il flusso viene creato con i valori di default definiti nel template; l'utente finale compilerà il form nel link restituito. **Endpoint:** `POST /true-flows` **Body minimo:** ```json { "template_token": "", "name": "Nome del flusso" } ``` **Risposta:** contiene il **token** del True Flow e l'URL **trueLink** (deeplink) da inviare all'utente. ### 2. Creazione True Flow con dati prepopolati Vuoi precompilare alcuni campi del form (es. nome, email, riferimento pratica). I campi compilabili sono quelli restituiti nello schema del flow template (GET /templates). **Endpoint:** `POST /true-flows` **Body:** ```json { "template_token": "", "name": "Flusso con dati prepopolati", "flow_data": { "nome": "Mario", "cognome": "Rossi", "email": "mario.rossi@example.com" } } ``` - **flow_data** è un oggetto chiave-valore: le chiavi sono i nomi dei campi definiti nel template; i valori devono rispettare tipo e vincoli dello schema. - I valori in `flow_data` diventano i **valori di default** del form. ### 3. Creazione True Flow con allegati Per allegare file al flusso sono necessarie **tre chiamate** in sequenza. #### Passo 1 — Ottenere token e URL di upload **Endpoint:** `POST /true-flows-attachments` **Body:** ```json { "file_name": "documento.pdf" } ``` **Risposta:** ```json { "token": "", "file_name": "documento.pdf", "upload_url": "https://..." } ``` - **token:** identificativo dell'allegato; lo userai in `flow_data`. - **upload_url:** URL firmato temporaneo (presigned URL) per caricare il file. Ha una scadenza di 120 secondi. #### Passo 2 — Caricare il file Esegui una richiesta **PUT** sull'**upload_url** restituito, con il corpo della richiesta uguale al contenuto binario del file (es. `Content-Type: application/pdf` per un PDF). Il client HTTP deve usare esattamente l'URL restituito; non aggiungere header aggiuntivi non richiesti dalla signed URL (di solito solo `Content-Type` e il body). #### Passo 3 — Creare il True Flow includendo gli allegati **Endpoint:** `POST /true-flows` Nel **flow_data**, inserisci i token degli allegati nei campi che il flow template riserva agli allegati (es. un campo tipo `documents` che accetta un array di token). **Body di esempio:** ```json { "template_token": "", "name": "Flusso con allegato", "flow_data": { "documents": ["", ""] } } ``` - I nomi dei campi per gli allegati (es. `documents`) dipendono dal flow template; puoi ricavarli dallo schema restituito da **GET /templates** (campi con `format: "attachment"`). - Ogni elemento dell'array è il **token** restituito da **POST /true-flows-attachments** dopo aver completato l'upload con PUT. **Riassunto sequenza:** 1. Per ogni file: `POST /true-flows-attachments` → ottieni `token` e `upload_url`. 2. Per ogni file: `PUT upload_url` con il corpo = contenuto del file. 3. `POST /true-flows` con `flow_data` contenente, nei campi allegati del template, gli array di token. ### 4. Creazione True Flow con firmatari Se il flow template prevede una sezione firmatari (`signData`), puoi passare i dati dei firmatari nell'array **sign_data**. **Endpoint:** `POST /true-flows` **Body di esempio:** ```json { "template_token": "", "name": "Flusso con firmatari", "sign_data": [ { "nome": "Mario", "cognome": "Rossi", "email": "mario.rossi@example.com" }, { "nome": "Luigi", "cognome": "Verdi", "email": "luigi.verdi@example.com" } ] } ``` - **sign_data** è un array di oggetti; ogni oggetto corrisponde a un firmatario. - I campi ammessi (es. `nome`, `cognome`, `email`) dipendono dallo schema **signData** del flow template; puoi ricavarlo da **GET /templates**. - I valori vengono inseriti nella sezione firmatari del flusso e utilizzati per l'invito alla firma. ## Combinazione di più opzioni Puoi combinare **flow_data**, **sign_data** e allegati nella stessa chiamata a **POST /true-flows**: ```json { "template_token": "", "name": "Flusso completo", "flow_data": { "riferimento": "PRAT-2024-001", "documents": [""] }, "sign_data": [ { "nome": "Mario", "cognome": "Rossi", "email": "mario.rossi@example.com" } ] } ``` L'ordine richiesto resta: prima eventuali **POST /true-flows-attachments** e **PUT** di upload, poi **POST /true-flows** con tutti i token e i dati desiderati.