Vai al contenuto

Firma di gruppo

Questa guida spiega come configurare la firma di gruppo utilizzando l'API NSE v1. La firma di gruppo determina quanti destinatari all'interno di uno stage devono completare il proprio task prima che la pratica avanzi. Esistono due varianti:

  • Firma di gruppo x su x — ogni destinatario dello stage deve firmare (detta anche firma parallela).
  • Firma di gruppo x su y — solo un sottoinsieme deve firmare (ad esempio 2 su 5).

Il resto del workflow della pratica — creazione della pratica, caricamento dei documenti, aggiunta dei destinatari, posizionamento dei campi e invio — segue gli stessi passaggi descritti nella guida Workflow base della pratica. Questa guida si concentra sull'unico campo che modifica il comportamento: requiredRecipientCompletions.

Come funziona

Quando si crea uno stage, requiredRecipientCompletions definisce quanti destinatari devono completare l'attività prima che lo stage si chiuda e la pratica avanzi. Tutti i destinatari dello stage ricevono il proprio invito nello stesso momento.

VarianterequiredRecipientCompletionsEffetto
x su xPari al totale dei destinatariOgni destinatario deve firmare
x su yInferiore al totale dei destinatariI primi x che firmano chiudono lo stage; gli altri non possono più agire

Firma di gruppo x su x

Tutti e 3 i destinatari devono firmare prima che la pratica avanzi.

Stage: requiredRecipientCompletions = 3  (total recipients = 3)
  ├── Alice  →  must sign
  ├── Bob    →  must sign
  └── Carol  →  must sign

Creare lo stage:

POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/stages
{
  "name": "Board Members",
  "requiredRecipientCompletions": 3,
  "type": "signer"
}

Aggiungere i destinatari — richiamare questo endpoint una volta per ogni destinatario, salvando ogni id restituito:

POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/stages/{stageId}/recipients
{
 "givenName": "Alice",
 "surname": "Smith",
 "email": "alice.smith@example.com",
 "notificationChannels":
 [
  "email"
 ]
}

Ripetere per Bob e Carol. Assegnare un campo firma a ciascun destinatario tramite l'endpoint dei task, quindi inviare. Lo stato della pratica rimane inProgress fino a quando tutti e 3 non hanno firmato.

Firma di gruppo x su y

Solo 2 dei 5 destinatari devono firmare. Appena viene raccolta la seconda firma, lo stage si chiude e i 3 destinatari restanti non possono più agire.

Stage: requiredRecipientCompletions = 2  (total recipients = 5)
  ├── Alice  →  signs ✓
  ├── Bob    →  signs ✓  ← threshold reached, stage closes
  ├── Carol  →  no longer required
  ├── David  →  no longer required
  └── Eva    →  no longer required

Creare lo stage:

POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/stages
{
  "name": "Investment Committee",
  "requiredRecipientCompletions": 2,
  "type": "signer"
}

Aggiungere i destinatari — richiamare questo endpoint una volta per ogni destinatario, salvando ogni id restituito:

POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/stages/{stageId}/recipients
{ 
 "givenName": "Alice",
 "surname": "Smith",
 "email": "alice.smith@example.com",
 "notificationChannels": 
  [
   "email"
  ]
}

Ripetere per Bob, Carol, David ed Eva: 5 chiamate in totale. A ogni destinatario deve essere assegnato un campo firma tramite l'endpoint dei task, anche se sono richiesti solo 2 completamenti, in modo che ciascuno di essi possa essere tra i primi a firmare. Quindi inviare la pratica come di consueto.

Regole fondamentali

  • requiredRecipientCompletions deve essere maggiore di 0 e non superiore al numero totale di destinatari dello stage.
  • Impostandolo pari al numero totale di destinatari, tutti devono firmare (x su x).
  • Impostandolo su un valore inferiore, sono richiesti solo i primi x a firmare (x su y).