Passer au contenu

Guide des flux de travail

Ce guide explique la structure de l'API NSE et comment combiner ses composants pour modéliser un large éventail de scénarios de signature réels. Plutôt que de décrire des appels API individuels, il se concentre sur les concepts sous-jacents à l'API et les différents flux de travail qu'il est possible de construire.


Les composants de base

Chaque flux de signature dans NSE est construit à partir de quatre objets imbriqués :

Enveloppe
  └── Étape 1
  │     ├── Destinataire A
  │     └── Destinataire B
  └── Étape 2
        └── Destinataire C
  └── Fichier (Document)
        └── Tâches de champs  (liées à des destinataires spécifiques)

Enveloppe — le conteneur de niveau supérieur. Il contient tout : documents, étapes et leurs destinataires. Une enveloppe suit un cycle de vie (draft → sent → completed) et constitue l'objet que l'on suit et télécharge.

Étape — une phase du flux de signature. Les étapes s'exécutent séquentiellement : l'étape 2 ne démarre pas tant que l'étape 1 n'est pas entièrement terminée. Dans une même étape, tous les destinataires assignés sont notifiés et agissent en parallèle.

Destinataire — une personne assignée à une étape. Elle reçoit une invitation (par e-mail, SMS ou WhatsApp), ouvre le document et effectue l'action requise par son étape.

Fichier et tâches de champs — documents joints à l'enveloppe avec des champs interactifs (signatures, cases à cocher, champs de texte) positionnés sur des pages spécifiques. Chaque champ est lié à un destinataire spécifique, de sorte que chaque personne ne voit et n'interagit qu'avec les champs qui lui sont assignés.


Documents

Une enveloppe peut contenir un ou plusieurs documents. Chaque document est téléversé sous forme de fichier PDF séparé dans l'enveloppe via une requête multipart/form-data.

Téléversement de fichiers

Le téléversement d'un fichier ne le rend pas encore interactif — il l'attache simplement à l'enveloppe et retourne un fileId. Les éléments interactifs sont ajoutés séparément via les tâches de champs.

Dans un flux multi-documents, les destinataires peuvent avoir des champs sur certains documents mais pas sur d'autres, et le même document peut avoir des champs assignés à différents destinataires.

Les étapes en détail

Les étapes constituent le mécanisme principal pour contrôler le flux et l'ordre d'un processus de signature.

Exécution séquentielle

Les étapes sont numérotées et s'exécutent dans l'ordre de leur création. La deuxième étape n'est pas déclenchée tant que chaque action requise dans la première étape n'est pas terminée. Cela permet de modéliser facilement des chaînes d'approbation, des contre-signatures et d'autres processus en plusieurs étapes.

Types d'étapes

Chaque étape possède un type qui définit ce que les destinataires de cette étape sont censés faire :

TypeAction des destinataires
SignerSigner ou interagir avec les champs de signature du document
ApproverApprouver ou rejeter l'enveloppe avant qu'elle ne passe à l'étape suivante
CarbonCopyRecevoir une copie de l'enveloppe à titre d'information — aucune action requise
ViewerConsulter le document — aucune action requise
AutomaticÉtape pilotée par le système sans destinataire humain

Une enveloppe commence généralement par une ou plusieurs étapes Signer, mais toute combinaison dans n'importe quel ordre est possible. Un schéma courant consiste à placer une étape Approver avant une étape Signer, de sorte qu'un responsable interne examine le document avant qu'il ne soit envoyé au signataire externe.

Contrôler le nombre de destinataires devant finaliser une étape

Par défaut, tous les destinataires d'une étape doivent finaliser leur action avant que l'étape n'avance. Cela peut être modifié avec requiredRecipientCompletions.

