Guides
Status PageRoadmapTestimoniesShare feedback

Qualified Electronic Seal

This guide helps you perform qualified electronic sealing in testing and production environments.

Suggest Edits

Step 1: Upload a Document

Upload the Document to Seal. The Document must be a PDF. All constraints that apply to Signature Documents also apply to Electronic Seal Documents. Note that your Document can also be password-protected, like Signature Documents.

Upload your Document with the Electronic Seal Document upload endpoint:

curl --request POST \
     --url https://{baseUrl}/electronic_seal_documents \
     --header 'Authorization: Bearer {apiKey}' \
     --header 'accept: application/json' \
     --header 'content-type: multipart/form-data' \
     --form 'file=@"/Users/user/document.pdf"'

{
  "id": "{{documentId}}",
  "total_pages": 2,
  "created_at": "2024-01-18T22:59:00+00:00"
}

Note the response id, so you will be able to reuse it for the actual Sealing.

Step 2: Create your secret

In order to ensure the integrity and authenticity of your requests to activate the Qualified Electronic Seal, you have to create a secret corresponding to a JWS (JSON Web Signature). A JWS corresponds to a signed JWT (JSON Web Token).

The creation of this JWS requires the following information:

  • Header
  • Payload
  • Private key, corresponding to the private key created during the Qualified Seal Certificate generation following this process, that will be used for the JWT encryption.

ℹ️

Sandbox use

As a first step, please reach out to your customer representative so you are allowed to use this feature in Sandbox.

For Sandbox use, the following shared private key must be used:

-----BEGIN EC PARAMETERS-----
BggqhkjOPQMBBw==
-----END EC PARAMETERS-----
-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIJSo3MhRNE8/DCFSAqNNJsAVuVJFOJJ5z4NwOmMlZCo/oAoGCCqGSM49
AwEHoUQDQgAELgdwOSjPeGOlUAdEZ6mbQFFA4VN+WAsA80RpEYMug2+mhEpNXPe1
K4yBYoi0gisHiceykyCeSIOXn9llf5VsYw==
-----END EC PRIVATE KEY-----

⚠️ This private key is dedicated to Sandbox use and integration testing purposes. It does not allow to perform sealing operations with legal value.

Header

The header is an object containing the parameters describing the cryptographic operations and parameters used. It must include the following parameters:

  • alg: identifies the cryptographic algorithm used to secure the JWS. Only ES256 algorithm is supported for now.
  • typ: declares the encoded object type of the JWS. Only JWT is supported for now.

Example:

{
  "alg": "ES256",
  "typ": "JWT"
}

Payload

The payload is an object containing information to be secured and some JWT Claims. It must include the following information:

  • iat: identifies the time at which the JWT was issued. Its value must be a UNIX timestamp, UTC format.
  • exp: identifies the expiration time on or after which the JWT must not be accepted for processing. Its value must be a UNIX timestamp, UTC format.
  • nbf: identifies the time before which the JWT MUST NOT be accepted for processing.
  • document_hash: hash of the Document to Seal that you uploaded in Upload a Document step.

Example:

{
    "iat": 1740669749,
    "exp": 1740669809,
    "nbf": 1740669749,
    "document_hash": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Document hash

A Document hash is a unique signature that helps to identify the document in a verifiable way. This information is requested in order to ensure that the Sealed Document is the one you uploaded initially.

SHA-256 hash function must be used.

To compute this hash, some libraries are provided by several programming languages or command line tools on Unix or Windows systems.

Secret (JWS) generation

Like Document hash computation, the generation of your JWS can be performed with programming languages such as Python, PHP or Java for example, for which libraries are available (see PyJWT for Python orfirebase/php-jwt for PHP or jjwt for JAVA) or in command line on Unix or Windows systems.

Example of JWS:

eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.eyJpYXQiOjE3NDA0MTgyNTcsImV4cCI6MTc0MDQxOTQ1NywiZG9jdW1lbnRfaGFzaCI6IjNkZjc5ZDM0YWJiY2E5OTMwOGU3OWNiOTQ0NjFjMTg5MzU4MjYwNGQ2ODMyOWE0MWZkNGJlYzE4ODVlNmFkYjQifQ.OwQLhDIN4FYa3chapBLhmRSzYDzc7Vtg3rccJcAjdNSBObJdOxBuFc4c-2nRPFWbMw5e6TYteV6rkvo5gIphL

ℹ️

If you have trouble with this secret generation step, just ask your customer representative for help.

Step 3: Seal the Document

You can now proceed with the actual Sealing of the Document. A typical Seal payload for Qualified Electronic Seal consists of 4 items:

  • The secretgenerated in the previous step;
  • The document_id for the Document to Seal (retrieved in step one);
  • The signature_levelset to qualified_electronic_signature to specify you want to create a Qualified Electronic Seal;
  • One or more fields, of which at least 1 field of type seal (see Add Fields to your Electronic Seal for more details on fields and how to use them);
    • To be noted that the Qualified Seal payload only accepts one sealfield.
  • For other properties, please refer to Create an Electronic Seal

For now, let us create a Qualified Seal with the Electronic Seal creation endpoint:

curl --request POST \
     --url https://{baseUrl}/electronic_seals \
     --header 'Authorization: Bearer {apiKey}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "secret": "{{yourSecret}}",
  "document_id": "{{documentId}}",
  "signature_level": "qualified_electronic_signature",
  "fields": [
    {
      "type": "seal",
      "page": 1,
      "height": 100,
      "width": 100,
      "x": 0,
      "y": 0
    }
  ]
}
'

{
  "id": "1365283d-0ba5-4a08-9a58-9818ef428320",
  "status": "pending",
  "signature_level": "advanced_electronic_signature",
  "created_at": "2024-01-18T22:59:00+00:00",
  "document_id": "{{documentId}",
  "timestamp": true,
  "image_id": null,
  "external_id": null
}

Don't forget to replace secretand documentId with the actual values retrieved from previous steps.

After creation, your Seal will have a status of pending. This means that it is will soon be processed (see the different statuses here).

Step 4: Download your Sealed Document

Once the Seal has been processed (see the dedicated guide for that purpose), you can download the Sealed Document using Document download endpoint:

curl --request GET \
     --url https://{baseUrl}/electronic_seal_documents/{documentId}/download \
     --header 'Authorization: Bearer {apiKey}' \
     --header 'accept: application/pdf' \
     --output 'document.pdf'

The signature panel in a PDF viewer will show you that the Document has been Sealed using your certificate.

Updated 1 day ago