Demander un cachet

En plus de l’utilisation des cachets dans le cadre d’une transaction, nous proposons un service de cachet autonome.

Avec le service de cachet autonome, vous pouvez :

sceller un document PDF (PAdES), voir Sceller un document PDF,
sceller un document XML (XAdES), voir Sceller un document XML (XAdES),
signer un hash pour construire votre propre conteneur de signature, voir Signer un hash,
récupérer la chaîne de certificats de votre CPM, voir Récupérer la chaîne de certificats.

Avant de pouvoir demander un cachet sur un document, vous devez :

Posséder un certificat de personne morale (CPM).
Vous assurer que la fonctionnalité est activée sur votre compte.

Pour demander la création d’un CPM et/ou activer la fonctionnalité sur votre compte, contactez votre gestionnaire de compte chez Universign.

Notez que lorsque vous utilisez le service de cachet autonome, les documents cachetés ne sont pas stockés. Les documents ne sont stockés que lorsque vous cachetez un document dans le cadre d’une transaction.

Sceller un document PDF

Pour apposer un cachet sur un document, envoyez une requête multipart/form-data à POST /v1/seals et transmettez le document dans l’argument file ainsi que le seal_id du certificat.

Notez que nous n’acceptons que le format PDF pour les fichiers d’une taille maximale de 25 Mo.

curl
https://api.universign.com/v1/seals \
-F [email protected] \
-d seal_id=lpc_wa7ZVZGxzOq0 \
-d label="John DOE, CEO of the company"

Vous pouvez passer des paramètres facultatifs :

field_page : numéro de la page sur laquelle vous souhaitez positionner le cachet. La valeur par défaut est 1.
field_x : coordonnée horizontale du cachet sur la page du document (en pixels). La valeur par défaut est 0.
field_y : coordonnée verticale du cachet sur la page du document (en pixels). La valeur par défaut est 0.
height : la hauteur du cachet (exprimée dans les unités d’espace utilisateur par défaut du PDF). La valeur minimale est 23, la valeur par défaut est 50 et le ratio de hauteur doit être 4 x la largeur.
width : la largeur du cachet (exprimée dans les unités d’espace utilisateur par défaut du PDF). La valeur minimale est 92, la valeur par défaut est 200 et le ratio de hauteur doit être 4 x la largeur.

Si vous ne transmettez que les paramètres obligatoires ou si vous ne transmettez pas les paramètres field_page, field_x, field_y, height et width, la requête renvoie une réponse 200 qui contient un cachet de document PAdES avec un cachet invisible.

language : la langue du texte dans la cartouche du cachet (« Scellé par [sealname], le [sealdate] »). Le format d’entrée attendu est ISO 639-1. Nous prenons actuellement en charge les langues suivantes : Français (fr), Allemand (de), Anglais (en), Bulgare (bg), Catalan (ca), Espagnol (es), Italien (it), Néerlandais (nl), Norvégien (no), Polonais (pl), Portugais (pt), Roumain (ro) et Suédois (sv). Le français (fr) est la langue par défaut.
custom_logo : le logo du cachet qui s’affichera sur le document. Nous acceptons uniquement les formats JPEG et PNG d’une taille maximale de 2 Mo.

Remarque : Pour garantir une résolution de haute qualité, les dimensions de votre logo doivent être de 300px x 72px.

Notez que la taille du cachet est fixée à 200px x 50px et ne peut pas être modifiée. Assurez-vous que le cachet est bien positionné dans le document. Si l’un des bords du cachet dépasse les limites du document, l’API renvoie une erreur.

label : le libellé qui s’affichera sur le cartouche de signature. Notez que la valeur label sera toujours précédée de l’expression Sealed by (Scellé par) générée automatiquement par notre système. Cette fonctionnalité doit être activée dans votre espace de travail.
compliance_policy : à définir sur pdfa pour forcer l’opération de cachet à respecter la norme PDF/A. Si ce paramètre n’est pas défini, si vous importez un document PDF/A, il sera scellé mais ne sera plus conforme à la norme PDF/A.
signature_type : le type de signature pour un cachet autonome. transmettez-le sur certification pour appliquer une signature de certification au document. Pour plus de détails, consultez Signatures de certification.
certification_permission : définit les modifications autorisées après l’application d’une signature de certification. Les valeurs possibles sont read_only, fill, annotate. À définir uniquement si signature_type est défini sur certification.

Les autorisations de certificat

read_only : aucune modification du document n’est autorisée. Toute modification du document invalide la signature.

