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:

PDF signing error: “Converting the document for signing in PDF format is not available”

If the service call specifies document_format=pdf, but after clicking “Continue” the signing page displays the message “Converting the document for signing in PDF format is not available” and no document preview is shown, then the uploaded file has not been recognised as a PDF. Typically, without the document_format parameter the same file is signed successfully, only in EDOC format.

The cause is usually that the file part of the multipart request has no Content-Type header, or that it is set to application/octet-stream. The service determines the file format precisely from this header, not from the file contents or its extension. Most HTTP clients set the header automatically, which is why the error occurs only when the file is attached as a byte stream or the multipart request is constructed manually.

The solution is to send the file part with Content-Type: application/pdf. To verify this, in the raw request the line Content-Disposition: form-data; name="file"; filename="document.pdf" must be followed by the line Content-Type: application/pdf. The same file will then be signed, and the result is a PAdES PDF.