Archiver des documents dans un coffre Namirial Archive

Si l’option Namirial Archive est activée sur votre espace de travail, les documents de vos transactions terminées peuvent être envoyés automatiquement dans un coffre Namirial Archive.

Une configuration de coffre se compose :

  • de la connexion à votre coffre Namirial,
  • des champs du coffre (schema fields) : les types de document (typologies) et les métadonnées de votre coffre,
  • des règles de routage : les documents envoyés au coffre (conditions) et les valeurs qui les accompagnent (instructions).

Vous pouvez configurer votre coffre depuis l’application web (consultez Configurer l’archivage long terme) ou via l’API, comme décrit ci-dessous.

Prérequis

  • Vous authentifiez vos requêtes avec une clé API de votre espace de travail.
  • L’option Namirial Archive est activée sur votre espace de travail. Si vous souhaitez l’activer, contactez votre gestionnaire de compte chez Universign.
  • Votre coffre a été créé côté Namirial et vous avez reçu ses informations de connexion de la part de l’équipe support Namirial.
  • Vos types de document et les métadonnées qui leur sont associées ont été créés dans votre coffre.

1. Créer un coffre

Envoyez une requête à POST /v1/vaults et transmettez le provider (namirial) et le name du coffre. La description est optionnelle.

curl
https://api.universign.com/v1/vaults \
-d provider=namirial \
-d name="ACME Vault" \
-d description="Main archive vault"

L’API renvoie un objet vault. Conservez l’id du coffre pour les requêtes suivantes.

{
  "object" : "vault",
  "id" : "vlt_id",
  "name" : "ACME Vault",
  "provider" : "namirial",
  "description" : "Main archive vault",
  "deployed" : false,
  "needs_redeploy" : false,
  "created_at" : "2026-05-28T10:00:00Z",
  "schema_fields" : [ ],
  "rules" : [ ]
}

2. Définir la connexion Namirial

Envoyez une requête à POST /v1/vaults/{vault_id}/config/namirial et transmettez les informations de connexion fournies par l’équipe support Namirial :

  • username : l’identifiant client,
  • password : le secret client,
  • id_setup : l’ID de configuration,
  • id_company : l’ID de l’entreprise,
  • vat_id : le N° de TVA.
curl
https://api.universign.com/v1/vaults/vlt_id/config/namirial \
-d id_setup=setup-1 \
-d id_company=company-1 \
-d vat_id=FR-123 \
-d username=client-id \
-d password=s3cr3t

Les identifiants sont vérifiés auprès de Namirial avant d’être enregistrés. La requête est rejetée si Namirial refuse les identifiants ou ne peut pas être joint.

Notez que le mot de passe est stocké chiffré et n’est jamais renvoyé par l’API.

Un argument absent laisse le paramètre inchangé, un argument vide l’efface.

3. Déclarer les champs du coffre

Les champs du coffre décrivent les types de document et les métadonnées de votre coffre. Vous devez déclarer au moins un type de document.

Pour retrouver les références de votre coffre, vous pouvez lister :

  • les types de document de votre coffre : GET /v1/vaults/{vault_id}/config/namirial/document-types. L’id de chaque type de document est le provider_ref à utiliser,
  • les métadonnées d’un type de document : GET /v1/vaults/{vault_id}/config/namirial/document-types/{doc_type_id}/metadata. Le name de chaque métadonnée est le provider_ref à utiliser.

Ensuite, pour chaque champ, envoyez une requête à POST /v1/vaults/{vault_id}/schema-fields avec les arguments suivants :

  • name : le nom du champ dans Universign,
  • kind : document_type ou metadata,
  • required : true si une valeur doit toujours être envoyée au coffre pour ce champ (valeur par défaut : false),
  • provider_ref : l’identifiant du type de document, ou le nom de la métadonnée, tel que défini dans le coffre Namirial.
curl
https://api.universign.com/v1/vaults/vlt_id/schema-fields \
-d name=SignedDocument \
-d kind=document_type \
-d required=true \
-d provider_ref=461
curl
https://api.universign.com/v1/vaults/vlt_id/schema-fields \
-d name=document_number \
-d kind=metadata \
-d provider_ref="DOCUMENT NUMBER"

Pour supprimer un champ, envoyez une requête à DELETE /v1/vaults/{vault_id}/schema-fields/{name}.

4. Créer une règle de routage

Sans règle de routage, vos documents ne sont pas archivés. Toutes les règles sont évaluées pour chaque document : un document qui correspond à plusieurs règles est archivé une fois par règle correspondante.

4.1. Créer la règle

Envoyez une requête à POST /v1/vaults/{vault_id}/rules et transmettez le name de la règle.

curl
https://api.universign.com/v1/vaults/vlt_id/rules \
-d name="Signed documents"

L’API renvoie un objet rule avec son id. Pour définir une description, envoyez une requête à POST /v1/vaults/{vault_id}/rules/{rule_id} avec l’argument description.

4.2. Ajouter des conditions

Les conditions définissent les documents concernés par la règle. Toutes les conditions d’une règle doivent être remplies pour que la règle s’applique. Si une règle n’a aucune condition, tous les documents sont éligibles à l’archivage.

