Passer au contenu

Envoyer une enveloppe groupée

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.

Prérequis

  • 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é

Étape 1 — Créer une enveloppe groupée

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.


Étape 2 — Téléverser un document

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
ChampTypeDescription
filebinaryLe 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.


Étape 3 — Ajouter l'étape de signature groupée

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.


Étape 4 — Ajouter les destinataires groupés

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}/recipients

Destinataire 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"
}

Étape 5 — Ajouter l'étape standard (facultatif)

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.


Étape 6 — Placer les champs de signature (facultatif)

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 stageId pour l'étape groupée — le même champ est appliqué à chaque destinataire ajouté à cette étape, chacun sur sa propre copie du document.
  • Utiliser recipientId pour 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 :

  • stageId sur 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é.
  • recipientId sur une tâche rattache le champ à un destinataire spécifique, généralement utilisé pour les étapes standard, non groupées.
  • positionX / positionY sont les coordonnées du coin supérieur gauche du champ sur la page.
  • allowedSignatureTypes contrôle les méthodes de signature que le destinataire peut choisir. Si la valeur est null, les paramètres par défaut de l'organisation s'appliquent.
  • sortOrder définit l'ordre dans lequel les champs sont présentés au signataire.

Réponse 204 No Content


Étape 7 — Envoyer l'enveloppe groupée

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}/send

Aucun corps de requête requis.

Réponse 200 OK

{
  "id": "b7e2a9c0-1234-1234-1234-1c7e5f8a3d21"
}