Vai al contenuto

Guida ai workflow

Questa guida spiega come è strutturata l'API di NSE e come è possibile combinarne i componenti di base per modellare un'ampia gamma di scenari di firma reali. Anziché illustrare le singole chiamate API, si concentra sui concetti alla base dell'API e sui diversi modelli di workflow che è possibile realizzare.


I componenti di base

Ogni workflow di firma in NSE è costruito a partire da quattro oggetti annidati l'uno nell'altro:

Envelope
  └── Stage 1
  │     ├── Recipient A
  │     └── Recipient B
  └── Stage 2
        └── Recipient C
  └── File (Document)
        └── Field Tasks  (linked to specific recipients)

Envelope — il contenitore di primo livello. Racchiude tutto: documenti, fasi e relativi destinatari. Una pratica attraversa un ciclo di vita (draft → sent → completed) ed è l'oggetto che viene monitorato e da cui si effettuano i download.

Stage — un passaggio del workflow di firma. Le fasi vengono eseguite in sequenza: la fase 2 non inizia finché la fase 1 non è completata integralmente. All'interno di una singola fase, tutti i destinatari assegnati vengono notificati e agiscono in parallelo.

Recipient — una persona assegnata a una fase (può trattarsi anche di una fase automatica che non richiede alcuna interazione). Il destinatario riceve un invito (tramite e-mail, SMS o WhatsApp), apre il documento ed esegue l'azione richiesta dalla propria fase.

File e Field Task — documenti allegati alla pratica con campi interattivi (firme, caselle di controllo, campi di testo) posizionati su pagine specifiche. Ogni campo è collegato a un destinatario specifico, così ciascuna persona vede e utilizza soltanto i campi a lei assegnati.


Documenti

Una pratica può contenere uno o più documenti. Ogni documento viene caricato nella pratica come file PDF separato tramite una richiesta multipart/form-data.

Caricamento dei file

Il caricamento di un file non lo rende ancora interattivo: lo allega semplicemente alla pratica e restituisce un fileId. Gli elementi interattivi vengono aggiunti separatamente tramite i field task.

In un workflow con più documenti, i destinatari possono avere campi su alcuni documenti e non su altri, e lo stesso documento può avere campi assegnati a destinatari diversi.

Approfondimento sulle fasi

Le fasi sono il meccanismo principale per controllare il flusso e l'ordine di un processo di firma.

Esecuzione sequenziale

Le fasi sono numerate e vengono eseguite nell'ordine in cui sono state create. La seconda fase non viene attivata finché tutte le azioni obbligatorie della prima fase non sono completate. Questo rende immediato modellare catene di approvazione, controfirme e altri processi articolati in più passaggi.

Tipi di fase

Ogni fase ha un tipo che definisce ciò che i destinatari di quella fase sono tenuti a fare:

TipoCosa fanno i destinatari
SignerFirmano o interagiscono con i campi firma nel documento
ApproverApprovano o respingono la pratica prima che passi alla fase successiva
CarbonCopyRicevono una copia della pratica per conoscenza: non è richiesta alcuna azione
ViewerVisualizzano il documento: non è richiesta alcuna azione
AutomaticPassaggio gestito dal sistema, senza destinatari umani

Una pratica inizia tipicamente con una o più fasi Signer, ma è possibile disporre qualsiasi combinazione in qualsiasi ordine. Un modello ricorrente prevede una fase Approver prima di una fase Signer, così che una persona interna riesamini il documento prima che venga inviato al firmatario esterno.

Controllare quanti destinatari devono completare una fase

Per impostazione predefinita, tutti i destinatari di una fase devono completare la propria azione prima che la fase avanzi. È possibile modificare questo comportamento tramite requiredRecipientCompletions.

