API Based Flow With File Hashes for .asice

This flow is best suited for cases where you do not wish to send the actual file contents to eID Easy. The only things you'll be sending to eID Easy service for signing are the file name and the file hash. This means that you can safely collect qualified electronic signatures in your own server without sending the document contents to any third parties.

With the API Based Flow With File Hashes you'll take care of handling all the user interactions and use the eID Easy API endpointsopen in new window only.

At the highest level, an "API based signing flow with file hashes for .asice" goes as follows:

File hash is prepared for signing - this is a single API request
User signs the file hash - this might require multiple API requests, polling and/or redirects depending on the signing method. TIP: We also have a couple of front-end components that can handle method specific user interactions and API requests for you. Take a look at our Browser Clientopen in new window and Widgetopen in new window
Fetch the signature - get the signature from eID Easy api.
Add the signature to an .asice container

Now, you're already off to a good start on your road to wielding the power of the strongest of the electronic signatures - the mighty QESopen in new window. Just follow the steps below and get your first file signed with eID Easy 🚀.

BEFORE YOU CONTINUE

Make sure that you have your eID Easy API credentials at hand as you'll need them in the following steps. You can follow this short guide to obtain the API credentials.

API REFERENCE

In the following guide, we'll use only a small subset of all the available parameters to keep things simple. You can click on the blue endpoint links in this guide to learn more about all the available options. For the full API reference, see: https://documenter.getpostman.com/view/3869493/Szf6WoG1open in new window

1. Prepare the file hash for signing

For that we'll send a server-side POST request to https://id.eideasy.com/api/signatures/prepare-files-for-signingopen in new window

The request body might look something like this:

{
   "secret": "{{secret}}",
   "client_id": "{{client_id}}",
   "container_type": "xades",
   "baseline": "LT",
   "files": [
      {
         "fileName": "example.pdf",
         "mimeType": "application/pdf",
         "fileContent": "w/d9o3efASVID0h/MGFHn+14Qye+fwz+4VEnN939tx8="
      }
   ],
   "signature_redirect": "https://example.localhost/signature-complete",
   "return_available_methods": true,
   "noemails": true
}

Property	Type	Default	Description
client_id	string	undefined	Required. Get from id.eideasy.com after signing up.
secret	string	undefined	Required. Get from id.eideasy.com after signing up.
container_type	string	undefined	Required. Type of the container in which you wish to receive the signature. For hash based asice, use "xades".
files[].fileContent	string	undefined	Required. A base64 encoded document digest to be signed.
files[].fileName	string	undefined	Required. Filename of the document to be signed.
files[].mimeType	string	undefined	Required. mimeType of the document to be signed.
signature_redirect	string	undefined	Optional. URL to where the user will be redirected after successful signing. This is only relevant in case you do not use Signature JSopen in new window for handling the browser-side user interactions.
return_method_configs	boolean	false	Optional. Whether to return the list of available signing method configs in the response.
noemails	boolean	true	Optional. Whether to send notification email or not. True will NOT send notification emails. Note that for API clients created before 2024-08-28, the default value is `false`.

Note: Don’t forget to set header Content-Type: application/json

Prepare the file for signing response

The API responds with a doc_id and a list of signing methods that are available for this signing session like this:

{
   "status": "OK",
   "doc_id": "QLcJD03LUP0S7DUeTGNobQdsiJGfzqRnULrGE0iV",
   "method_configs": [
      {
         "action_type": "mid-signature",
         "supported_countries": [
            "EE"
         ]
      },
      {
         "action_type": "smart-id-signature",
         "supported_countries": [
            "EE",
            "LV",
            "LT"
         ]
      },
      ...
   ]
}

Make a note of the doc_id value you receive (do not use the one in this example, it is expired) as we'll use it in the next steps.

2. Let user sign the hash

IMPORTANT!

For the signature to be valid, you must show the file contents to the use before signing. After signing, you must provide the signed file to the user.

So, you most probably want to have a user interface with a file preview, buttons for selecting different signing methods and elements to handle method specific user interactions. E.g. some signing methods require user input like entering their phone number or personal id code.

If building all that seems like quite a bit of work then you're totally right, it is. That's why we've built a couple of front-end components you can use to handle method specific user interactions and API calls.

Enter the front-end components:

Browser Clientopen in new window - only handles the method specific API calls. Does not include any UI elements. Useful for when you wish to write your own UI elements.
Widgetopen in new window - a full-fledged UI component to handle all the signing methods and their user interactions and API calls. Can be used in Vue 2 and React based web apps and works equally well on plain old HTML pages too.
Signature JSopen in new window - a small browser-side JavaScript library that you can use to handle eID Easy signing flows in a popup window.

As for the current tutorial, we are going to use the Signature JSopen in new window to get up and running quickly. If instead, you wish to handle all the front-end interactions and API calls yourself, take a look at the API Referenceopen in new window for method specific implementation details.

2.1 Setting up the front-end parts

Install the Signature JS:

yarn add @eid-easy/signature-js

npm install @eid-easy/signature-js

We'll then initialize the Signature JS with the following parameters:

const signature = new Signature({
  onSuccess: () => {
    console.log('User has successfully signed the document');
  },
  onFail: (error) => {
    console.log('Signing failed');
  },
});