Ce champ accepte un entier — le nombre minimum de destinataires devant finaliser l'étape pour qu'elle soit considérée comme terminée. Si une étape compte trois destinataires mais que requiredRecipientCompletions est défini à 1, l'étape se termine dès que l'un d'eux signe. Cela est utile pour des scénarios tels que :

  • Signature en comité : envoyer à cinq membres du conseil d'administration, en requérir deux pour signer.
  • Pools de signataires autorisés : envoyer à trois signataires autorisés, l'un quelconque pouvant signer au nom du groupe. Si requiredRecipientCompletions n'est pas défini, sa valeur par défaut correspond au nombre total de destinataires de l'étape (tous doivent finaliser).

Configuration des destinataires

Chaque destinataire est configuré au niveau de l'étape, avant que les documents ou les champs ne soient définis. L'enregistrement du destinataire contrôle l'identité, la communication, la sécurité d'accès et — si nécessaire — les données de préconfiguration requises pour les signatures basées sur des certificats.

Identité et coordonnées

Un destinataire est identifié par son prénom, son nom de famille, son adresse e-mail et, optionnellement, un numéro de téléphone. Le numéro de téléphone est requis lors de l'utilisation d'une authentification par SMS ou d'une signature OTP.

Canaux de notification

Il est possible de contrôler la manière dont le destinataire reçoit son invitation et les rappels via notificationChannels. Les options disponibles sont Email, Sms et WhatsApp.

Langue

Le champ languageCode définit la langue utilisée pour tous les e-mails, SMS et éléments d'interface affichés à ce destinataire. Utile lorsque le flux implique des destinataires dans différents pays.

Authentification

L'authentification ajoute une vérification d'identité que le destinataire doit effectuer avant d'accéder au document. Trois mécanismes sont disponibles et peuvent être combinés :

  • Code d'accès — un secret statique défini à l'avance. Le destinataire doit saisir le code correct pour ouvrir l'enveloppe. Ce code est partagé avec lui via un canal séparé.
  • OTP par SMS — un mot de passe à usage unique envoyé sur un numéro de téléphone au moment où le destinataire tente d'ouvrir le document. Le numéro de téléphone est spécifié lors de la configuration du destinataire.
  • OAuth — le destinataire s'authentifie via un fournisseur d'identité externe. Le nom du fournisseur et l'identifiant externe du destinataire sont fournis pour lier les comptes.

Configuration de signature

