eSignature

Automatic and Mass Signature Certificates, with or without OTP, can be purchased via the endpoints

• POST /certificates/namirial-automatic
• POST /certificates/namirial-otp

Once the request has been made via the API, a link will be available in the response to initiate the identification procedure, according to current regulations, of the applicant and thus obtain the certificate.

Our service includes video recognition, which can be done from the comfort of your home or office in a few seconds. Alternatively, other identification procedures are available via:

• SPID
• CIE
• CNS
• Digital signature

PLEASE NOTE: Purchase of the certificate is essential in order to use the Automatic and Massive Qualified Electronic Signature service (with or without OTP).

The certificate is valid for 3 years.

The CERT_USERNAME and CERT_PASSWORD credentials are not issued immediately after purchasing a QES signing certificate. To obtain them, it is necessary to complete the certificate holder identification procedure.

After submitting a purchase request through the POST /certificates/namirial-automatic or POST /certificates/namirial-otp endpoints, the API response returns the certificateLink field, which contains the URL required to start the identification process. The procedure usually takes only a few minutes and must be completed directly by the certificate holder.

Once the activation process has been successfully completed, the credentials are delivered through separate channels to ensure the highest level of security:

• SMS containing the PIN;
• Email containing the CERT_USERNAME and a password-protected PDF attachment containing the CERT_PASSWORD.

To open the PDF and view the CERT_PASSWORD, you must use the PIN received via SMS.

Separating the delivery channels for the credentials reduces the risk of unauthorized access and provides enhanced protection for the signing certificate.

If you do not receive the email containing the credentials, please also check your Spam/Junk folder and ensure that the email address provided during the certificate request is correct.

Purchasing a QESeal certificate (available with a validity of 1 or 3 years) currently requires a manual procedure through customer support.

Follow these steps:

1. Contact customer support to start the purchase request.
2. Complete the purchase following the instructions provided by support and receive the identification form by email.
3. Submit the required documentation for the identification process:

