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.
- 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 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.
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| Champ | Type | Description |
|---|---|---|
file | binary | Le 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.
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.
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.
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/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. 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}/sendAucun corps de requête requis.
Réponse 204 No Content
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"
...
}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).
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