fill : les modifications autorisées sont le remplissage de formulaires, l’instauration de modèles de page et la signature. Toute autre modification invalidera la signature.

Notez que les formulaires et les champs de signature doivent déjà être présents dans le document à certifier.

Les champs de signature intégrés doivent avoir des dimensions égales ou supérieures à 200x50px. Si un champ de signature intégré est trop petit, le document n’est pas accepté.

annotate : les modifications autorisées sont les mêmes que pour fill, ainsi que la création, la suppression et la modification d’annotations. Toute autre modification invalidera la signature.

Sceller un document à l’aide d’un certificat QCP-l-qscd

Vous pouvez être amené à sceller un document à l’aide d’un certificat QCP-l-qscd de personne morale (CPM). Comme il s’agit d’un certificat de niveau supérieur, l’utilisation du cachet doit être autorisée en saisissant le code PIN - préalablement initialisé - pour ce certificat.

Pour ce faire, vous devez passer le code PIN du certificat dans l’argument auth_data[].value, comme dans l’exemple de requête ci-dessous :

Exemple de requête

curl
https://api.universign.com/v1/seals \
-F [email protected] \
-d seal_id=lpc_wa7ZVZGxzOq0 \
-d auth_data[atm_Bw3e].value=12345678

auth_data[ ].value : à définir uniquement pour autoriser l’utilisation d’un certificat QCP-l-qscd de personne morale (CPM) afin de sceller un document. Vous devez spécifier le code PIN associé au certificat. L’identifiant du moyen d’authentification doit être ajoutée à l’argument auth_data[ ].value entre crochets (par exemple auth_data[atm_Bw3e].value). Notez que vous pouvez récupérer l’identifiant du moyen d’authentification dans la section Certificats de votre espace de travail.

Sceller un document PDF/A

PDF/A est un format normalisé ISO (ISO 19005) soumis à des règles strictes visant à éliminer tout élément susceptible de se détériorer avec le temps.

PDF/A est généralement requis lorsque des documents doivent être archivés, échangés ou conservés à des fins juridiques.

Vous pouvez avoir besoin de sceller sur un document PDF/A et de garantir le même niveau de conformité une fois le cachet apposé. Pour ce faire, envoyez une requête multipart/form-data à POST /v1/seals et transmettez le document dans l’argument file, le seal_id du certificat, ainsi que l’argument compliance_policy.

curl
https://api.universign.com/v1/seals \
-F file=@MyPDF_A.pdf \
-d seal_id=lpc_wa7ZVZGxzOq0 \
-d compliance_policy=pdfa

L’API renvoie une réponse 200 contenant le document PDF/A scellé et présentant le même niveau de conformité.

Les illustrations ci-dessous montrent la vérification de la conformité du document PDF/A avant et après l’apposition du cachet.

Vérification de la conformité du document PDF/A

Vérification de la conformité du document PDF/A scellé

Récupérer la chaîne de certificats

Avant de signer un hash, vous pouvez avoir besoin de l’identifiant de votre CPM et de la chaîne de certificats de votre sealer. L’identifiant de votre CPM (ou sealer) est le même que le seal_id utilisé pour sceller un document PDF (par exemple lpc_wa7ZVZGxzOq0).

Pour Récupérer la chaîne de certificats, envoyez une requête GET à GET /v1/sealers/{sealer_id}.

curl
https://api.universign.com/v1/sealers/lpc_wa7ZVZGxzOq0

L’API renvoie une réponse 200 contenant un objet JSON :

{
  "id": "lpc_wa7ZVZGxzOq0",
  "certificate_chain": [
    "MIIGyjCCBLKgAwIBAgIRAJZpvFJjhgMj...",
    "MIIF...",
    "MIIFbDCCA1SgAwIBAgIUEAOYh64F0ICU..."
  ],
  "signature_algorithms": [
    "1.2.840.113549.1.1.10"
  ]
}

id : l’identifiant du sealer.
certificate_chain : la chaîne de certificats du CPM, encodée en base64. Le certificat de signature est placé en premier, suivi des certificats intermédiaires et racine.
signature_algorithms : les OID des algorithmes de signature pris en charge par le sealer. Lisez cette liste plutôt que de coder l’OID en dur, afin que votre intégration continue de fonctionner lorsque de nouveaux algorithmes seront ajoutés.

Notez que la chaîne de certificats est renvoyée même lorsque le certificat est expiré ou révoqué, afin que vous puissiez vérifier son statut. La signature avec un tel certificat est en revanche refusée.

