L'API Namirial Sign Enterprise (v1) est une API RESTful qui permet de créer, gérer et suivre des workflows de signature électronique de manière programmatique. Vous pouvez l'utiliser pour intégrer NSE dans vos propres applications, automatiser l'envoi d'enveloppes ou créer des portails de signature personnalisés.
La spécification API interactive est disponible ci-dessous — utilisez-la pour explorer les points de terminaison, inspecter les schémas de requête et de réponse, et effectuer des appels directement.
Tous les points de terminaison de l'API sont relatifs à l'URL de base de votre instance NSE :
Par exemple
https://demo-eu-ie1-api.namirialsign.com/api/La plupart des points de terminaison incluent organizationId comme paramètre de chemin obligatoire (assurez-vous de le renseigner à chaque utilisation de l'API). Il s'agit de l'identifiant de l'organisation, dans votre instance NSE, propriétaire de la ressource concernée.
- Sémantique REST complète — utilise les verbes GET, POST, PUT, PATCH et DELETE selon les conventions REST standard.
- Ressources rattachées à une organisation — toutes les ressources, à l'exception des données de référence, sont rattachées à
/organizations/{organizationId}/. - Workflow basé sur des étapes — les workflows de signature sont modélisés sous forme d'étapes ordonnées. Les destinataires d'une même étape signent en parallèle ; les étapes sont traitées séquentiellement selon leur ordre de tri.
- Séparation de la structure et du contenu — les fichiers, étapes et destinataires sont gérés comme des sous-ressources indépendantes d'une enveloppe ou d'un modèle, permettant un contrôle précis de chaque partie du workflow.
- Artefacts pour les documents finalisés — une fois une enveloppe terminée, les documents signés et la piste d'audit sont accessibles sous forme d'artefacts.
L'authentification à l'API utilise OAuth 2.0 Client Credentials, avec MyNamirial comme fournisseur d'identité.
- Créez une application IdP (compte de service).
- Notez l'ID client et le secret client attribués à l'application.
Remarque : la création d'un IdP dans MyNamirial et la génération du ClientID et du ClientSecret peuvent être effectuées dans l'interface, dans la section des comptes de service. Pour plus d'informations, voir : Compte de service
Utilisez le flux Client Credentials pour obtenir un jeton Bearer JWT.
Il est également possible de créer un jeton d'accès personnel pour utiliser l'API. Pour plus d'informations, voir : Jeton d'accès. Ajoutez l'en-tête « Personal-Access-Token » avec le jeton obtenu comme valeur.
Incluez le jeton comme jeton Bearer dans l'en-tête Authorization de chaque requête API :
Authorization: Bearer <access_token>Les requêtes non authentifiées ou avec un jeton expiré renvoient 401 Unauthorized.
Une enveloppe représente une demande de signature unique. Elle contient un ou plusieurs documents (fichiers), un workflow de signature (étapes) et des options d'enveloppe telles que le nom, la date d'expiration et la configuration des rappels.
Cycle de vie d'une enveloppe :
| Statut | Description |
|---|---|
| Draft (Brouillon) | Créée mais pas encore envoyée. Toute la configuration peut être modifiée. |
| InProgress (En cours) | Envoyée aux destinataires. Le workflow de signature est en cours. |
| Completed (Terminée) | Tous les destinataires ont terminé leurs activités. Les artefacts sont disponibles au téléchargement. |
| Canceled (Annulée) | Annulée manuellement. Plus aucune activité n'est possible. |
| Expired (Expirée) | La date d'expiration a été atteinte avant la finalisation. Peut être reprise avec une nouvelle date. |
| Rejected (Rejetée) | L'enveloppe a été rejetée par un ou plusieurs destinataires. |
Un modèle est une configuration d'enveloppe réutilisable — préchargée avec des documents, des étapes, des destinataires et des emplacements de champs. Créer une enveloppe à partir d'un modèle copie l'intégralité de la configuration dans une nouvelle enveloppe au statut Brouillon, qui peut être personnalisée avant l'envoi.
Une étape représente une phase du workflow de signature. Chaque étape contient un ou plusieurs destinataires qui agissent en parallèle. Les étapes sont traitées séquentiellement par ordre croissant de sortOrder. Utilisez requiredRecipientCompletions pour permettre à une étape de progresser lorsqu'un nombre minimum de destinataires (sur le total) ont terminé leur activité — utile pour les scénarios de signature de groupe.
Un destinataire est une personne assignée à une étape. Chaque destinataire dispose de coordonnées (e-mail, nom, téléphone), d'un canal de notification (E-mail, SMS, WhatsApp ou Aucun), d'une préférence de langue, d'exigences d'authentification facultatives (code d'accès, OTP par SMS, OAuth) et d'une configuration de signature facultative (type de signature et données pré-remplies requises).
Un fichier est un document joint à une enveloppe ou un modèle. Les tâches sont les éléments interactifs assignés aux destinataires — champs de signature, saisies de texte, cases à cocher, listes déroulantes, demandes de pièces jointes et lectures de confirmation. La plupart des tâches sont positionnées sur une page précise d'un fichier, mais certaines (comme les lectures de confirmation) s'appliquent au niveau du fichier ou de la page, sans position fixe.
Une fois qu'une enveloppe atteint le statut Completed (Terminée), ses fichiers de sortie deviennent disponibles sous forme d'artefacts. Il existe deux types d'artefacts : CompletedFile (le document signé) et AuditTrail (le journal complet des événements au format PDF).
| Type | Description |
|---|---|
ClickToSignSignature | Signature simple par clic de confirmation — sans certificat cryptographique. |
DrawToSignSignature | Signature manuscrite dessinée, capturée dans le navigateur ou sur un appareil tactile. |
TypeToSignSignature | Signature créée en saisissant le nom du destinataire dans une police choisie. |
LocalCertificateSignature | Signature utilisant un certificat installé sur l'appareil local du destinataire. |
DisposableCertificateSignature | Signature utilisant un certificat qualifié à usage unique, généré au moment de la signature. |
BiometricSignature | Signature capturée via une tablette biométrique (pression et dynamique du stylet). |
RemoteCertificateSignature | Signature utilisant un certificat qualifié distant (nécessite userId et deviceId). |
OneTimePasswordSignature | Signature confirmée via un code OTP envoyé par SMS au numéro de téléphone du destinataire. |
AutomaticSignature | Signature appliquée sans aucune interaction nécessaire. |
PluginSignature | Signature déléguée à un plugin de signature personnalisé configuré sur l'instance. |
Toutes les réponses d'erreur suivent une structure cohérente :
{
"errors": [
{
"errorId": "string",
"field": "string",
"message": "string",
"messageEn": "string",
"additionalData": {}
}
]
}| Statut HTTP | Signification |
|---|---|
200 OK | La requête a réussi. |
201 Created | La ressource a été créée. L'ID de la nouvelle ressource est renvoyé dans le corps de la réponse. |
204 No Content | La requête a réussi sans corps de réponse (mise à jour ou suppression). |
400 Bad Request | La requête est invalide ou mal formée. |
401 Unauthorized | L'authentification est absente ou le jeton a expiré. |
403 Forbidden | L'utilisateur authentifié n'a pas les droits d'accès à cette ressource. |
404 Not Found | La ressource demandée n'existe pas. |
422 Unprocessable Entity | La requête est valide mais viole une règle métier. |
500 Internal Server Error | Une erreur inattendue s'est produite sur le serveur. |
Une intégration type pour l'envoi d'une demande de signature suit les étapes suivantes :
- Créer une enveloppe —
POST /organizations/{organizationId}/envelopes - Téléverser un document —
POST /organizations/{organizationId}/envelopes/{envelopeId}/files - Ajouter une étape de signature —
POST /organizations/{organizationId}/envelopes/{envelopeId}/stages - Ajouter un destinataire à l'étape —
POST /organizations/{organizationId}/envelopes/{envelopeId}/stages/{stageId}/recipients - Placer les tâches de champs sur le document —
PUT /organizations/{organizationId}/envelopes/{envelopeId}/files/{fileId}/tasks - Envoyer l'enveloppe —
POST /organizations/{organizationId}/envelopes/{envelopeId}/send - Vérifier l'enveloppe —
GET /organizations/{organizationId}/envelopes/{envelopeId} - Télécharger les artefacts —
GET /organizations/{organizationId}/envelopes/{envelopeId}/artifacts
Pour créer une enveloppe à partir d'un modèle, remplacez les étapes 1 à 5 par :
- Créer une enveloppe à partir d'un modèle —
POST /organizations/{organizationId}/templates/{templateId}/create-envelope - Mettez éventuellement à jour les destinataires ou les fichiers dans le brouillon, puis procédez à l'envoi.
La spécification API interactive complète est disponible sur l'interface Swagger UI de votre instance NSE. Contactez votre représentant Namirial pour obtenir l'URL correcte pour votre environnement.
Le Swagger UI de DÉMONSTRATION est disponible à cette URL : https://demo-eu-ie1-api.namirialsign.com/api/swagger/index.html