Envoyez une requête à POST /v1/vaults/{vault_id}/rules/{rule_id}/conditions avec :

  • source : l’information à évaluer (consultez le tableau ci-dessous),
  • operator : l’opérateur de comparaison (consultez le tableau ci-dessous),
  • value : la valeur attendue. Avec les opérateurs in et not_in, transmettez plusieurs valeurs séparées par des virgules (par exemple value=document,evidence).
curl
https://api.universign.com/v1/vaults/vlt_id/rules/rul_id/conditions \
-d source=document.kind \
-d operator=equals \
-d value=document
source Description
document.kind La nature du document. Valeurs possibles : document (les documents de la transaction), evidence (les fichiers de preuve) et capture (les documents capturés).
document.id L’identifiant du document.
document.metadata.<clé> La valeur d’une métadonnée du document (par exemple document.metadata.contract_ref).
transaction.id L’identifiant de la transaction.
transaction.name Le nom de la transaction.
transaction.year L’année de la transaction.
transaction.folder_name Le nom du dossier de la transaction.
transaction.metadata.<clé> La valeur d’une métadonnée de la transaction (par exemple transaction.metadata.clientId).
operator La condition est remplie si la source…
equals est égale à la valeur.
not_equals est différente de la valeur.
in fait partie des valeurs. Séparez les valeurs par des virgules.
not_in ne fait pas partie des valeurs. Séparez les valeurs par des virgules.
exists est renseignée. Ne transmettez aucune value.
not_exists n’est pas renseignée. Ne transmettez aucune value.

4.3. Ajouter des instructions d’archivage

Les instructions définissent les valeurs envoyées au coffre pour chaque champ lorsque la règle s’applique. Envoyez une requête à POST /v1/vaults/{vault_id}/rules/{rule_id}/instructions pour chaque champ, avec :

  • field_name : le nom du champ du coffre,
  • value : une valeur statique ou une expression entre ${ et }. Pour le champ de type de document, transmettez le nom du champ de type de document cible (par exemple SignedDocument).
curl
https://api.universign.com/v1/vaults/vlt_id/rules/rul_id/instructions \
-d field_name=document_number \
--data-urlencode 'value=${transaction.id}-${document.name}'
curl
https://api.universign.com/v1/vaults/vlt_id/rules/rul_id/instructions \
-d field_name=SignedDocument \
-d value=SignedDocument

Les expressions disponibles sont :

Expression Valeur envoyée au coffre
${transaction.id} L’identifiant de la transaction
${transaction.name} Le nom de la transaction
${transaction.year} L’année de la transaction
${transaction.created_at} La date de création de la transaction
${transaction.folder_name} Le nom du dossier de la transaction
${transaction.metadata.<clé>} La valeur d’une métadonnée de la transaction
${document.id} L’identifiant du document
${document.name} Le nom du document
${document.metadata.<clé>} La valeur d’une métadonnée du document

Notez qu’une expression doit toujours être saisie entre ${ et }. Sinon, le texte est envoyé au coffre comme valeur statique.

Pour supprimer une règle, envoyez une requête à DELETE /v1/vaults/{vault_id}/rules/{rule_id}.

Notez que les conditions et les instructions ne peuvent pas être modifiées ni supprimées individuellement. Pour les changer, supprimez la règle puis recréez-la avec les nouvelles conditions et instructions.

5. Déployer le coffre

Votre configuration n’est appliquée qu’une fois déployée. Envoyez une requête à POST /v1/vaults/{vault_id}/deploy. La configuration du provider et les règles sont validées, puis la version courante du coffre est utilisée pour router vos documents.

curl -X POST
https://api.universign.com/v1/vaults/vlt_id/deploy

L’objet vault renvoyé a l’attribut deployed à true.

Les modifications effectuées après un déploiement ne sont appliquées qu’après un nouveau déploiement du coffre. Dans ce cas, l’attribut needs_redeploy du coffre vaut true.

Pour suspendre temporairement l’archivage via un coffre, envoyez une requête à POST /v1/vaults/{vault_id}/undeploy. Le coffre n’est plus utilisé pour router vos documents jusqu’à son prochain déploiement.

Router les documents grâce aux métadonnées de document

Les règles de routage peuvent s’appuyer sur les métadonnées que vous associez à chaque document (consultez Ajouter des métadonnées au document), aussi bien dans les conditions que dans les instructions.

Par exemple, pour envoyer au coffre la référence de contrat transmise lors de l’ajout du document :

curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/documents \
-d document=file_d0bDo8LgEkEA \
-d metadata[contract_ref]=C-2026-001
curl
https://api.universign.com/v1/vaults/vlt_id/rules/rul_id/instructions \
-d field_name=document_number \
--data-urlencode 'value=${document.metadata.contract_ref}'

Consulter la configuration de votre coffre

  • GET /v1/vaults : liste les coffres de votre espace de travail.
  • GET /v1/vaults/{vault_id} : récupère un coffre avec ses champs et ses règles.
  • GET /v1/vaults/{vault_id}/rules/{rule_id} : récupère une règle avec ses conditions et ses instructions.

Pour plus de détails sur les endpoints de coffre, consultez l’API reference.


Espace Développeur
Guides
Services
Référence API