Utilisez la chaîne de certificats pour construire votre conteneur de signature après une signature de hash, ou pour vérifier une signature.

Notez que le CPM doit être rattaché à votre espace de travail. Dans le cas contraire, l’API renvoie une erreur 404.

Signer un hash

Vous pouvez avoir besoin de signer des données qui ne sont ni un PDF ni un document XML, ou de construire votre propre conteneur de signature (par exemple avec la bibliothèque DSS). Dans ce cas, vous calculez le hash de vos données de votre côté et vous envoyez uniquement ce hash pour qu’il soit signé avec votre sealer.

Vos données ne quittent jamais votre système : vous n’envoyez que leur hash. L’API renvoie la valeur brute de la signature, que vous intégrez dans votre propre conteneur de signature (CAdES, XAdES, JAdES, PAdES…).

1. Calculer le hash de vos données

Le hash doit être calculé avec l’algorithme SHA-256 et transmis sous forme de fichier binaire (32 octets), et non sous forme de chaîne hexadécimale.

openssl dgst -sha256 -binary MyDocument.pdf > hashvalue

Par exemple, le hash SHA-256 354BD98DA206B3A5650BBE4C6630D467AAF65A4E33590DD20E50C469104FE8A6 (représentation hexadécimale) doit être transmis sous forme des 32 octets correspondants. Si vous disposez déjà du hash sous forme de chaîne hexadécimale, convertissez-le en binaire :

echo -n 354BD98DA206B3A5650BBE4C6630D467AAF65A4E33590DD20E50C469104FE8A6 | xxd -r -p > hashvalue

2. Signer le hash

Envoyez une requête multipart/form-data à POST /v1/sealers/{sealer_id}/sign-hash et transmettez le hash dans l’argument hash, ainsi que les algorithmes de signature et de hash.

curl
https://api.universign.com/v1/sealers/lpc_wa7ZVZGxzOq0/sign-hash \
-F hash=@hashvalue \
-F signature_algorithm=1.2.840.113549.1.1.10 \
-F hash_algorithm=2.16.840.1.101.3.4.2.1 \
--output signature.bin

hash : le hash à signer, sous forme de fichier binaire. Sa longueur doit correspondre à l’algorithme de hash (32 octets pour SHA-256) et ne doit pas dépasser 64 octets.
signature_algorithm : l’OID de l’algorithme de signature.
hash_algorithm : l’OID de l’algorithme de hash utilisé pour calculer le hash.
auth_data[ ].value : à définir uniquement pour autoriser l’utilisation d’un certificat QCP-l-qscd de personne morale (CPM). Pour plus de détails, consultez Sceller un document à l’aide d’un certificat QCP-l-qscd.

Algorithmes pris en charge

Seule la combinaison d’algorithmes suivante est prise en charge. Toute autre valeur est rejetée avec une erreur 400.

Algorithme	Nom	OID
Algorithme de signature	RSASSA-PSS	`1.2.840.113549.1.1.10`
Algorithme de hash	SHA-256	`2.16.840.1.101.3.4.2.1`

L’API renvoie une réponse 200 avec le type de contenu application/octet-stream. Le corps contient la valeur brute de la signature (binaire). Il ne s’agit ni d’un objet JSON ni d’un conteneur de signature : enregistrez-la dans un fichier ou lisez-la comme un tableau d’octets, sans l’interpréter comme du texte.

3. Construire votre conteneur de signature

Utilisez la valeur brute de la signature et la chaîne de certificats renvoyée par Récupérer la chaîne de certificats pour construire votre conteneur de signature.

Vous pouvez vérifier la valeur de la signature avec OpenSSL, à l’aide du certificat de signature (premier certificat de la chaîne) enregistré sous certificate.pem :

openssl x509 -in certificate.pem -pubkey -noout > publickey.pem

openssl pkeyutl -verify -pubin -inkey publickey.pem \
-in hashvalue -sigfile signature.bin \
-pkeyopt digest:sha256 \
-pkeyopt rsa_padding_mode:pss \
-pkeyopt rsa_pss_saltlen:32 \
-pkeyopt rsa_mgf1_md:sha256

Erreurs

L’API renvoie une erreur 400 lorsque :

le signature_algorithm ou le hash_algorithm est absent, vide ou non pris en charge,
le hash est absent, ou sa longueur ne correspond pas à l’algorithme de hash (par exemple The hash must be 32 bytes long, got 16),
le certificat ne prend pas en charge la combinaison d’algorithmes demandée,
le certificat est expiré ou révoqué,
le certificat nécessite une autorisation et aucun auth_data[ ].value n’est transmis.

