Modelli, ruoli e campi

Un modello è un contratto riutilizzabile. Ha un nome, una sola bozza e un numero qualsiasi di versioni pubblicate. Le buste si creano sempre da una versione pubblicata, che è immutabile: modificare un modello significa salvare una nuova bozza e pubblicarla come versione successiva. Le buste già inviate mantengono la versione che hanno fissato.

{
  "id": "tpl_3kQ9xV2mLp",
  "organization": "org_…",
  "name": "Mutual NDA",
  "description": "Two-party NDA, US law",
  "latestVersion": 3,
  "draftVersion": 4,
  "createdAt": "2026-10-01T09:12:44.120Z",
  "updatedAt": "2026-10-12T16:03:10.981Z"
}

Gli id sono stringhe con prefisso (tpl_, tplv_, tfl_, env_, rcp_, ses_, lnk_, evt_, whk_, whd_, …); gli orari sono in formato RFC 3339 in UTC.

Due modi di creare un modello

La modalità Sovrapposizione (source: "pdf") parte da un documento caricato. I campi sono rettangoli posizionati sulle sue pagine in punti PDF (1/72 di pollice), con l’origine nell’angolo in alto a sinistra della pagina e l’indice di pagina a partire da 0. Un file .docx caricato viene convertito in PDF una sola volta (con LibreOffice, mantenendo il layout di Word; i font che il file non incorpora possono essere sostituiti) e da quel momento è un PDF come qualsiasi altro: il file riporta convertedFrom: "docx". Le versioni in modalità Sovrapposizione possono contenere anche modifiche al contenuto (testo modificato sul posto, bianchetto, caselle di testo, immagini, operazioni sulle pagine) che vengono applicate alla pubblicazione della versione.

La modalità Documento (source: "document") memorizza il contratto stesso come testo formattato (ProseMirror JSON) con segnaposto di variabili come {{client.name}}, blocchi di campo in linea, sezioni condizionali (mantenute solo quando un’espressione showIf è vera) e sezioni e righe di tabella ripetute (una per ogni elemento di una variabile di tipo array). Ogni busta compone il proprio PDF e le posizioni dei campi vengono lette da quella composizione. Nella dashboard, la modalità Documento corrisponde a “Inizia da un documento vuoto”. Tramite l’API è possibile anche importare un file Word in modalità Documento con POST /v1/templates/{id}/import: i {{tags}} diventano variabili o campi e le righe per la firma (“Signature: ____”, “By: ____”, “Date: ____”) diventano blocchi di campo.

Nella dashboard

Nuovo modello offre due punti di partenza:

Carica documento: un’unica area di rilascio per file .pdf e .docx fino a 25 MB. I file Word vengono convertiti in PDF e si aprono nell’editor con un promemoria per controllare il layout convertito prima di posizionare i campi. Le piccole correzioni si fanno direttamente sul PDF (“Modifica contenuto”); per una revisione più ampia, modifichi il file Word e lo carichi di nuovo.
Inizia da un documento vuoto: scriva il contratto in modalità Documento.

Modifiche al contenuto

La modalità Modifica contenuto dell’editor cambia ciò che vedono i firmatari senza toccare il file caricato. Il suo strumento predefinito, Modifica testo, evidenzia i blocchi di testo della pagina (righe e paragrafi raggruppati a partire dal livello di testo del PDF); faccia clic su uno, oppure lo raggiunga con Tab e prema Invio, per modificarlo sul posto con la stessa posizione, dimensione, colore, allineamento e font. Ctrl/Cmd+Invio salva, Esc annulla e ogni modifica può essere ripristinata dall’elenco delle modifiche. Le modifiche si possono annullare come qualsiasi altra modifica. Gli altri strumenti aggiungono bianchetto, caselle di testo e immagini, e inseriscono, eliminano, riordinano o ruotano le pagine.

Una modifica del testo sul posto viene memorizzata come due elementi che condividono un group: un bianchetto sopra il blocco originale (nel colore di sfondo della pagina) e un elemento di testo impaginato nel blocco, con l’interlinea e la prima linea di base del blocco:

[
  { "id": "whiteout_k2", "kind": "whiteout", "group": "blk_k1", "page": 0, "color": "#FFFFFF",
    "rect": { "x": 71, "y": 209.9, "width": 452, "height": 26.9 } },
  { "id": "text_k3", "kind": "text", "group": "blk_k1", "page": 0, "rect": { "x": 72, "y": 210.9, "width": 451, "height": 24.9 },
    "text": "1. Purpose. The Parties wish to evaluate a joint venture…", "original": "1. Purpose. The Parties wish to evaluate a possible business relationship…",
    "size": 10.5, "lineHeight": 15.23, "baseline": 7.54, "padding": 0, "align": "left", "color": "#0B0F1A",
    "face": { "source": "pdf", "name": "ABCDEF+Calibri", "fallback": "carlito" }, "font": "helvetica" }
]

