Passer au contenu

Signature de groupe

Ce guide explique comment configurer la signature de groupe via l'API NSE v1. La signature de groupe contrôle le nombre de destinataires d'une étape devant finaliser leur action avant que l'enveloppe n'avance. Il existe deux variantes :

  • Signature de groupe x sur x — chaque destinataire de l'étape doit signer (également appelée signature en parallèle).
  • Signature de groupe x sur y — seul un sous-ensemble doit signer (p. ex. 2 sur 5).

Le reste du flux d'enveloppe — création de l'enveloppe, téléversement des documents, ajout des destinataires, placement des champs et envoi — suit les mêmes étapes décrites dans le guide Flux d'enveloppe de base. Ce guide se concentre sur le seul champ qui modifie le comportement : requiredRecipientCompletions.

Fonctionnement

Lors de la création d'une étape, requiredRecipientCompletions définit le nombre de destinataires devant finaliser leur action avant que l'étape ne se clôture et que l'enveloppe n'avance. Tous les destinataires de l'étape reçoivent leur invitation en même temps.

VarianterequiredRecipientCompletionsEffet
x sur xÉgal au nombre total de destinatairesChaque destinataire doit signer
x sur yInférieur au nombre total de destinatairesLes x premiers à signer clôturent l'étape ; les autres ne peuvent plus agir

Signature de groupe x sur x

Les 3 destinataires doivent signer avant que l'enveloppe n'avance.

Étape : requiredRecipientCompletions = 3  (nombre total de destinataires = 3)
  ├── Alice  →  doit signer
  ├── Bob    →  doit signer
  └── Carol  →  doit signer

Créer l'étape :

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

Ajouter les destinataires — appeler cet endpoint une fois par destinataire en sauvegardant chaque id retourné :

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

Répéter pour Bob et Carol. Assigner un champ de signature à chaque destinataire via l'endpoint des tâches, puis envoyer. Le statut de l'enveloppe reste inProgress jusqu'à ce que les 3 aient signé.

Signature de groupe x sur y

Seuls 2 des 5 destinataires doivent signer. Dès que la deuxième signature est collectée, l'étape se clôture et les 3 destinataires restants ne peuvent plus agir.

Étape : requiredRecipientCompletions = 2  (nombre total de destinataires = 5)
  ├── Alice  →  signe ✓
  ├── Bob    →  signe ✓  ← seuil atteint, l'étape se clôture
  ├── Carol  →  n'est plus requise
  ├── David  →  n'est plus requis
  └── Eva    →  n'est plus requise

Créer l'étape :

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

Ajouter les destinataires — appeler cet endpoint une fois par destinataire en sauvegardant chaque id retourné :

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

Répéter pour Bob, Carol, David et Eva — 5 appels au total. Un champ de signature doit être assigné à chaque destinataire via l'endpoint des tâches, même si seules 2 finalisations sont requises, afin que n'importe lequel d'entre eux puisse être parmi les premiers à signer. Envoyer ensuite l'enveloppe normalement.

Règles importantes

  • requiredRecipientCompletions doit être supérieur à 0 et ne peut pas dépasser le nombre total de destinataires dans l'étape.
  • Le définir égal au nombre total de destinataires signifie que tout le monde doit signer (x sur x).
  • Le définir à une valeur inférieure signifie que seuls les x premiers à signer sont requis (x sur y).