L’API renvoie une erreur 403 (seal.standalone_seal.unavailable) si le service de cachet autonome n’est pas activé sur votre espace de travail, et une erreur 404 si le CPM n’existe pas ou n’est pas rattaché à votre espace de travail.

Sceller un document XML (XAdES)

Vous pouvez avoir besoin de sceller un document XML, par exemple une facture, un bon de commande ou toute donnée structurée échangée avec un partenaire. Pour ce faire, vous pouvez apposer un cachet XAdES sur votre document XML.

L’API renvoie le même document XML avec une signature enveloppée de niveau XAdES-BASELINE-T : la signature est ajoutée à l’intérieur de l’élément racine de votre document et contient un horodatage qualifié. L’élément racine de votre document est conservé.

Pour sceller un document XML, envoyez une requête multipart/form-data à POST /v1/sealers/{sealer_id}/xades et transmettez le document dans l’argument file.

Notez que nous acceptons les fichiers XML d’une taille maximale de 2 Mo.

curl
https://api.universign.com/v1/sealers/lpc_wa7ZVZGxzOq0/xades \
-F [email protected] \
--output MyDocument-sealed.xml

file : le document XML à sceller. Le document doit être un document XML bien formé.
auth_data[ ].value : à définir uniquement pour autoriser l’utilisation d’un certificat QCP-l-qscd de personne morale (CPM). Pour plus de détails, consultez Sceller un document à l’aide d’un certificat QCP-l-qscd.

L’API renvoie une réponse 200 avec le type de contenu application/xml. Le corps contient votre document XML scellé.

Exemple de réponse (extrait)

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<PurchaseOrder xmlns="urn:example:purchaseorder:1.0" Id="doc-po-001">
  ...
  <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#" Id="id-dc0560ef...">
    <ds:SignedInfo>
      <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
      <ds:SignatureMethod Algorithm="http://www.w3.org/2007/05/xmldsig-more#sha256-rsa-MGF1"/>
      <ds:Reference URI="">...</ds:Reference>
      <ds:Reference Type="http://uri.etsi.org/01903#SignedProperties" URI="#xades-id-dc0560ef...">...</ds:Reference>
    </ds:SignedInfo>
    <ds:SignatureValue>...</ds:SignatureValue>
    <ds:KeyInfo>...</ds:KeyInfo>
    <ds:Object>
      <xades:QualifyingProperties Target="#id-dc0560ef...">
        <xades:SignedProperties>
          <xades:SignedSignatureProperties>
            <xades:SigningTime>2026-09-25T14:15:00Z</xades:SigningTime>
            <xades:SigningCertificateV2>...</xades:SigningCertificateV2>
          </xades:SignedSignatureProperties>
          <xades:SignedDataObjectProperties>...</xades:SignedDataObjectProperties>
        </xades:SignedProperties>
        <xades:UnsignedProperties>
          <xades:UnsignedSignatureProperties>
            <xades:SignatureTimeStamp>...</xades:SignatureTimeStamp>
          </xades:UnsignedSignatureProperties>
        </xades:UnsignedProperties>
      </xades:QualifyingProperties>
    </ds:Object>
  </ds:Signature>
</PurchaseOrder>

Le cachet XAdES utilise les mêmes algorithmes que la signature de hash : RSASSA-PSS avec SHA-256. Aucun autre algorithme n’est disponible.

Vous pouvez vérifier votre document XML scellé avec l’outil de validation DSS de la Commission européenne.

Erreurs

L’API renvoie une erreur 400 lorsque :

le file est absent, ou dépasse la taille maximale autorisée,
le file n’est pas un document XML, ou n’est pas un document XML bien formé,
le certificat est expiré ou révoqué,
le certificat nécessite une autorisation et aucun auth_data[ ].value n’est transmis.

D’autres formats de signature, comme JAdES (JSON) et CAdES, seront bientôt disponibles avec le service de cachet autonome.

Transactions

Modèles

Archives

Identité & certificats

Horodatages

Cachets

Master console

Demander un cachet

Sceller un document PDF

Sceller un document à l’aide d’un certificat QCP-l-qscd

Sceller un document PDF/A

Récupérer la chaîne de certificats

Signer un hash

1. Calculer le hash de vos données

2. Signer le hash

3. Construire votre conteneur de signature

Erreurs

Sceller un document XML (XAdES)

Erreurs

Créer un webhook endpoint

Les modèles de transaction

Espace Développeur

Guides

Services

Référence API