Questo campo accetta un numero intero: il numero minimo di destinatari che devono completare la fase perché sia considerata conclusa. Se una fase contiene tre destinatari ma requiredRecipientCompletions è impostato su 1, la fase si completa appena uno di essi firma. Questo è utile in scenari come:

  • Firma di un comitato: invio a cinque membri del consiglio, con la firma di due di essi come requisito.
  • Pool di firmatari autorizzati: invio a tre firmatari autorizzati, uno qualsiasi dei quali può firmare a nome del gruppo. Se requiredRecipientCompletions non è impostato, assume come valore predefinito il numero totale di destinatari della fase (tutti devono completare).

Configurazione del destinatario

Ogni destinatario viene configurato a livello di fase e può essere configurato prima che vengano predisposti documenti o campi. Il record del destinatario controlla identità, comunicazione, sicurezza di accesso e, ove necessario, i dati di preconfigurazione richiesti per le firme basate su certificato.

Identità e dati di contatto

Un destinatario è identificato da nome, cognome, indirizzo email e, facoltativamente, da un numero di telefono. Il numero di telefono è obbligatorio quando si utilizza l'autenticazione tramite SMS o la firma con OTP.

Canali di notifica

È possibile controllare la modalità con cui il destinatario riceve l'invito ed eventuali promemoria tramite notificationChannels. Le opzioni disponibili sono Email, Sms e WhatsApp.

Lingua

Il campo languageCode imposta la lingua utilizzata per tutte le e-mail, i messaggi SMS e gli elementi dell'interfaccia mostrati a questo destinatario. Utile quando il workflow coinvolge destinatari in Paesi differenti.

Autenticazione

L'autenticazione aggiunge un controllo di identità che il destinatario deve superare prima di poter accedere al documento. Sono disponibili tre meccanismi, che possono anche essere combinati:

  • Codice di accesso — un codice segreto statico definito dal mittente. Il destinatario deve inserire il codice corretto per aprire la pratica. Il codice viene condiviso con il destinatario attraverso un canale proprio.
  • OTP via SMS — una password temporanea inviata a un numero di telefono nel momento in cui il destinatario tenta di aprire il documento. Il numero di telefono va specificato durante la configurazione del destinatario.
  • OAuth — il destinatario si autentica tramite un provider di identità esterno. Occorre fornire il nome del provider e l'identificativo esterno del destinatario per collegare gli account.

Configurazione della firma

