PortalSign integrācijas vadlīnijas

Pakalpojuma izsaukuma parametri

UML datu plūsmas diagramma

Komentāri par diagrammu

1. Ārējā sistēma augšupielādē failu(s) kopā ar konfigurācijas parametriem (atgriešanās url, formāts) uz PortalSign pakalpojumu. Pieprasījumā jānorāda Basic authorization parametri.

2. PortalSign pakalpojums atgriež "redirect" http atbildi uz procesa parakstīšanas uri portālā (redirect(Uri(s"$portalHost/parakstit/${process.uuid}"), StatusCodes.SeeOther)).

3. Ārējā sistēma atgriež "redirect" http atbildi klienta pārlūkam.

4. Klienta pārlūks dodas uz attiecīgo parakstīšanas procesu portālā.

5. Notiek standarta parakstīšanas process portālā, kas, aprakstīts citos dokumentos.

6. Kad lietotājs pārlūkā klikšķina uz pogu ar atgriešanās uri, lietotāja pārlūks dodas uz ārējo sistēmu.

7. Ārējā sistēma pieprasa lejuplādēt parakstīto dokumentu pēc process_uuid

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

8. Elektroniski parakstīts fails vai faili tiek atgriezti ar PortalSign pakalpojumu.

9. Ārējā sistēma, ar procesa ID izsaucot DELETE metodi, veic augšupielādēto failu dzēšanuhttps://www.eparaksts.lv/api/v1/portal-sign/\{process.uuid

Ja solī 4. lietotājam nav pieejama lapaeparaksts.lv/parakstit/{process_uuid} tad lietotājs tiks novirzīts uz lapu, kas norādīts parametrā return_to_uri, ar papildus pievienotu parametru error=service_not_available.

Ja solī 5. lietotājs neparaksta dokumentu un nospiež "Atcelt", tad lietotājs tiks novirzīts uz lapu, kas norādīts parametrā return_to_uri, ar papildus pievienotu parametru error= user_canceled.

PAKALPOJUMA IZSAUKUMA PARAUGS (Postman JSON formāts)

Pakalpojuma PortalSign testēšanai var izmantot arī POSTMAN JSON izsaukumus. Pakalpojums ir pieejams produkcijas vidē. Tas nozīmē, ka testējot var izmantot produkcijas vides eID karti vai eParaksts mobile.

Postman pieprasījums PortalSign pakalpojumam (JSON failu var importēt kā Postman kolekciju. Pēc importēšanas Authorization sadaļā jānorāda derīgs lietotājvārds un parole, kā arī parakstāmais fails vai faili).

{
  "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 atbilde uz iepriekš minēto pieprasījumu:

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.

Sistēmā ir izveidots jauns parakstīšanas process ar unikālu identifikatoru

(piemēram, 7f37d82e-4b16-495c-b077-64197e330176).

Tālāk nepieciešams pārlūkā iekopēt saiti https://www.eparaksts.lv/portal-sign/7f37d82e-4b16-495c-b077-64197e330176 pārlūkā un veikt dokumenta parakstīšanu.

Pēc dokumenta parakstīšanas lietotājs nonāk logā “Dokuments ir parakstīts”, kur jāspiež poga “Atgriezties sistēmā”. Lietotājs nokļūst lapā, kas pieprasījumā tika norādīts kā return_to_uri.

Parakstīto dokumentu var lejupielādēt no saites: https://www.eparaksts.lv/api/v1/portal‑sign/\{process_uuid}/download-document

Pēc dokumenta lejupielādes ārējā sistēma veic dokumenta dzēšanu, ar procesa ID izsaucot DELETE metodi: https://www.eparaksts.lv/api/v1/portal-sign/{process_uuid}

PAKALPOJUMA IZSAUKUMA PARAUGS (http komandrindas klients)

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'

Atbildes piemērs:

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.

Šajā scenārijā izpildot GET pieprasījumu vai atverot saiti pārlūkā tiek atvērta portāla parakstīšanas plūsma.

Pēc faila elektroniskas parakstīšanas, lietotājs tiek novirzīts uz lapu, kura pakalpojuma izsaukumā norādīta kā atgriešanās URL.

Atbildes statusa kodi un skaidrojums

Kļūdaina izsaukuma piemērs:

Pieprasījums nesatur obligāto file parameteru:

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

Atbildes piemērs:

HTTP/1.1 415 Unsupported Media Type

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

multipart/form-data

HTTP koda 502 piemērs no Postman: