PortalSign integration guidelines

Service Call Parametrs

UML Data flow diagram

Comments regarding diagram

1. The external system uploads file(s) together with configuration parameters (return URL, format) to the PortalSign service. Basic authorization parameters must be specified in the request.

2. The PortalSign service returns a "redirect" HTTP response to the signing process URI in the portal (redirect(Uri(s"$portalHost/parakstit/${process.uuid}"), StatusCodes.SeeOther)).

3. The external system returns a "redirect" HTTP response to the client browser.

4. The client browser opens the corresponding signing process in the portal.

5. The standard signing process takes place in the portal, as described in other documents.

6. When the user clicks the button with the return URI in the browser, the user's browser goes to the external system.

7. The external system requests download of the signed document using process_uuid

   https://www.eparaksts.lv/api/v1/portal-sign/\{process.uuid}/download-document

8. The PortalSign service returns the electronically signed file(s).

9. The external system deletes the uploaded files by calling the DELETE method with the process ID: https://www.eparaksts.lv/api/v1/portal-sign/\{process.uuid

If, in step 4, the pageeparaksts.lv/parakstit/{process_uuid} is unavailable, the user will be redirected to the URL specified in the return_to_uri parameter, with the additional parameter error=service_not_available.

If, in step 5, the user cancels the signing process by clicking "Cancel", the user will be redirected to the URL specified in the return_to_uri parameter, with the additional parameter error=user_canceled.

SERVICE CALL SAMPLE (Postman JSON format)

The PortalSign service can also be tested using POSTMAN JSON requests. The service is available in the production environment. This means that a production environment eID card or eParaksts mobile can be used for testing.

Postman request to the PortalSign service (JSON can be imported as a Postman collection. After import, it will be necessary to specify a valid username and password in the Authorization section, as well as the file or files to be signed).

{
  "info": {
    "_postman_id": "279ac0cf-06ba-44bd-bdff-9b2a488ddde4",
    "name": "eparaksts PortalSign",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "PortalSign sample request",
      "protocolProfileBehavior": {
        "followRedirects": false
      },
      "request": {
        "auth": {
          "type": "basic",
          "basic": [
            {
              "key": "password",
              "value": "Parole",
              "type": "string"
            },
            {
              "key": "username",
              "value": "Lietotājvārds",
              "type": "string"
            }
          ]
        },
        "method": "POST",
        "header": [],
        "body": {
          "mode": "formdata",
          "formdata": [
            {
              "key": "document_format",
              "value": "pdf",
              "type": "text"
            },
            {
              "key": "sign_mode",
              "value": "single",
              "type": "text"
            },
            {
              "key": "flow",
              "value": "portal",
              "type": "text"
            },
            {
              "key": "return_to_uri",
              "value": "https://www.eparaksts.lv",
              "type": "text"
            },
            {
              "key": "return_to_uri_title",
              "value": "Return to your system",
              "type": "text"
            },
            {
              "key": "file",
              "type": "file",
              "src": "/home/testing.pdf"
            }
          ]
        },
        "url": {
          "raw": "https://www.eparaksts.lv/api/v1/portal-sign/upload-and-sign",
          "protocol": "https",
          "host": [
            "www",
            "eparaksts",
            "lv"
          ],
          "path": [
            "api",
            "v1",
            "portal-sign",
            "upload-and-sign"
          ]
        },
        "description": "Portal flow for signing a PDF document without changing the file format."
      },
      "response": []
    }
  ]
}

Postman response to the above request:

The response to the request can be found under <a href=
https://www.eparaksts.lv/portal-sign/7f37d82e-4b16-495c-b077-64197e330176
this URI</a> using a GET method.

A new signing process with a unique identifier has been created in the system

(example: 7f37d82e-4b16-495c-b077-64197e330176).

Next, it is necessary to paste the link https://www.eparaksts.lv/portal-sign/7f37d82e-4b16-495c-b077-64197e330176 into the browser and perform document signing.

After signing the document, the user arrives at the “Document is signed” window, where the “Return to system” button must be pressed. The user is redirected to the page specified as return_to_uri in the request.

The signed document can be downloaded from the link: https://www.eparaksts.lv/api/v1/portal‑sign/\{process_uuid}/download-document

After downloading the document, the external system deletes the document by calling the DELETE method with the process ID: https://www.eparaksts.lv/api/v1/portal-sign/{process_uuid}

SERVICE CALL SAMPLE (http command line client)

http --ignore-stdin --form --timeout 3600 POST \
  'https://www.eparaksts.lv/api/v1/portal-sign/upload-and-sign' \
  'return_to_uri'='https://company.lv/application1/form1.html' \
  'file'@/home/test_faili/dokuments.pdf \
  Authorization:'Basic ZGVtbzpkZW1v'

Example response:

HTTP/1.1 303 See Other
Location: https://www.eparaksts.lv/parakstit/a1cce99d-7678-45f2-9c95-975ef5659509
The response to the request can be found under <a href=https://www.eparaksts.lv/parakstit/a1cce99d-7678-45f2-9c95-975ef5659509 >this URI</a> using a GET method.

In this scenario, executing the GET request or opening the link in a browser opens the portal signing flow.

After electronically signing the file, the user is redirected to the page specified as the return URL in the service call.

Response status codes and explanation

Example of an incorrect call:

The following request does not include the mandatory file parameter:

http --ignore-stdin --form --timeout 3600 POST \
  'https://www.eparaksts.lv/api/v1/portal-sign/upload-and-sign' \
  Authorization:'Basic ZGVtbzpkZW1v'

Example response:

HTTP/1.1 415 Unsupported Media Type

The request's Content-Type [application/x-www-form-urlencoded] is not supported. Expected:

multipart/form-data

Example of HTTP status code 502 from Postman: