Passer au contenu

Catégorie de documents et flux d'enveloppe

Ce guide décrit le flux complet pour classifier un document à l'aide d'une catégorie de documents et envoyer une enveloppe via l'API d'intégration NSE. À la fin, vous aurez créé une catégorie de documents, créé une enveloppe, téléversé un fichier, classifié ce fichier avec des métadonnées, vérifié et appliqué les politiques associées, puis envoyé l'enveloppe.

Une catégorie de documents est utile lorsque des documents doivent être catégorisés (par exemple « Contrat » ou « Facture ») et automatiquement acheminés selon un flux de signature prédéfini, basé sur les politiques associées à cette catégorie.

Prérequis

  • Le feature flag DocumentClasses doit être activé pour l'organisation
  • 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 catégorie de documents

Une catégorie de documents regroupe les documents d'un même type (p. ex. « Contrat ») et leur associe un ensemble de champs de métadonnées typés. Une fois créée, elle peut être réutilisée dans plusieurs enveloppes et associée à des politiques.

Dans la requête suivante, une catégorie de documents est ajoutée avec une métadonnée de type String. Il est possible d'ajouter plusieurs champs de métadonnées à une catégorie de documents ; les types Number et Date sont également disponibles.

POST /api/v1/organizations/{organizationId}/document-classes
{
  "name": "Contracts",
  "description": "Document class for contracts",
  "metadata": [
    {
      "id": 1,
      "name": "Name",
      "type": "StringType",
      "required": true
    }
  ]
}

Réponse 201 Created

{
  "id": "d4e5f6a7-1234-1234-1234-1234567890ab"
}

Sauvegardez le champ id retourné — il s'agit de votre documentClassId, utilisé à l'étape 4.


Étape 2 — Créer une enveloppe

Pour une configuration simple, il suffit de créer une enveloppe avec un nom et une date d'expiration.

POST /api/v1/organizations/{organizationId}/envelopes
{
  "name": "Name",
  "expiration": {
    "expiresAt": "2026-05-30T18:30:00.000Z",
    "mode": "absolute"
  }
}

Réponse 201 Created

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

Sauvegardez le champ id retourné — il s'agit de votre envelopeId pour toutes les étapes suivantes.


Étape 3 — Téléverser un fichier

Téléversez un PDF (ou un autre format pris en charge) dans l'enveloppe. Ce point de terminaison utilise multipart/form-data, et non JSON.

POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/files
Content-Type: multipart/form-data
ChampTypeRequisDescription
filebinaryOuiLe fichier document
documentClassIdstring (UUID)NonOptionnel — assigner la catégorie de documents au moment du téléversement

Exemple curl :

curl -X POST \
  "https://demo-eu-ie1-api.namirialsign.com/api/organizations/{organizationId}/envelopes/{envelopeId}/files" \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/document.pdf"

Réponse 201 Created

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

Sauvegardez le champ id retourné — il s'agit de votre fileId, utilisé dans les étapes suivantes.


Étape 4 — Ajouter la catégorie de documents avec les métadonnées au fichier

Associez la catégorie de documents créée à l'étape 1 au fichier téléversé, et renseignez les valeurs pour chaque champ de métadonnées.

PUT /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/files/{fileId}
{
  "documentClass": {
    "id": "6a1231231231233f5",
    "metadata": [
      {
        "type": "StringType",
        "value": "TEST",
        "id": 1
      }
    ]
  }
}

Réponse 204 No Content

Après cette étape, le fichier est classifié et ses métadonnées sont enregistrées. Le système peut désormais évaluer quelles politiques s'appliquent en fonction de la catégorie de documents.


Étape 5 — Vérifier les politiques

Avant d'appliquer la politique, appelez le point de terminaison verify pour vérifier si l'enveloppe et ses documents classifiés satisfont déjà les exigences des politiques associées. Aucune modification n'est apportée à l'enveloppe.

POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/verify-policies
{}

Réponse 200 OK

{
  "compliant": false
}

Étape 6 — Appliquer les politiques

Appelez apply-policies pour remplir l'enveloppe avec le flux de travail défini par les politiques associées. Cette action ajoute automatiquement les destinataires configurés dans la politique.

POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/apply-policies
{}

Réponse 204 No Content

Après cet appel, le flux de signature de l'enveloppe est entièrement configuré par la politique. Les destinataires et les étapes sont désormais présents dans l'enveloppe — vérifiez cela en appelant à nouveau le point de terminaison verify (étape 7).


Étape 7 — Vérifier de nouveau les politiques

Réexécutez l'appel verify après avoir appliqué la politique pour confirmer que l'enveloppe est complète et cohérente.

POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/verify-policies
{}

Réponse 200 OK

{
  "compliant": true
}

Si compliant est true, les conditions configurées pour les politiques sont satisfaites.


Étape 8 — Envoyer l'enveloppe

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

Aucun corps de requête requis.

Réponse 200 OK

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

Les destinataires recevront désormais des notifications par e-mail avec des liens vers leurs tâches de signature.


Pour la documentation de référence expliquant l'interface de cette rubrique, voir :