La configurazione della firma sul destinatario è necessaria soltanto per i metodi di firma che richiedono dati predisposti in anticipo, in particolare:

  • Certificato usa e getta — un certificato qualificato monouso emesso al momento della firma. Occorre fornire i dati del documento di identificazione del destinatario (tipo, numero, nazione di emissione, scadenza e così via) e un numero di telefono di verifica. La piattaforma utilizza queste informazioni per emettere il certificato durante la sessione di firma.
  • Certificato remoto — il destinatario firma utilizzando un certificato conservato in un servizio di firma remota. Occorre fornire l'ID utente e l'ID dispositivo che identificano il certificato in tale servizio.
  • Firma con OTP — una password temporanea via SMS che funge da firma stessa (da non confondere con l'OTP come metodo di autenticazione di accesso). Occorre fornire il numero di telefono al quale l'OTP viene inviato nel momento della firma.
  • Plugin di firma — integrazioni di firma di terze parti. Occorre specificare l'ID del plugin e le eventuali impostazioni chiave/valore richieste dal plugin. Per tutti gli altri metodi di firma — click-to-sign, draw-to-sign, type-to-sign, biometrico, certificato locale — non è necessaria alcuna preconfigurazione sul destinatario. I metodi consentiti sono invece controllati da allowedSignatureTypes sul campo firma stesso, che viene impostato durante il posizionamento del campo sul documento.

Messaggio personale

Un messaggio in testo libero mostrato al destinatario insieme all'invito standard. È possibile utilizzarlo per fornire contesto, per esempio spiegando quale documento si sta firmando o indicando istruzioni specifiche per questa pratica.


Scenari di workflow

Gli scenari seguenti illustrano come fasi e destinatari si combinano per gestire i casi reali più comuni.


Scenario 1 — Firmatario unico

Il workflow più semplice: un documento, una persona che firma.

Stage 1 (Signer)
  └── Alice

Alice riceve un invito, apre il documento, appone la propria firma e la pratica si completa.


Scenario 2 — Due firmatari in sequenza

Entrambe le parti devono firmare e l'ordine è rilevante. Il contratto viene inviato prima alla prima parte; solo dopo la sua firma la seconda parte riceve il proprio invito.

Stage 1 (Signer)   →   Stage 2 (Signer)
  └── Alice                └── Bob

È una configurazione frequente nei contratti bilaterali, in cui una parte avvia il processo e l'altra controfirma.


Scenario 3 — Più firmatari in parallelo

Due o più persone devono firmare, ma l'ordine non è rilevante. Ricevono tutte l'invito nello stesso momento e possono firmare in modo indipendente.

Stage 1 (Signer)
  ├── Alice
  └── Bob

Alice e Bob ricevono l'invito contemporaneamente. La pratica non si completa finché entrambi non hanno firmato (requiredRecipientCompletions = 2, che è anche il valore predefinito in presenza di due destinatari).


Scenario 4 — Firma di gruppo (N di M)

Nell'elenco sono presenti tre firmatari autorizzati, ma la firma di uno qualsiasi di essi è sufficiente per perfezionare l'accordo.

Stage 1 (Signer) — requiredRecipientCompletions: 1
  ├── Alice
  ├── Bob
  └── Carol

Tutti e tre ricevono l'invito nello stesso momento. La pratica avanza appena uno di essi firma. Per gli altri due non è più richiesta alcuna azione.

Questo modello si utilizza anche per scenari a voto di maggioranza, per esempio richiedendo la firma di 3 membri del consiglio su 5.


Scenario 5 — Approvazione interna prima della firma esterna

Un documento deve essere approvato da un revisore interno prima di essere inviato al cliente per la firma.

Stage 1 (Approver)   →   Stage 2 (Signer)
  └── Internal Manager       └── Customer

Il responsabile riceve il documento per primo e lo approva oppure lo respinge. Se lo approva, viene attivata la fase 2 e il cliente riceve il proprio invito alla firma. Se lo respinge, la pratica si arresta e il mittente riceve una notifica.


Scenario 6 — Firma seguita da notifica in copia

Dopo che tutte le parti hanno firmato, un soggetto terzo (per esempio l'ufficio legale o un sistema di archiviazione) deve ricevere automaticamente una copia del documento completato.

Stage 1 (Signer)   →   Stage 2 (CarbonCopy)
  ├── Alice                └── Legal Team
  └── Bob

Il destinatario della fase CarbonCopy non compie alcuna azione: riceve semplicemente la pratica come notifica una volta completate le fasi precedenti. È un modo pulito per garantire che le persone interessate siano informate senza obbligarle ad accedere o a interagire con il documento.


Scenario 7 — Più fasi con tipi differenti

Un workflow complesso che combina approvazione, firma in parallelo e notifica:

Stage 1 (Approver)   →   Stage 2 (Signer)        →   Stage 3 (CarbonCopy)
  └── Legal Reviewer       ├── Party A                  └── Archive System
                           └── Party B

Il revisore legale approva per primo il documento. Entrambe le parti ricevono quindi il proprio invito contemporaneamente e devono firmare entrambe. Successivamente il sistema di archiviazione riceve automaticamente il documento completato.


Field task

I field task rappresentano il collegamento tra una posizione su un documento e un destinatario. Un task definisce:

  • Quale tipo di interazione è prevista (una firma, una casella di controllo, un campo di testo e così via)
  • In quale punto del documento compare il campo (quale pagina e le coordinate x/y dell'angolo superiore sinistro del campo, espresse in unità di pagina PDF)
  • Quanto è grande il campo (larghezza e altezza)
  • Chi è responsabile del suo completamento (il recipientId)
  • In quale ordine i campi vengono presentati al firmatario (sortOrder) I field task vengono impostati per ciascun file tramite una richiesta PUT. Questa chiamata è una sostituzione completa: definisce l'elenco integrale dei task per quel documento. Se viene richiamata una seconda volta con un elenco modificato, i task precedenti vengono interamente scartati e diventa effettivo il nuovo elenco.

Tipi di campo

La proprietà fieldType di un field task determina ciò che il destinatario vede e ciò che è tenuto a fare:

Tipo di campoCosa fa
SignatureIl destinatario appone una firma. I metodi di firma consentiti sono controllati da allowedSignatureTypes sul campo stesso.
TextInputIl destinatario inserisce del testo (il mittente può impostare formati specifici, ad esempio data o numero).
CheckboxIl destinatario seleziona o deseleziona una casella.
RadiobuttonIl destinatario seleziona uno dei pulsanti di opzione proposti.
DropDownIl destinatario seleziona un valore da un menu a discesa predefinito.
ListBoxIl destinatario seleziona uno o più valori da un elenco visibile.
AttachmentIl destinatario carica un file come parte della propria risposta.
AreaReadConfirmationIl destinatario deve confermare esplicitamente di avere letto un'area specifica all'interno di una pagina.
PageReadConfirmationIl destinatario deve confermare di avere letto un'intera pagina prima di procedere.
FileReadConfirmationIl destinatario deve confermare di avere letto l'intero documento.
LinkMostra un collegamento cliccabile all'interno del documento, che tipicamente rimanda a una risorsa esterna che il destinatario deve consultare.
ApprovalIl destinatario approva facendo clic sul campo (meccanismo analogo a quello della firma ClickToSign)

Campo firma e metodi di firma consentiti

Specificamente per i campi Signature, è possibile limitare i metodi di firma tra cui il destinatario può scegliere impostando allowedSignatureTypes sul campo. Se questo valore viene lasciato vuoto o null, viene applicata la configurazione predefinita dell'organizzazione.

I tipi di firma confermati sono:

Tipo di firmaDescrizione
ClickToSignSignatureIl destinatario fa clic su un pulsante per confermare la propria firma: non è richiesto alcun tracciato né certificato.
DrawToSignSignatureIl destinatario traccia la propria firma con il mouse o su uno schermo touch.
TypeToSignSignatureIl destinatario digita il proprio nome, che viene reso come firma.
BiometricSignatureAcquisisce dati biometrici (pressione, velocità, ritmo) durante il gesto di firma.
LocalCertificateSignatureIl destinatario firma utilizzando un certificato conservato sul proprio dispositivo locale (ad esempio una smart card o un token USB).
DisposableCertificateSignatureAl momento della firma viene emesso un certificato qualificato monouso. Richiede una preconfigurazione sul destinatario.
RemoteCertificateSignatureIl destinatario firma utilizzando un certificato conservato in un servizio di firma remota. Richiede una preconfigurazione sul destinatario.
OneTimePasswordSignatureUn OTP inviato via SMS funge da firma. Richiede una preconfigurazione sul destinatario.
AutomaticSignatureLa firma viene apposta senza alcuna interazione umana.
PluginSignatureLa firma è gestita dall'integrazione di un plugin di terze parti. Richiede la configurazione del plugin sul destinatario.

Questo aspetto è distinto da signatureConfiguration sul destinatario. L'attributo allowedSignatureTypes del campo controlla quali metodi vengono proposti nell'interfaccia. L'attributo signatureConfiguration del destinatario fornisce i dati predisposti in anticipo richiesti dai metodi che ne hanno bisogno (certificato usa e getta, certificato remoto, firma con OTP, plugin di firma). Per tutti gli altri metodi è sufficiente la configurazione del campo: non è necessario impostare dati aggiuntivi sul destinatario.

Annotazioni

È possibile aggiungere le seguenti annotazioni:

  • Text
    • Definisce un testo visibile al destinatario sul documento
  • Date
    • Aggiunge la data al documento
  • FullName
    • Aggiunge il nome e cognome del destinatario al documento
  • FirstName
    • Aggiunge il nome del destinatario al documento
  • LastName
    • Aggiunge il cognome del destinatario al documento
  • Initials
    • Aggiunge le iniziali del destinatario al documento
  • Email
    • Aggiunge l'indirizzo email del destinatario al documento

Posizionamento dei campi

La posizione e la dimensione dei campi sono definite in unità di coordinate di pagina PDF:

  • positionX e positionY sono le coordinate dell'angolo superiore sinistro del campo sulla pagina
  • width e height definiscono la dimensione del campo
  • page specifica su quale pagina del documento compare il campo (con indice a partire da 1)

Assegnazione di più campi allo stesso destinatario

Un singolo destinatario può avere più field task su uno o più documenti. La proprietà sortOrder controlla la sequenza con cui i campi gli vengono presentati durante la sessione di firma. I campi con valore di ordinamento più basso vengono mostrati per primi. Questo permette di guidare il firmatario attraverso il documento secondo un ordine logico, indipendentemente da dove i campi siano fisicamente posizionati sulla pagina.


Il ciclo di vita della pratica

Una volta inviata, una pratica attraversa un insieme definito di stati:

draft → sent → completed
                ↘ rejected
                ↘ expired
                ↘ cancelled
StatoSignificato
draftLa pratica è stata creata ma non ancora inviata. Può ancora essere modificata.
sentI destinatari sono stati notificati e il workflow è attivo.
completedTutte le fasi obbligatorie sono state completate correttamente.
rejectedUn destinatario ha respinto il documento.
expiredIl termine è scaduto prima del completamento del workflow.
cancelledIl mittente ha interrotto manualmente il processo.

Una volta che una pratica raggiunge uno stato terminale (completed, rejected, expired, cancelled) non può più essere modificata né fatta avanzare. I documenti firmati e l'audit trail diventano disponibili per il download dall'endpoint artifacts.


Utilizzo dei modelli per i workflow ricorrenti

Se si invia ripetutamente la stessa struttura di documenti — le stesse fasi, la stessa disposizione dei campi, lo stesso ordine di firma — è possibile definire tutto questo una sola volta come modello. Quando serve una nuova pratica, la si crea dal modello con una sola chiamata API. La pratica risultante è una copia indipendente e, se necessario, può essere modificata prima dell'invio.

I modelli sono particolarmente utili quando:

  • Il documento cambia ogni volta, ma la struttura del workflow è sempre la stessa.
  • È necessario creare a livello programmatico molte pratiche in blocco.
  • Si vuole imporre un processo di firma standard in tutta l'organizzazione.

Principi di progettazione fondamentali

Alcuni aspetti da tenere presenti durante la progettazione dell'integrazione:

Tutto è delimitato dall'organizzazione. Tutte le chiamate API includono l'organizationId nel percorso. È l'identificatore del tenant e determina quali configurazioni, modelli e pratiche completate sono accessibili.

I campi vengono assegnati ai destinatari, non alle fasi. Il posizionamento di un campo firma richiede il recipientId specifico. Ciò significa che occorre prima aggiungere fasi e destinatari e solo dopo posizionare i field task.

La chiamata di invio è il punto di non ritorno. Fino a quando non si richiama l'endpoint di invio, la pratica resta in draft e può essere modificata liberamente. Una volta inviata, il workflow è attivo e i destinatari vengono notificati.

Il completamento di una fase attiva automaticamente la fase successiva. Non è necessario effettuare polling né far avanzare manualmente il workflow. Appena una fase raggiunge il numero richiesto di completamenti, l'API attiva la fase successiva e invia gli inviti al gruppo di destinatari successivo.

Per un workflow completo di una pratica, consultare la guida seguente: Envelope-Workflow

Per un workflow completo di un modello, consultare la guida seguente: Template-Workflow