Passer au contenu

Envoyer votre première enveloppe

Ce guide décrit étape par étape l'envoi d'une demande de signature via l'API NSE v1. À la fin, une enveloppe aura été créée, un document téléversé, un signataire ajouté, un champ de signature placé et l'enveloppe envoyée — le tout via l'API.

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

Commencer par créer une enveloppe. Il s'agit du conteneur pour les documents et les destinataires. Elle est créée en statut draft et reste modifiable jusqu'à l'envoi.

Dans la plupart des intégrations, il suffit au minimum de lui donner un nom et de définir une expiration. Ici, une expiration relative est utilisée — 14 jours après l'envoi (exprimée en secondes).

POST /api/v1/organizations/{organizationId}/envelopes
{
  "name": "Lease Agreement",
  "expiration": {
    "mode": "relative",
    "afterSendInSeconds": 1209600
  }
}

Réponse 201 Created

{
  "id": "a1b2c3d4-1234-1234-1234-ef1234567890"
}

Sauvegarder le champ id retourné — il s'agit de l'envelopeId pour tous les appels suivants.


Étape 2 — Téléverser un document

Téléverser le PDF que le destinataire devra signer. Cet endpoint utilise multipart/form-data, et non JSON.

Remarque : La taille maximale d'un fichier est de 10 Mo et une enveloppe peut contenir au maximum 10 documents.

POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/files
Content-Type: multipart/form-data
ChampTypeDescription
filebinaryLe fichier PDF à joindre

Réponse 201 Created

{
  "id": "3fa85f64-1234-1234-1234-2c963f66afa6"
}

Sauvegarder le champ id retourné — il s'agit du fileId, utilisé lors du placement du champ de signature.


Étape 3 — Ajouter une étape de signature

Une étape représente une phase du flux de signature. Les destinataires dans la même étape signent en parallèle ; les étapes s'exécutent dans l'ordre. Pour cet exemple, une étape avec un seul signataire est suffisante.

POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/stages
{
  "name": "Signers",
  "requiredRecipientCompletions": 1,
  "type": "signer"
}

Réponse 201 Created

{
  "id": "5c367bac-1234-1234-1234-08f3025e28ab"
}

Sauvegarder le champ id retourné — il s'agit du stageId.


Étape 4 — Ajouter un destinataire

Ajouter la personne qui signera le document à l'étape créée précédemment.

POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/stages/{stageId}/recipients
{
  "givenName": "John",
  "surname": "Doe",
  "email": "john.doe@example.com",
  "notificationChannels": [
    "email"
  ]
}

Réponse 201 Created

{
  "id": "4e861e0f-1234-1234-1234-58bd9928b4a8"
}

Sauvegarder le champ id retourné — il s'agit du recipientId, utilisé lors du placement du champ de signature.


Étape 5 — Placer un champ de signature

Ajouter tous les champs qui doivent apparaître sur le document et indiquer qui doit les signer. Cet appel remplace intégralement toutes les tâches du fichier ; envoyer donc la liste complète à chaque fois.

Chaque tâche encapsule une définition de field avec le recipientId et un sortOrder.

PUT /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/files/{fileId}/tasks
{
  "tasks": [
    {
      "field": {
        "fieldType": "Signature",
        "id": "field-001",
        "page": 1,
        "positionX": 100,
        "positionY": 650,
        "width": 200,
        "height": 60,
        "allowedSignatureTypes": [
          { "signatureType": "ClickToSignSignature" },
          { "signatureType": "DrawToSignSignature" }
        ]
      },
      "recipientId": "4e861e0f-1234-1234-1234-58bd9928b4a8",
      "sortOrder": 1
    }
  ]
}

Quelques points à noter :

  • 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 6 — Envoyer l'enveloppe

Une fois tout configuré, envoyer l'enveloppe. Cette action fait passer l'enveloppe de draft à sent et déclenche l'e-mail d'invitation au destinataire.

POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/send

Aucun corps de requête requis.

Réponse 204 No Content


Étape 7 — Vérifier le statut de l'enveloppe

Interroger cet endpoint pour suivre l'avancement.

GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}

Réponse 200 OK

{
  "id": "a1b2c3d4-1234-1234-1234-ef1234567890",
  "name": "Lease Agreement",
  "status": "completed",
  "sentAt": "2026-04-20T10:05:00Z"
  ...
}

Étape 8 — Télécharger le document signé

Une fois l'enveloppe en statut completed, récupérer le fichier signé et la piste d'audit.

Lister les éléments disponibles :

GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/artifacts
{
  "artifacts": [
    {
      "id": "0a9e87c0-1234-1234-1234-99c8c87a9a33",
      "name": "LeaseAgreement.pdf",
      "type": "CompletedFile"
    },
    {
      "id": "1b8f76b1-1234-1234-1234-aada9b8bab44",
      "name": "Audit Trail.pdf",
      "type": "AuditTrail"
    }
  ]
}

Télécharger un artefact spécifique :

GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/artifacts/{artifactId}

Retourne le fichier sous forme de flux binaire (application/pdf).


Prochaines étapes

Ce guide couvre le flux essentiel. La référence API complète décrit les options supplémentaires disponibles à chaque étape, notamment :

  • Enveloppe : rappels automatiques, dates d'expiration absolues
  • Étapes : signature en parallèle, étapes d'approbation uniquement (Approver), copie carbone (CarbonCopy)
  • Destinataires : authentification SMS/OTP, codes d'accès, configuration de certificat QES
  • Champs : zones de texte, cases à cocher, listes déroulantes, confirmations de lecture, et plus encore