Property	Type	Default	Description
onSuccess	function	undefined	Required. This function is called when the user has successfully signed the document.
onFail	function	undefined	Required. This function is called when the user cancels or fails to sign the document and is unable to continue with the signing process. Note that this function is not called on validation errors or on other errors that the end user can correct and then proceed.
baseUrl	string	https://id.eaideasy.com	Optional. eID Easy API baseUrl. If you wish to make requests against the sandbox environment, set this to https://test.eideasy.com

You can now call the signature.start method in response to a user action. E.g. when they click a "start signing" button in your UI. Note: it is important to call signature.start inside the user-triggered event handlers, because some browsers (e.g. Firefox) will otherwise block the popup window. See this articleopen in new window for more information.

signature.start({
    clientId: /* your client_id */,
    docId: /* doc_id you received from the /prepare-files-for-signing API call */,
    actionType: 'smart-id-signature',
    country: 'EE',
    language: 'en', // ISO 639-1 two letter language code,
    inputValues: { // optional
        email: 'dummy@dummy.it',
        username: 'testuser',
        phone: '+37212345678',
        idcode: '987654321',
    },
});

Property	Type	Default	Description
clientId	string	undefined	Required. Get from id.eideasy.com after signing up.
docId	string	undefined	Required. doc_id you receive from the /prepare-files-for-signing API call.
actionType	string	undefined	Required. actionType is the identifier of the signing method you wish to use. You can find the available actionTypes for the current signing session in the response body (the `method_configs` property) of the prepare files call we made in step 1.
country	string	undefined	Required. ISO 3166-1 alpha-2open in new window country code. You can find the available countries per each actionType for the current signing session in the response body (the `method_configs` property) of the prepare files call we made in step 1.
language	string	undefined	Optional Two letter ISO 639-1open in new window language code.
inputValues.email	string	undefined	Optional. Signer's email address. This is used to pre-fill the email field in the signing form.
inputValues.username	string	undefined	Optional. Signer's method specific username. This is used to pre-fill the username field in the signing form.
inputValues.phone	string	undefined	Optional. Signer's method specific phone number. This is used to pre-fill the phone number field in the signing form.
inputValues.idcode	string	undefined	Optional. Signers's national id code. This is used to pre-fill the id code field in the signing form.

And we are almost done! Our end-user can now sign the document we prepared for them. After they have completed the signing process we probably want to fetch the signed file and let the end-user download it.

3. Fetch the signature

Wait but how do I know when the user has signed the hash?

If you are using our widget, browser client or signature js you can use the onSuccess callback function to for example send an AJAX request to your backend.
If you're using the method specific endpointsopen in new window directly (without the help of our widget or browser client), then you'll be polling the /complete endpoint.
Additionally, you can log in to your eID Easy admin dashboard and configure the "Signature notification URL" in the "EDIT" > "Notification hooks" view of your website. eID Easy server will send a POST request (that contains singer_id and doc_id) to this url every time a file gets signed.

NOTE for when you are not using Signature JS to handle the browser-side user interactions

Some signing methods (like the Latvian eParaksts Mobile) are redirect based. This means that end-user gets redirected to the method provider´s website to complete the signing process after which they'll be redirected back to the url you provided for signature_redirect in the https://id.eideasy.com/api/signatures/prepare-files-for-signing request. In these cases you can't use the widget's or browser client's onSuccess callback function. Our recommendation is to use a separate view for displaying the signature success. Provide the url of that view in the /prepare-files-for-signing request and redirect the user to that same view in the widget's onSuccess callback. Or in case of SPAs, just render the success view.

Alright, let's fetch the signature. For that, make a POST request to https://id.eideasy.com/api/signatures/download-signed-fileopen in new window:

{
  "secret": "{{secret}}",
  "client_id": "{{client_id}}",
  "doc_id":"{{doc_id}}"
}

doc_id - the same doc_id you got in step "1. Prepare the file for signing"

Example response:

{
   "status": "OK",
   "signed_file_contents": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIH...",
   "filename": "signature.xml",
   "signer_idcode": "30303039914",
   "signer_country": "EE",
   "signer_firstname": "QUALIFIED OK1",
   "signer_lastname": "TESTNUMBER",
   "signing_method": "smart-id-signature"
}

signed_file_contents - signature .xml in base64 encoding.

If the status is not OK, then you should not consider the signature to be verified.

4. Add the signature to an .asice container

You now have the base64 encoded .xml file that contains the signature. The only thing left to do is to create an .asice container, include the original file and add the .xml signature to the container. See this guide on how to do that.

And that’s it. Good job! 🙌 You're now able to use the eID Easy API to collect strong electronic signatures in your projects.

Don't forget to check out our showcase of possible integrations with the eID Easy API at https://demo.eideasy.com/sign-custom-fileopen in new window. Source code available here: https://github.com/eideasy/eid-sample-appopen in new window

# API Based Flow With File Hashes for .asice

# 1. Prepare the file hash for signing

# Prepare the file for signing response

# 2. Let user sign the hash

# 2.1 Setting up the front-end parts

# 3. Fetch the signature