Flusso di chiamate True Flow

Copia

• Copia per LLM

  Copia pagina come Markdown per LLM
• Visualizza come Markdown

  Apri questa pagina come Markdown
• Apri in ChatGPT

  Ottieni informazioni da ChatGPT
• Apri in Claude

  Ottieni approfondimenti da Claude
• Connetti a Cursor

  Installa il server MCP su Cursor
• Connetti a VS Code

  Installa il server MCP su VS Code

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

In tutti i casi le richieste devono includere l'autenticazione con API key. Per il contesto sui token usati nelle chiamate, vedi Flow template token; per combinare più opzioni in un'unica creazione, vedi Combinazione di più 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:

{
  "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:

{
  "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:

{
  "file_name": "documento.pdf"
}

Risposta:

{
  "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:

{
  "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:

{
  "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:

{
  "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.