Implement Document Signing via Evrotrust Application

Implement Document Signing via Evrotrust Application

Info
This guide provides a step-by-step process for integrating the Evrotrust API to enable document signing via the Evrotrust mobile app. The flow involves checking user status, sending documents for signing, handling callbacks, checking status (optional), downloading the signed document, and decrypting it.

Prerequisites:

1. User Check

Endpoint: POST /user/check/extended

Description: This endpoint returns detailed information about the Evrotrust user status and checks if the user has a valid Evrotrust account. Use this to verify if the user is registered and can proceed with signing

Important: You can send only one identifiying parameter (identificationNumber, email, phone) or mutiple - we recommend sending either identificationNumber or phone as the email has the possibility to not be verified yet resulting in a negative response.

Headers:

Content-Type: application/json
Authorization: {{authorization}}

Request Parameters:

  • Body: JSON object with user identifiers (e.g., phone number, email, or identification number).

Idea
Example Request:

  1. {
  2.     "vendorNumber": VENDOR_NUMBER,
  3.     "user": {
  4.         "identificationNumber": 'XXXX',
  5.         "country" : "XX"
  6.         //"email" : "XXX@XXX.XXX"
  7.         //"phone" : '+XXXXXX'
  8. }
1
2
3
4
5
6
7
8
{
"vendorNumber": VENDOR_NUMBER,
"user": {
"identificationNumber": 'XXXX',
"country" : "XX"
//"email" : "XXX@XXX.XXX"
//"phone" : '+XXXXXX'
}


Idea
Example Response:


  1. {
  2.     "isRegistered": 1,
  3.     "isIdentified": 1,
  4.     "isRejected": 0,
  5.     "rejectReason": 0,
  6.     "isSupervised": 1,
  7.     "isReadyToSign": 1,
  8.     "hasConfirmedPhone": 1,
  9.     "hasConfirmedEmail": 1
  10. }
1
2
3
4
5
6
7
8
9
10
{
"isRegistered": 1,
"isIdentified": 1,
"isRejected": 0,
"rejectReason": 0,
"isSupervised": 1,
"isReadyToSign": 1,
"hasConfirmedPhone": 1,
"hasConfirmedEmail": 1
}

If the user does not have an account or is invalid, handle accordingly (e.g., prompt them to register via the app).


2. Send File for Signing via App

Endpoint: POST /document/doc/online

Description: Send the file to a user or multiple users for signing via the Evrotrust application. Specify the document, signers, and a callback URL for notifications.

Headers:

Content-Type: multipart/form-data
Authorization: {{authorization}}

Important: Check out guide on how to create the publicKey here.

Request Parameters:

  • Body: multipart/form-data with two parameters: data="{{data}} - this contains the json body, document=@"/C:/Downloads/example.pdf - this contains the document path

Idea
Example Request:

  1. {
  2.     "vendorNumber": VENDOR_NUMBER,
  3.     "document": {
  4.         "description": "XXXXX",
  5.         "dateExpire": 1760529368,
  6.         "coverage": 20000,
  7.         "preview": 0,
  8.     },
  9.     "signInfo": {
  10.         "type": "PDF2",
  11.         "algorithm": "SHA256",
  12.     },
  13.     "publicKey": {{public_key}},
  14.     "users": [
  15.         {"identificationNumber": 'XXXXXXXXXX',
  16.         "country" : "XX"
  17.         //"email" : "XXX@XXX.XXX"
  18.         //"phone" : '+XXXXXX'
  19.         "employee": 0
  20.         }],
  21.     "urlCallback": "https://xxxxxx.com/",
  22.     "BIOrequired": 0
  23.  }

Idea
Example Response:

  1. {
  2.     "threadID": "9CD21F3BE864",
  3.     "transactions": [
  4.         {
  5.             "transactionID": "449520878519",
  6.             "identificationNumber": "9809057240"
  7.         }
  8.     ]
  9. }

The user will receive a push notification in the Evrotrust app to sign the document.

3. Receive Callback Notification (Evrotrust -> Vendor)

Endpoint: Your specified urlCallback from Step 2 (https://your-server.com/ )

Description: Evrotrust sends signing status updates to this URL. Implement a webhook to receive and process these notifications, which include the transaction ID and status (e.g., signed, rejected).

Idea
Example Request (from Evrotrust):

  1. {
  2.   "transactionID": "961546252836",
  3.   "status": 2
  4. }

Idea
Example Response (your server should return):

  1. HTTP/1.1 200 OK

Process the callback to update your system. Validate the request (e.g., via signature or IP whitelist) for security.

For more information - check “Receive a Callback From Evrotrust” guide.

4. Check Signing Status (Optional)

Endpoint: POST /document/status

Description: Check the signing status of a document using the transactionID from Step 2. This is useful for polling if you require it.

Headers:

Info
Content-Type: application/json

Authorization: {{authorization}}

Request Parameters:

  • Body: JSON with transactionID.

Idea
Example Request:

  1. {
  2.     "vendorNumber": VENDOR_NUMBER,
  3.     "transactionID": "449520878519"
  4. }

Idea
Example Response:

  1. {
  2.     "status": 1,
  3.     "isProcessing": 0
  4. }

Poll this endpoint periodically until the desired status is reached.

5. Download the Signed Document

Endpoint: POST /document/download

Description: Download a ZIP file containing the encrypted signed document using the transactionID.

Headers:

Content-Type: application/json
Authorization: {{authorization}}

Request Parameters:

  • Body: JSON with transactionID.

Idea
Example Request:

  1. {
  2.   "transactionID":"449520878519",
  3.   "vendorNumber": VENDOR_NUMBER
  4. }

Idea
Example Response:
  • HTTP/1.1 200 OK
    1. Content-Type: application/zip
    2. Content-Disposition: attachment; filename="zipFMTry3"

    4. [Binary ZIP content]

    Save the ZIP file for the next step.

    6. Decrypt the Files

    Description: After downloading the ZIP file, follow the our decryption guide to decrypt the signed file. The ZIP typically contains the encrypted signed PDF and additional files needed for decryption.

    Steps:

    • Extract the ZIP file.

    • Use your private key (from integration setup) to decrypt the contents.

    • Refer to the decryption guide here.

    If you encounter issues, refer to the full Evrotrust API documentation at https://developers.evrotrust.com/ .


      • Related Articles

      • Receive a Callback From Evrotrust

        This guide explains how to set up and handle callbacks from Evrotrust. Callbacks are asynchronous notifications sent by Evrotrust to your server when certain events occur (e.g., a document is signed, expires, or is rejected). These notifications ...

      • User Guide - Evrotrust Support Portal - Zoho Desk

        Тable of Contents Summary & Overview Purpose of This Guide How to Use the Evrotrust Support Portal 1. Registration, Login & Forgotten Password 1.1 First-Time Access 1.2 How to Log In 1.3 How to Reset a Password 2. Navigating the Portal 2.1 Home ...

      • Document Decryption Guide

        This guide provides a step-by-step explanation of the decryption process for the encrypted file in the result of document/download. The scheme combines RSA (asymmetric encryption) to encrypt a symmetric key and AES (symmetric encryption) in CBC mode ...

      • How to Generate Your Public and Private Keys

        This guide explains how to generate an RSA 2048-bit key pair in PKCS#8 format, and prepare them for use in API requests. RSA is an asymmetric encryption algorithm where the public key is used for encryption, and the private key for decryption. This ...

      • Availability Report

        Attached, you can find the availability report for the services by month: