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.
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.
| Variante | requiredRecipientCompletions | Effetto |
|---|---|---|
| x su x | Pari al totale dei destinatari | Ogni destinatario deve firmare |
| x su y | Inferiore al totale dei destinatari | I primi x che firmano chiudono lo stage; gli altri non possono più agire |
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 signCreare 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.
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 requiredCreare 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.
requiredRecipientCompletionsdeve essere maggiore di0e 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).