La configuration de signature du destinataire n'est nécessaire que pour les méthodes de signature requérant des données préprovisionées — spécifiquement :

  • Certificat jetable — un certificat qualifié à usage unique émis au moment de la signature. Les détails du document d'identification du destinataire (type, numéro, pays émetteur, expiration, etc.) ainsi qu'un numéro de téléphone de vérification sont fournis. La plateforme les utilise pour émettre le certificat lors de la session de signature.
  • Certificat distant — le destinataire signe à l'aide d'un certificat stocké dans un service de signature distant. L'identifiant utilisateur et l'identifiant d'appareil permettant d'identifier son certificat dans ce service sont fournis.
  • Signature OTP — un mot de passe à usage unique par SMS qui constitue la signature elle-même (à ne pas confondre avec l'OTP utilisé comme méthode d'authentification d'accès). Le numéro de téléphone auquel l'OTP est envoyé au moment de la signature est fourni.
  • Plugins de signature — intégrations de signature tierces. L'identifiant du plugin et les éventuels paramètres clé/valeur qu'il requiert sont spécifiés. Pour toutes les autres méthodes de signature — clic pour signer, dessin pour signer, saisie pour signer, biométrique, certificat local — aucune préconfiguration n'est nécessaire sur le destinataire. Les méthodes autorisées sont en revanche contrôlées par allowedSignatureTypes sur le champ de signature lui-même, défini lors du placement du champ sur le document.

Message personnel

Un message en texte libre affiché au destinataire en complément de l'invitation standard. Il peut être utilisé pour fournir un contexte — par exemple, expliquer quel document est à signer ou donner des instructions spécifiques à cette enveloppe.


Scénarios de flux de travail

Les scénarios suivants illustrent comment les étapes et les destinataires se combinent pour gérer des cas réels courants.


Scénario 1 — Signataire unique

Le flux le plus simple : un document, une personne à signer.

Étape 1 (Signer)
  └── Alice

Alice reçoit une invitation, ouvre le document, appose sa signature et l'enveloppe est finalisée.


Scénario 2 — Deux signataires en séquence

Les deux parties doivent signer et l'ordre est important. Le contrat est d'abord envoyé à la première partie ; ce n'est qu'après sa signature que la deuxième partie reçoit son invitation.

Étape 1 (Signer)   →   Étape 2 (Signer)
  └── Alice                └── Bob

Ce schéma est courant pour les contrats bilatéraux où une partie initie et l'autre contre-signe.


Scénario 3 — Plusieurs signataires en parallèle

Deux personnes ou plus doivent signer, mais l'ordre n'a pas d'importance. Elles reçoivent toutes leur invitation en même temps et peuvent signer de manière indépendante.

Étape 1 (Signer)
  ├── Alice
  └── Bob

Alice et Bob reçoivent leur invitation simultanément. L'enveloppe ne se finalise pas tant que les deux n'ont pas signé (requiredRecipientCompletions = 2, ce qui correspond également à la valeur par défaut lorsque deux destinataires sont présents).


Scénario 4 — Signature de groupe (N sur M)

Trois signataires autorisés figurent sur la liste, mais l'un quelconque d'entre eux suffit pour exécuter l'accord.

Étape 1 (Signer) — requiredRecipientCompletions : 1
  ├── Alice
  ├── Bob
  └── Carol

Les trois reçoivent l'invitation en même temps. L'enveloppe avance dès que l'un d'eux signe. Les deux autres ne sont plus tenus d'agir.

Ce schéma est également utilisé pour les scénarios de vote à la majorité — par exemple, requérir 3 membres du conseil d'administration sur 5 pour signer.


Scénario 5 — Approbation interne avant signature externe

Un document doit être approuvé par un responsable interne avant d'être envoyé au client pour signature.

Étape 1 (Approver)   →   Étape 2 (Signer)
  └── Responsable interne    └── Client

Le responsable reçoit le document en premier et l'approuve ou le rejette. En cas d'approbation, l'étape 2 est déclenchée et le client reçoit son invitation de signature. En cas de rejet, l'enveloppe s'arrête et l'expéditeur est notifié.


Scénario 6 — Signature suivie d'une notification en copie carbone

Une fois toutes les parties ayant signé, un tiers (tel qu'un service juridique ou un système d'archivage) doit recevoir automatiquement une copie du document finalisé.

Étape 1 (Signer)   →   Étape 2 (CarbonCopy)
  ├── Alice                └── Service juridique
  └── Bob

Le destinataire de l'étape CarbonCopy n'effectue aucune action — il reçoit simplement l'enveloppe en notification une fois les étapes précédentes terminées. C'est un moyen efficace de s'assurer que les bonnes personnes sont informées sans leur demander de se connecter ou d'interagir avec le document.


Scénario 7 — Multi-étapes avec types mixtes

Un flux complexe combinant approbation, signature en parallèle et notification :

Étape 1 (Approver)   →   Étape 2 (Signer)        →   Étape 3 (CarbonCopy)
  └── Juriste               ├── Partie A                  └── Système d'archivage
                            └── Partie B

Le juriste approuve d'abord le document. Les deux parties reçoivent ensuite leurs invitations simultanément et doivent toutes deux signer. Après cela, le système d'archivage reçoit automatiquement le document finalisé.


Tâches de champs

Les tâches de champs constituent le lien entre une position dans un document et un destinataire. Une tâche définit :

  • Le type d'interaction attendu (une signature, une case à cocher, une saisie de texte, etc.)
  • L'emplacement dans le document où le champ apparaît (la page, et les coordonnées x/y du coin supérieur gauche du champ, exprimées en unités de page PDF)
  • La taille du champ (largeur et hauteur)
  • Le responsable de son remplissage (le recipientId)
  • L'ordre dans lequel les champs sont présentés au signataire (sortOrder) Les tâches de champs sont définies par fichier via une requête PUT. Cet appel est un remplacement complet — il définit la liste complète des tâches pour ce document. Si cet appel est effectué une deuxième fois avec une liste modifiée, les tâches précédentes sont entièrement supprimées et la nouvelle liste prend effet.

Types de champs

La propriété fieldType d'une tâche de champ détermine ce que le destinataire voit et ce qu'il est censé faire :

Type de champDescription
SignatureLe destinataire appose une signature. Les méthodes de signature autorisées sont contrôlées par allowedSignatureTypes sur le champ lui-même.
TextInputLe destinataire saisit du texte (des formats spécifiques, p. ex. date ou nombre, peuvent être définis par l'expéditeur).
CheckboxLe destinataire coche ou décoche une case.
RadiobuttonLe destinataire sélectionne l'un des boutons radio proposés.
DropDownLe destinataire sélectionne une valeur dans une liste déroulante prédéfinie.
ListBoxLe destinataire sélectionne une ou plusieurs valeurs dans une liste visible.
AttachmentLe destinataire téléverse un fichier dans le cadre de sa réponse.
AreaReadConfirmationLe destinataire doit explicitement confirmer avoir lu une zone spécifique d'une page.
PageReadConfirmationLe destinataire doit confirmer avoir lu une page entière avant de continuer.
FileReadConfirmationLe destinataire doit confirmer avoir lu l'intégralité du document.
LinkAffiche un lien cliquable dans le document, pointant généralement vers une ressource externe que le destinataire doit consulter.
ApprovalLe destinataire approuve en cliquant sur le champ (mécanisme similaire à la signature ClickToSign).

Champ de signature et méthodes de signature autorisées

Pour les champs Signature spécifiquement, il est possible de restreindre les méthodes de signature disponibles pour le destinataire en définissant allowedSignatureTypes sur le champ. Si ce paramètre est vide ou null, la configuration par défaut de l'organisation s'applique.

Les types de signature disponibles sont :

Type de signatureDescription
ClickToSignSignatureLe destinataire clique sur un bouton pour confirmer sa signature — aucun dessin ni certificat requis.
DrawToSignSignatureLe destinataire dessine sa signature avec une souris ou un écran tactile.
TypeToSignSignatureLe destinataire saisit son nom qui est rendu sous forme de signature.
BiometricSignatureCapture les données biométriques (pression, vitesse, rythme) lors du geste de signature.
LocalCertificateSignatureLe destinataire signe à l'aide d'un certificat stocké sur son appareil local (p. ex. une carte à puce ou un token USB).
DisposableCertificateSignatureUn certificat qualifié à usage unique est émis au moment de la signature. Nécessite une préconfiguration sur le destinataire.
RemoteCertificateSignatureLe destinataire signe à l'aide d'un certificat stocké dans un service de signature distant. Nécessite une préconfiguration sur le destinataire.
OneTimePasswordSignatureUn OTP envoyé par SMS constitue la signature. Nécessite une préconfiguration sur le destinataire.
AutomaticSignatureLa signature est effectuée sans aucune intervention humaine.
PluginSignatureLa signature est gérée par une intégration de plugin tierce. Nécessite une configuration de plugin sur le destinataire.

Ceci est distinct de la signatureConfiguration sur le destinataire. Le paramètre allowedSignatureTypes du champ contrôle les méthodes proposées dans l'interface. La signatureConfiguration du destinataire fournit les données préprovisionées requises par les méthodes qui en ont besoin (certificat jetable, certificat distant, signature OTP, plugins de signature). Pour toutes les autres méthodes, la configuration du champ seule est suffisante — aucune donnée supplémentaire ne doit être définie sur le destinataire.

Annotations

Les annotations suivantes peuvent être ajoutées :

  • Text
    • Définit un texte visible par le destinataire sur le document
  • Date
    • Ajoute la date au document
  • FullName
    • Ajoute le nom complet du destinataire au document
  • FirstName
    • Ajoute le prénom du destinataire au document
  • LastName
    • Ajoute le nom de famille du destinataire au document
  • Initials
    • Ajoute les initiales du destinataire au document
  • Email
    • Ajoute l'adresse e-mail du destinataire au document

Positionnement des champs

La position et la taille des champs sont définies en unités de coordonnées de page PDF :

  • positionX et positionY sont les coordonnées du coin supérieur gauche du champ sur la page
  • width et height définissent la taille du champ
  • page spécifie la page du document sur laquelle le champ apparaît (indexation à partir de 1)

Assigner plusieurs champs au même destinataire

Un même destinataire peut avoir plusieurs tâches de champs sur un ou plusieurs documents. La propriété sortOrder contrôle l'ordre dans lequel les champs lui sont présentés lors de sa session de signature. Les champs avec un ordre de tri inférieur sont affichés en premier. Cela permet de guider le signataire à travers un document dans un ordre logique, indépendamment de la position physique des champs sur la page.


Le cycle de vie de l'enveloppe

Une fois envoyée, une enveloppe suit un ensemble d'états définis :

draft → sent → completed
                ↘ rejected
                ↘ expired
                ↘ cancelled
StatutSignification
draftL'enveloppe a été créée mais pas encore envoyée. Elle peut encore être modifiée.
sentLes destinataires ont été notifiés et le flux de travail est actif.
completedToutes les étapes requises ont été finalisées avec succès.
rejectedUn destinataire a rejeté le document.
expiredLa date limite a été dépassée avant la finalisation du flux de travail.
cancelledL'expéditeur a arrêté manuellement le processus.

Une fois qu'une enveloppe atteint un état terminal (completed, rejected, expired, cancelled), elle ne peut plus être modifiée ni avancée. Les documents signés et la piste d'audit deviennent disponibles au téléchargement depuis l'endpoint des artefacts.


Utilisation des modèles pour les flux récurrents

Si la même structure de document est envoyée régulièrement — les mêmes étapes, le même positionnement des champs, le même ordre de signature — tout cela peut être défini une fois comme modèle. Lorsqu'une nouvelle enveloppe est nécessaire, elle est créée à partir du modèle en un seul appel API. L'enveloppe résultante est une copie indépendante et peut être modifiée avant l'envoi si nécessaire.

Les modèles sont particulièrement utiles lorsque :

  • Le document change à chaque fois, mais la structure du flux reste toujours la même.
  • De nombreuses enveloppes doivent être créées de manière programmée en masse.
  • Un processus de signature standard doit être imposé à l'ensemble de l'organisation.

Principes de conception clés

Quelques points à garder à l'esprit lors de la conception de l'intégration :

Tout est limité à l'organisation. Tous les appels API incluent l'organizationId dans le chemin. Il s'agit de l'identifiant du locataire qui détermine la configuration, les modèles et les enveloppes finalisées accessibles.

Les champs sont assignés aux destinataires, pas aux étapes. Le placement d'un champ de signature nécessite le recipientId spécifique. Cela signifie que les étapes et les destinataires doivent être ajoutés en premier, puis les tâches de champs peuvent être placées.

L'appel d'envoi est le point de non-retour. Tant que l'endpoint d'envoi n'est pas appelé, l'enveloppe reste en état draft et peut être librement modifiée. Une fois envoyée, le flux de travail est actif et les destinataires sont notifiés.

La finalisation d'une étape déclenche automatiquement l'étape suivante. Il n'est pas nécessaire d'interroger l'API et d'avancer manuellement le flux de travail. Une fois qu'une étape atteint le nombre requis de finalisations, l'API déclenche l'étape suivante et envoie les invitations aux destinataires suivants.

Pour un flux d'enveloppe complet, voir le guide suivant : Flux d'enveloppe

Pour un flux de modèle complet, voir le guide suivant : Flux de modèle