# 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).

## 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** (e, ove previsto, il report template associato).
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": "<token_ottenuto_da_GET_templates>",
  "name": "Nome del flusso"
}
```

**Risposta:** contiene il **token** del True Link 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": "<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": "<attachment_token>",
  "file_name": "documento.pdf",
  "upload_url": "https://..."
}
```

- **token:** identificativo dell'allegato; lo userai in `flow_data`.
- **upload_url:** URL firmato (signed URL) per caricare il file.


#### 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": "<template_token>",
  "name": "Flusso con allegato",
  "flow_data": {
    "documents": ["<attachment_token_1>", "<attachment_token_2>"]
  }
}
```

- 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": "<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": "<template_token>",
  "name": "Flusso completo",
  "flow_data": {
    "riferimento": "PRAT-2024-001",
    "documents": ["<attachment_token>"]
  },
  "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.