Ce guide décrit étape par étape l'envoi d'un même document à un large groupe de destinataires via l'API Enveloppe groupée (Bulk Envelope) de NSE. À la fin, une enveloppe groupée aura été créée, un document téléversé, une étape de signature groupée définie pour les destinataires en masse, une seconde étape ajoutée pour un destinataire standard (non groupé), des champs de signature placés pour les deux, et l'enveloppe groupée envoyée.
Une enveloppe groupée est utile lorsque le même document (par exemple un contrat de campagne ou une reconnaissance de politique) doit être envoyé individuellement à de nombreux destinataires, tout en passant éventuellement encore par un ou plusieurs approbateurs ou signataires fixes, non groupés.
- Un jeton Bearer JWT valide ou un jeton d'accès personnel
- Votre ID d'organisation (
organizationId) - Un document prêt à être téléversé
Commencer par créer l'enveloppe groupée. Comme une enveloppe classique, elle est créée en statut draft et reste modifiable jusqu'à l'envoi.
POST /api/v1/organizations/{organizationId}/bulk-envelopes{
"name": "Bulk contract for Q1 campaign",
"expiration": {
"mode": "Absolute",
"expiresAt": "2026-08-15T06:20:36.459164+00:00"
}
}Réponse 201 Created
{
"id": "b7e2a9c0-1234-1234-1234-1c7e5f8a3d21"
}Sauvegarder le champ id retourné — il s'agit du bulkEnvelopeId pour tous les appels suivants.
Téléverser le PDF qui sera envoyé à chaque destinataire. Cet endpoint utilise multipart/form-data, et non JSON.
POST /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/files
Content-Type: multipart/form-data| Champ | Type | Description |
|---|---|---|
file | binary | Le fichier PDF à joindre |
Réponse 201 Created
{
"id": "c4f81b3d-1234-1234-1234-2d9f4c1b6a05"
}Sauvegarder le champ id retourné — il s'agit du fileId, utilisé lors du placement des champs de signature.
Créer l'étape qui contiendra les destinataires en masse. Définir mode sur Bulk indique au système que les destinataires ajoutés à cette étape recevront chacun leur propre copie de l'enveloppe, signée indépendamment.
POST /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/stages{
"name": "Bulk Stage",
"requiredRecipientCompletions": 1,
"type": "Signer",
"mode": "Bulk"
}Réponse 201 Created
{
"id": "9f534128-1234-1234-1234-ddd212a60d68"
}Sauvegarder le champ id retourné — il s'agit du bulkStageId.
Ajouter les destinataires qui recevront chacun une copie individuelle de l'enveloppe. Répéter cet appel une fois par destinataire.
POST /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/stages/{bulkStageId}/recipientsDestinataire 1
{
"languageCode": "en",
"givenName": "John",
"surname": "Doe",
"email": "john.doe@example.com"
}Réponse 201 Created
{
"id": "01750358-1234-1234-1234-b8ccbd123e79"
}Destinataire 2
{
"languageCode": "en",
"givenName": "Jane",
"surname": "Doe",
"email": "jane.doe@example.com"
}Réponse 201 Created
{
"id": "2b8a6e71-1234-1234-1234-7f3c5d8a2b64"
}En complément de l'étape groupée, ajouter une seconde étape pour un destinataire standard (non groupé) — par exemple un approbateur interne qui doit signer chaque enveloppe individuelle générée à partir des destinataires groupés. Comme cette étape n'est pas marquée comme groupée, le même destinataire est reporté dans chacune des enveloppes individuelles créées pour les destinataires de l'étape groupée, et doit signer sur chacune d'entre elles.
POST /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/stages{
"name": "Standard Stage",
"requiredRecipientCompletions": 1,
"type": "Signer",
"mode": "Standard"
}Réponse 201 Created
{
"id": "6d3e9a17-1234-1234-1234-8e1b4f7c2a93"
}Sauvegarder le champ id retourné — il s'agit du standardStageId.
Ajouter maintenant l'unique destinataire de cette étape :
POST /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/stages/{standardStageId}/recipients{
"languageCode": "en",
"givenName": "Joe",
"surname": "Public",
"email": "joe.public@example.com"
}Réponse 201 Created
{
"id": "7a1c4e58-1234-1234-1234-1d5b9c3f7e28"
}Sauvegarder le champ id retourné — il s'agit du standardRecipientId.
Ajouter les champs qui doivent apparaître sur le document pour chaque étape. Cet appel remplace intégralement toutes les tâches du fichier ; envoyer donc la liste complète à chaque fois.
Un champ peut être rattaché à une étape entière (stageId) ou à un destinataire spécifique (recipientId) :
- Utiliser
stageIdpour l'étape groupée — le même champ est appliqué à chaque destinataire ajouté à cette étape, chacun sur sa propre copie du document. - Utiliser
recipientIdpour l'étape standard — le champ est rattaché à ce destinataire spécifique, qui le signe sur chaque enveloppe individuelle générée à partir de l'étape groupée.
PUT /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/files/{fileId}/tasks{
"tasks": [
{
"field": {
"fieldType": "Signature",
"id": "signature1",
"page": 1,
"positionX": 100,
"positionY": 200,
"width": 200,
"height": 50,
"required": true,
"allowedSignatureTypes": [
{ "signatureType": "ClickToSignSignature" }
]
},
"stageId": "9f534128-1234-1234-1234-ddd212a60d68",
"sortOrder": 1
},
{
"field": {
"fieldType": "Signature",
"id": "signature2",
"page": 1,
"positionX": 100,
"positionY": 300,
"width": 200,
"height": 50,
"required": true,
"allowedSignatureTypes": [
{ "signatureType": "ClickToSignSignature" }
]
},
"recipientId": "7a1c4e58-1234-1234-1234-1d5b9c3f7e28",
"sortOrder": 1
}
]
}Quelques points à noter :
stageIdsur une tâche appartenant à une étape groupée signifie que le champ est généré sur chaque copie individuelle créée pour les destinataires de cette étape — il n'est pas nécessaire de répéter la tâche pour chaque destinataire groupé.recipientIdsur une tâche rattache le champ à un destinataire spécifique, généralement utilisé pour les étapes standard, non groupées.positionX/positionYsont les coordonnées du coin supérieur gauche du champ sur la page.allowedSignatureTypescontrôle les méthodes de signature que le destinataire peut choisir. Si la valeur estnull, les paramètres par défaut de l'organisation s'appliquent.sortOrderdéfinit l'ordre dans lequel les champs sont présentés au signataire.
Réponse 204 No Content
Une fois tout configuré, envoyer l'enveloppe groupée. Cette action génère une enveloppe individuelle par destinataire groupé, fait passer chacune de draft à sent, et déclenche les e-mails d'invitation.
POST /api/v1/organizations/{organizationId}/bulk-envelopes/{bulkEnvelopeId}/sendAucun corps de requête requis.
Réponse 200 OK
{
"id": "b7e2a9c0-1234-1234-1234-1c7e5f8a3d21"
}