face sceglie il font: il font incorporato nel PDF quando può disegnare ogni carattere del nuovo testo, altrimenti un font incluso con metriche compatibili (sans Arimo per Helvetica/Arial, serif Tinos per Times, mono Cousine per Courier, carlito Carlito per Calibri) con peso e stile corrispondenti. Il testo va a capo all’interno del blocco; quando servono più righe dell’originale, la modifica si estende nello spazio libero sottostante e l’editor rifiuta di salvarla quando non ce n’è (“il testo non entra: lo accorci o aggiunga spazio”). L’editor e l’API condividono il codice di impaginazione e dei font, quindi il PDF pubblicato corrisponde all’anteprima riga per riga.

Le modifiche possono cambiare solo una bozza. La pubblicazione le applica a un nuovo PDF di base il cui SHA-256 è il documentHash della versione (l’hash di ciò che vedono i firmatari); l’originale caricato viene conservato come sourceFile della versione e la bozza successiva parte da esso con le stesse modifiche. Il bianchetto copre il contenuto solo visivamente; il testo originale resta nel file sottostante, quindi non è un oscuramento sicuro.

Ruoli

I ruoli sono le parti del contratto. I destinatari di una busta vengono associati ai ruoli tramite key.

{ "key": "client", "label": "Client", "kind": "signer", "order": 1, "verification": "none" }

Proprietà	Significato
`key`	Identificatore in minuscolo (`^[a-z][a-z0-9_]*$`) usato dai campi e dai destinatari della busta
`kind`	`signer` (deve avere un campo firma o sigla), `approver`, `form_filler` o `cc` (riceve, non firma mai)
`order`	Ordine di instradamento a partire da 1. I ruoli con lo stesso ordine firmano in parallelo; l’ordine successivo inizia quando hanno terminato
`verification`	Come il destinatario del ruolo dimostra la propria identità: `none` (predefinito: solo il link di firma univoco) o `email_otp` (il link più un codice inviato via e-mail). Un destinatario può sostituirlo; veda verifica del firmatario

passkey, id_check e sms_otp compaiono nello schema ma non sono ancora disponibili per la firma: un modello che usa passkey o id_check non può essere pubblicato e i codici SMS non vengono ancora recapitati.

Campi

{
  "id": "client_signature",
  "type": "signature",
  "role": "client",
  "label": "Signature",
  "required": true,
  "rect": { "page": 1, "x": 72, "y": 610, "width": 220, "height": 48 }
}

Tipi di campo: signature, initials, name, email, date_signed, text, number, date, checkbox, radio, dropdown, attachment, formula, stamp e variable_text (compilato dal mittente a partire da una variabile, non da un firmatario). I campi possono avere anche:

variable: un JSON Pointer nelle variabili (/client/name) per collegare o precompilare il campo;
options per radio e dropdown;
validation: pattern, min, max, maxLength o un format (email, phone, date, number, currency);
showIf: una condizione su variabili e altri campi, ad esempio plan != "free";
formula: un valore calcolato, di sola lettura;
overflow: che cosa fare quando un valore non entra nel riquadro: shrink (predefinito), wrap o reject.

Variabili

Le variables di una versione sono un JSON Schema (draft 2020-12) per i dati che invia con ogni busta; i sampleVariables della versione sono un esempio. POST /v1/envelopes convalida le Sue variables rispetto a esso e segnala ogni problema con un JSON Pointer:

{
  "type": "https://bonafidesign.com/problems/validation-error",
  "title": "Validation failed",
  "status": 422,
  "detail": "The request is invalid.",
  "errors": [
    { "pointer": "/variables/client/name", "message": "is required", "hint": "Provide a value for 'name'." }
  ]
}

Per vedere il risultato prima dell’invio, generi un’anteprima con filigrana di qualsiasi versione con POST /v1/templates/{id}/versions/{version}/render ({ "variables": { … } } → PDF), oppure crei la busta con ?dry_run=true.

Creare un modello con l’API

La maggior parte dei team progetta i modelli nell’editor della dashboard. Tutto ciò che fa è disponibile tramite l’API:

POST /v1/templates con { "name": "Mutual NDA" }.
POST /v1/templates/{id}/files con il PDF (o il .docx) come corpo (Content-Type: application/pdf) o come campo multipart file. Fino a 25 MB. La risposta contiene l’id del file (tfl_…), il numero di pagine e le dimensioni delle pagine.
PUT /v1/templates/{id}/draft con roles, fields, variables (e file, oppure source: "document" con content). Le bozze vengono salvate così come sono; per ora non viene controllato nulla.
POST /v1/templates/{id}/publish. La pubblicazione esegue un controllo della bozza: il ruolo di ogni campo esiste, ogni ruolo di firmatario ha un campo firma, i campi rientrano nelle pagine, i campi radio e dropdown hanno opzioni, le espressioni sono analizzabili. I problemi vengono restituiti come 422 con puntatori come /fields/3/rect.

curl https://api.bonafidesign.com/v1/templates/tpl_3kQ9xV2mLp/files \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @nda.pdf

Gli endpoint delle versioni accettano un numero, latest o draft: GET /v1/templates/{id}/versions/latest, GET /v1/templates/{id}/versions/2/document (il PDF di base). Un modello mai usato da una busta o da un link di firma può essere eliminato; altrimenti DELETE risponde 409 in-use.