• identity document
• company registration certificate (or equivalent document, depending on the applicant company's country)
• completed form (received in step 2)

4. Receive the certificate credentials (certificateUsername and certificatePassword) at the email address specified in the form. The certificateUsername is a string with the prefix SHI.

IMPORTANT: Purchasing the seal is mandatory in order to use the QESeal service on Openapi.

You can carry out the signing process via API via the endpoints

• POST/EU-QES_automatic for Massive Automatic Signature Certificate
• POST/EU-QES_OTP for Remote Certificate with OTP
• POST/EU-QES_eseal for Qualified Electronic Seal

 The mandatory fields for the QES are three:

1. Document (inputDocument)
2. Signature Certificate Username
3. Signature Certificate Password

If the signatureType is not specified, the system will select the most suitable format (CAdES, PAdES, XAdES, PKCS#1) based on the uploaded file's mimeType.

The European eIDAS Regulation (Electronic Identification, Authentication and Trust Services) defines three levels of electronic signatures, each with different characteristics and legal value:

Simple Electronic Signature (SES)
It is the most basic form of electronic signature. It allows an action or consent to be associated with a user but provides limited guarantees regarding the signatory's identity. It is commonly used to accept terms and conditions, confirm online transactions, or access digital services.

Advanced Electronic Signature (AES)
It ensures a unique link between the signatory and the signed document, making it possible to identify the signatory and detect any subsequent changes to the document. In many cases, it may have the same legal effect as a handwritten signature and is suitable for signing contracts and private agreements.

Qualified Electronic Signature (QES)
This is the highest level of electronic signature defined by the eIDAS Regulation. Issued through a qualified certificate by a qualified trust service provider, it offers the highest level of security and has full legal validity throughout the European Union. In Italy, it is commonly associated with digital signatures.

Which One Should You Choose?

Note: The information provided is for general informational purposes only and does not constitute legal advice. The choice of the most suitable type of electronic signature depends on the applicable regulatory framework, the level of risk, and the specific needs of your business. To identify the most appropriate solution, it is recommended to consult your legal team or specialized advisors.

QES OTP and QES Automatic services support different qualified electronic signature standards, each designed for specific document types and use cases:

• CAdES (CMS Advanced Electronic Signatures): allows you to sign any type of file. The signed document is generally generated with a .p7m extension, which embeds both the original file and the digital signature.
• PAdES (PDF Advanced Electronic Signatures): dedicated to PDF documents. It preserves the .pdf extension and allows the signature to be displayed directly within the document.
• XAdES (XML Advanced Electronic Signatures): specifically designed for XML documents, commonly used for data exchange between applications and information systems.
• PKCS#1: does not represent a document signature format, but rather an RSA-based cryptographic standard used to sign hashes or application-level data.

In summary, CAdES, PAdES, and XAdES define the format and method used to apply a digital signature to different types of documents, while PKCS#1 defines the cryptographic mechanism used to generate and verify the signature itself. The choice of standard depends on the document format and the integration requirements of the signing process.

Note: depending on the selected signature standard (CAdES, PAdES, XAdES, or PKCS#1), specific additional configuration options will be available and can be set during the signing request through the option field in the payload.

These options allow you, for example, to customize the signature behavior, the output document format, and other parameters specific to the selected standard.

To view all available options, supported values, and implementation details, please refer to the technical documentation and the corresponding API schema for the selected signature standard. This will help you correctly configure the service according to your integration requirements.

Yes, the QES OTP and QES Automatic services allow you to customize the position of the signature within the document by specifying the page where it should be applied or the signature fields to be used.

Note: this feature is available exclusively for PAdES signatures, the only signature format that is visibly displayed within the PDF document.

If no configuration is specified, the signature is automatically placed in the bottom-left corner of the first page.

To customize the signature position through the /EU-QES_otp or /EU-QES_automatic endpoint, you can use the parameters available in the options object of the request payload.

1. Positioning by page (page)

You can specify the PDF page where the signature field will be created and the digital signature applied:

• 1 → first page of the document
• 2 → second page of the document
• -1 → last page of the document

For example, by setting page: -1, the signature will be automatically inserted on the last page of the PDF.

When this parameter is used, the signature is always placed in the bottom-left corner of the selected page.

2. Sign all signature fields in the document (signAllFields)

If the document contains one or more predefined signature fields, you can set the following property inside the "signerImage" object:

"signAllFields": true

The signature will then be automatically applied to all signature fields available in the PDF.

3. Sign specific fields (fieldsNameList)

If you want to sign only specific fields, you can use the fieldsNameList parameter within the signerImage object.
The parameter must contain an array with the identifiers of the signature fields to be signed:

"fieldsNameList": [
"CustomerSignature",
"ContractHolderSignature"
]

The signature will be applied exclusively to the fields specified in the array.

The service allows various configurations, such as:

• Validation and signing mode (synchronous or asynchronous)
• Signature level
• Hash algorithm
• Callback for notifications and updates
  

Some options are specific to certain formats, such as signature positioning in PDF documents.

The response depends on the request's status and may be:

• Waiting for validation
• Waiting for signature process to complete
• Signature process completed

In case of a successful outcome ("DONE"), the response will include details such as status, signature format, selected options (e.g., signature level, hash algorithm, potential callback), and completion date.

Yes, through the GET /signatures/{id}/{actionType} endpoint, you can request the full details of the process, the signed document, the validated document, or the audit trail. The audit trail includes all information leading to the successful signature and allows for technical reconstruction of each step in case of disputes.

Both. The Qualified Electronic Signature (QES) via API allows you to choose between synchronous or asynchronous validation and signing.

The signature procedure has legal validity (eIDAS) and is reinforced by sending signatory verification OTPs. At the end of the signing procedure, it will also be possible to request via API both the signed document and the copy of the audit trail. The audit trail is the document that contains all the information that led to the successful signature. In the event of disputes, this file will make it possible to technically reproduce each step of the procedure.  The audit trail contains data on the procedure (id, creation date, sending and expiry), on signatories (name, surname, email, telephone number, IP address) signatory authentication mode (authentication method, message sent and time of validation). The audit trail is archived in its original form for 10 years.

The electronic signature service (SES) allows you to sign PDF documents remotely in a simple, secure way and in compliance with applicable regulatory standards. Multiple signers can be involved in the same document, including with different signature placements within the pages.

The process is structured into the following steps:

1. API request submission
Make an API call including signer details (first and last name), the type of signature to apply (typed or drawn), the OTP authentication method (email or SMS), and the language of the interface and OTP communications. Depending on the selected authentication method, you will also need to provide the signer’s email address or mobile phone number.

2. Signature link generation
The system returns unique links for each signer, to be used to access the signing process. It is your responsibility to distribute the links to the respective signers and manage the delivery of the signing interface.

3. Document signing
Signers access the platform via the received link, complete OTP authentication, and proceed with signing the document.

4. Process completion and download
At the end of the process, the signed and validated document is made available for download, along with the complete operation log (audit trail), ensuring full traceability of the signing workflow.

Yes, it is possible to customize the SES signing interface for the end user already at the request stage.

Customization can include, for example, changing colors (background, title, and text) and the visibility of the sidebar, header, and footer, as well as adding your company logo. It is also possible to enable or disable the document download for the user.

Finally, at the end of the signing process, it is possible to configure a redirect URL to a custom web page.

Yes, it is possible to set the language of the SES signing interface at the signer level.

The language in which the user views the interface and receives communications (email or SMS containing the OTP) can be defined through the “Language” field within the Signers object.

Yes. The SES service allows you to define whether a signer's data can be modified during the signing process through the userEditableData object, available within the options object of the POST /EU-SES request.

By default, signers can modify certain personal information, including:

• First and last name
• Email address
• Mobile phone number

These options are enabled by default and set to true.

If you want to prevent signers from modifying one or more fields, simply set the corresponding properties to false. The data will then be displayed in read-only mode within the signing interface and cannot be edited by the user.

This feature is particularly useful when you need to ensure that data collected and verified beforehand remains unchanged throughout the entire signing process.

Error 815 – invalid signer email is returned when the signer’s email address is not valid or has not been correctly provided in the request.

To resolve the issue, we recommend checking that the value provided is formally correct and does not contain unwanted spaces before or after the email address.

In particular, we suggest implementing the following client-side validations before sending the API request:

1. Syntax check (email format)
Ensure that the input string matches a valid email format (e.g. [email protected]).
If the format is incorrect, block the request directly in the user interface, preventing the API call.

2. String sanitization
Make sure to remove any leading or trailing spaces by applying a normalization such as .trim() to the email value.

3. Form validation enforcement
To minimize errors, it is recommended to prevent form submission until validation has been successfully completed, avoiding invalid API requests.

Yes, the service supports adding any type of timestamp, providing additional security and legal validity to signed documents.

The validity of a signed document can be verified through the POST /verify endpoint. The response will include details such as:

• Confirmation of the signature validity and format used
• Document owner
• Certificate status and date
• Any certificate revocation with the respective date
• Presence and date of a timestamp

The activation and usage times of eSignature services vary depending on the type of signature or certificate requested:

• Automatic QES (with or without OTP): certificate activation depends on the completion of the video identification process, which in most cases takes only a few minutes.
• QESeal (Qualified Electronic Seal): certificate issuance generally requires up to 10 business days from the receipt of payment and all the documentation required for preliminary verification.
• SES (Simple Electronic Signature): signer identification takes place in real time during the signing process through OTP verification.
• Applying the signature or seal: once the service has been activated, the application of the automatic signature, the OTP signature, the simple signature (SES), or the electronic seal is performed in real time via API.

Under the Usage section, you can monitor free requests and those made through subscription or top-up. This is available in both graphical (monthly and yearly periods) and text summary formats.

The QES service has no annual fees. Payment is required only for certificate activation and actual usage.

The costs related to requests are:

• from 0.013€ on subscription and 0.050€ on top-up for the service with Automatic Signature certificate
• from 0,007€ on subscription and 0,050€ on top-up for the service with Automatic Signature certificate with OTP
  

The costs for certificates, on the other hand, are as follows:

• 137€ for the 3-year Automatic Signature certificate + video id
• 29€ for the 3-year Automatic Signature certificate with OTP + video id

The service has no annual fees. There is only a charge for activating the seal and for actual usage.

With regard to uses, the cost is as low as 0.013€/request on subscription or 0.050€/request on top-up.

With regard to the seal, it is possible to request activation for 1 or 3 years and the costs are 387€ for 1 year, 987€ for 3 years.

The cost is per signer, not per number of signatures applied to the document:

• From €0.09 per signer with a subscription plan
• €0.49 per signer for single requests charged on prepaid credit

If there are multiple signers, the cost is multiplied by the number of signers involved, applying the applicable rate (subscription or single request). The charge is applied at the time of the request, regardless of how the signing process is completed later.

During the signing process, it is possible to add a European legally valid timestamp at an additional cost of €0.15.