Passer au contenu

Créer un modèle et envoyer une enveloppe à partir de celui-ci

Les modèles permettent de définir un flux de signature réutilisable — document, étapes, destinataires et placement des champs — puis de créer des enveloppes à la demande. Ce guide décrit la configuration complète d'un modèle et explique comment créer une enveloppe à partir de celui-ci.

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é

Partie 1 — Créer le modèle

Étape 1 — Créer un modèle

Créer le conteneur du modèle. Lui donner un nom pour pouvoir l'identifier ultérieurement. Il est également possible de définir optionnellement une expiration.

POST /api/v1/organizations/{organizationId}/templates
{
  "name": "Standard Lease Agreement",
  "expiration": {
    "expiresAt": "2026-04-25T09:16:24.350Z",
    "mode": "absolute"
  }
}

Réponse 201 Created

{
  "id": "f7e6d5c4-1234-1234-1234-ba9876543210"
}

Sauvegarder le champ id retourné — il s'agit du templateId pour tous les appels suivants de cette section.

Étape 2 — Téléverser un document dans le modèle

Joindre le PDF que les signataires recevront. Cet endpoint utilise multipart/form-data, et non JSON.

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

Réponse 201 Created

{
  "id": "9c8b7a69-1234-1234-1234-987654321000"
}

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


Étape 3 — Ajouter une étape de signature au modèle

Une étape représente une phase du flux de travail. Les destinataires dans la même étape signent en parallèle ; les étapes s'exécutent dans l'ordre.

POST /api/v1/organizations/{organizationId}/templates/{templateId}/stages
{
  "name": "First",
  "requiredRecipientCompletions": 1,
  "type": "signer"
}

Réponse 201 Created

{
  "id": "b2a1f0e9-1234-1234-1234-726150403020"
}

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


Étape 4 — Ajouter un destinataire à l'étape

Ajouter un destinataire à l'étape. Dans un modèle, le destinataire représente généralement un rôle — les coordonnées réelles peuvent être remplacées lors de la création d'une enveloppe à partir du modèle.

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

Réponse 201 Created

{
  "id": "1a2b3c4d-1234-1234-1234-ef0123456789"
}

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

Définir l'emplacement de la signature et l'assigner au destinataire. Cet appel remplace intégralement toutes les tâches du fichier ; envoyer donc la liste complète à chaque fois.

PUT /api/v1/organizations/{organizationId}/templates/{templateId}/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": "1a2b3c4d-1234-1234-1234-ef0123456789",
      "sortOrder": 1
    }
  ]
}
  • 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

Le modèle est maintenant entièrement configuré.


Partie 2 — Créer une enveloppe à partir du modèle

Étape 6 — Créer une enveloppe

Instancier une nouvelle enveloppe à partir du modèle en un seul appel. Le document, les étapes, les destinataires et le placement des champs du modèle sont tous copiés automatiquement dans la nouvelle enveloppe. Aucun corps de requête n'est requis.

POST /api/v1/organizations/{organizationId}/templates/{templateId}/create-envelope

Réponse 200 OK

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

Le createdEnvelopeId retourné est un identifiant d'enveloppe standard. À partir de ce point, travailler avec l'enveloppe exactement comme avec n'importe quelle autre — il est possible de la modifier avant l'envoi ou de l'envoyer immédiatement.


Étape 7 — Envoyer l'enveloppe

Faire passer l'enveloppe de draft à sent. Cette action déclenche l'e-mail d'invitation au destinataire.

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

Aucun corps de requête requis. Utiliser createdEnvelopeId comme envelopeId.

Réponse 200 OK

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

Étape 8 — 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": "Standard Lease Agreement",
  "status": "completed",
  "sentAt": "2026-04-20T10:05:00Z"
  ...
}

Étape 9 — 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 artefacts disponibles :

GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/artifacts
{
  "artifacts": [
    {
      "id": "0a9e87c0-1234-1234-1234-99c8c87a9a33",
      "name": "LeaseAgreement_signed.pdf",
      "type": "CompletedFile"
    },
    {
      "id": "1b8f76b1-1234-1234-1234-aada9b8bab44",
      "name": "AuditTrail.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).