Krātuves API

Failu augšupielāde

Darbības joma
Jauns fails tiek pievienots konkrētajai failu apstrādes sesijai.

Apraksts

Fails tiek pievienots faila apstrādes sesijai;
Tiek atgriezta faila apraksta informācija.

Pieprasījums
Pakalpojuma sniedzēja lietojumprogramma, izmantojot TLS, nosūta šādu GET pieprasījumu:

PUT /api-storage/v1.0/{sessionId}/upload

Autorizācija

Pieprasījumā jāiekļauj Authorization galvene ar OAuth Introspekta piekļuves marķieri (Introspect access token), kas iegūts no e-Identitātes platformas, izmantojot pakalpojumu sniedzēja akreditācijas datu piešķiršanas plūsmu (credentials grant flow).

Pamatteksts (body)

Paramters	Tips	Lietošana	Apraksts
fails	Binārie dati	Obligāts	Augšuplādējamais fails

Piemērs

PUT /api-storage/v1.0/77740b301f0880ef498cb1e474e8060b3e538cfeea8ebf508c2bad4b72b56a87/upload HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv

*Atbilde
JSON objekts:

{
    "data": [
                {
            "includedDocuments": [
                {
                  "id": {String},
                   "name": {String},
                   "size": {Number},
                    "type": {String}
                }
            ],
            "id": {String},
            "name": {String},
            "size": {Number},
            "type": {String}
               }
            ]
}

Paramters	Tips	Apraksts
`data`	Objekts (Object)	Datu objekts
`data.includedDocuments`	Masīvs (Array)	Ja augšupielādētais fails ir ASiC-E (EDOC), ASiC-E konteinerā iekļauto failu saraksts
`data.includedDocuments.id`	Virkne (String)	Iekļautā faila identifikators ir jāizmanto, ja nepieciešams lejupielādēt pašreizējo iekļauto failu
`data.includedDocuments.name`	Virkne (String)	Iekļautā faila nosaukums
`data.includedDocuments.size`	Numurs (Number)	Iekļautā faila lielums baitos
`data.includedDocuments.type`	Virkne (String)	Apstrādātā faila tips. "file" — faila vai ASiC-E konteinera gadījumā
`data.id`	Virkne (String)	Faila identifikators (documentId)
`data.name`	Virkne (String)	Faila nosaukums
`data.size`	Vesels skaitlis (Integer)	Faila lielums baitos
`data.type`	Virkne (String)	Apstrādātā faila tips: "file" — faila vai ASiC-E konteinera gadījumā

Piemērs, ja augšupielādētais fails nav ASiC-E konteiners

{
    "data": {
        "id": "cc8bcb560bbfee4c190433ea63c549d1",
        "name": "test.doc",
        "size": 41280,
        "type": "file"
           }
}

Piemērs, ja ir augšupielādēts ASiC-E konteiners

{
    "data": {
        "includedDocuments": [
            {
                "id": "3cbc266934776e581bcb406f15bb5ffd",
                "name": "Receipt.doc",
                "size": 22528,
                "type": "file"
           }
        ],
        "id": "23a3abe0a211478ae55554649178568e",
        "name": "Receipt.edoc",
        "size": 14805,
        "type": "file"
           }
}

Pievieno dokumenta īssavilkumu (digest)

Darbības joma

Darbības "Pievienot dokumentu īssavilkumu" mērķis ir izvairīties no failu pārsūtīšanas (ja ir papildu drošības prasības) no iekšējā tīkla.

Darbība pievieno parakstāmā faila īssavilkumu (HASH) un faila nosaukumu faila apstrādes sesijai.

Iespējama tikai ASiC-E (EDOC) dokumentu tipu parakstīšanai.

Apraksts

Faila īssavilkums (digest) un faila nosaukums ir pievienots faila apstrādes sesijai;
Tiek atgriezta faila apraksta informācija.

Pieprasījums
Pakalpojuma sniedzēja lietojumprogramma, izmantojot TLS, nosūta šādu GET pieprasījumu:

POST /api-storage/v1.0/{sessionId}/addDocumentDigest

Parametrs	Tips	Lietošana	Apraksts
`sessionId`	Virkne (64) (String (64))	Obligāts	Failu apstrādes sesijas identifikators

Autorizācija
Pieprasījumā jāiekļauj Authorization galvene ar OAuth Introspekta piekļuves marķieri (Introspect access token), kas iegūts no e-Identitātes platformas, izmantojot pakalpojumu sniedzēja akreditācijas datu piešķiršanas plūsmu (credentials grant flow).

Pamatteksts (body)

{
    "files": [
            {
                "name": {String},
                "digest": {String},
                "digest_algorithm": {String}
            }
        ],
    "signatureIndex": {String}
}

Parametrs	Tips	Lietošana	Apraksts
`files`	Masīvs (Array)	Obligāts	Failu īssavilkums un nosaukumu masīvs
`files.name`	Virkne (String)	Obligāts	Faila nosaukums (ar paplašinājumu), no kura tika aprēķināts īssavilkums
`files.digest`	Virkne (String)	Obligāts	Aprēķināts faila īssavilkums Base64 kodējumā. ⚠️ Skatīt piezīmi zemāk
`files.digest_algorithm`	Virkne (String)	Obligāts	Izmantotais HASH algoritms (tiek atbalstīts tikai SHA256)
`signatureIndex`	Virkne (String)	Neobligāti	Parakstu secības indekss, kas sākas ar "0", kas nozīmē pirmo parakstu (XAdES paraksta faila nosaukums signatures0.xml) Ja Parametrs netiek izmantots, paraksta indekss būs "0". ⚠️ Ja ir plānots, ka failu parakstīs vairāk nekā viens parakstītājs, šis parametrs tiek palielināts par 1 katram nākamajam parakstam. ASiC-E konteinerā nedrīkst būt vairāk par vienu parakstu ar tādu pašu faila nosaukumu. Pretējā gadījumā pakalpojuma sniedzējam ir jāpārdēvē paraksta fails pirms pievienošanas ASiC-E konteineram.

🚧
Failu īssavilkuma (digest) aprēķins
⚠️ Šobrīd tiek atbalstīts tikai SHA256
💡 Vispirms aprēķiniet SHA256 HASH no faila, kas jāparaksta. Pēc tam paņemiet SHA256 HASH un pārveidojiet HEX uz Base64 kodējumā. Kā piemēru kodēšanai var izmantot https://base64.guru/converter/encode/hex

👍
Failu īssavilkuma izmantošanas vadlīnijas līdz ASiC-E pabeigšanai
Īssavilkuma (digest) sagatavošana un parakstīšana

Parakstāmo failu jaucējvērtība (hash) jāaprēķina pakalpojuma sniedzēja infrastruktūrā.;

Īsavilkums ir jākodē no aprēķinātās jaucējvērtības (no HEX uz Base64);

Pakalpojuma sniedzējs saņem autorizācijas marķieri (Introspect tvērums), lai piekļūtu SignAPI;

Pieprasīt darbību “Pievieno dokumenta īssavilkumu (digest)” (POST /api-storage/v1.0/{sessionId}/addDocumentDigest);

Pieprasīt darbību “Aprēķināt īssavilkumu” (POST /api-sign/v1.0/calculateDigest);

Pieprasīt darbību “Pabeigt parakstīšanu” (POST /api-sign/v1.0/finalizeSigning);

Pieprasīt operāciju "Failu saraksts" (GET /api-session/v1.0/{sessionId}/list) - iegūt ASiC-E konteinera parametru "documentId";

Pieprasīt operāciju “Faila lejupielāde”(GET /api-session/v1.0/{sessionId}/{documentId}) - lejupielādējiet parakstītu ASiC-E konteineru;

Atveriet konteineru ar ZIP apstrādes rīkiem (iespējams, paplašinājums ir jāpārdēvē uz “.zip”);

Pievieno konteinera saknes mapei failu, no kura tika aprēķināts īssavilkums.;

Kad fails ir pievienots, ja nepieciešams, mainiet paplašinājumu atpakaļ uz ".edoc" vai ".asice".

Papildu paraksta pievienošana esošajam ASiC-E konteineram
(gadījumā, ja failu īssavilkumu ir parakstījis vairāk nekā viens parakstītājs)

Ja jau esat parakstījis ASiC-E ar vismaz vienu parakstu un jums nav saglabāts parakstīts fails/-i īssavilkums;

Izpakot ASiC-E konteineru - izvilkt parakstāmo failu/s;

Izpildiet 1. līdz 9. darbību sadaļā "Īssavilkuma sagatavošana un parakstīšana";

Dodieties uz mapi "META-INF" un izvelciet paraksta XML failu (faila nosaukumā (signatures1.xml) ir jāietver "parakstu" nosaukums);

Atveriet esošo ASiC-E (kur vēlaties pievienot parakstu);

Atveriet mapi "META-INF";

Pārbaudiet, vai mapē nebija paraksta faila ar tādu pašu faila nosaukumu, kāds tika izvilkts 4. darbībā: a. ja satur, pārdēvējiet paraksta XML faila indeksu, kas iegūts 4. darbībā;

Pievienojiet paraksta XML failu mapei "META-INF;

Kad ir pievienots paraksta XML fails, ja nepieciešams, mainiet paplašinājumu atpakaļ uz ".edoc" vai ".asice".

Piemērs ar viena faila īssavilkumu un nosaukumu

POST /api-storage/v1.0/77740b301f0880ef498cb1e474e8060b3e538cfeea8ebf508c2bad4b72b56a87/addDocumentDigest HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv
{
    "files": [
            {
                "name": "10-10.pdf",
                "digest": "u69UTpGwlSfNpIMYhXPIa612ELFu+Y8zWaVCApzlQdE=",
                "digest_algorithm": "SHA256"
            }
        ],
    "signatureIndex": "0"
}

Piemērs ar vairāku failu īssavilkumu un nosaukumu

POST /api-storage/v1.0/77740b301f0880ef498cb1e474e8060b3e538cfeea8ebf508c2bad4b72b56a87/addDocumentDigest HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv
{
    "files": [
            {
                "name": "10-10.pdf",
                "digest": "u69UTpGwlSfNpIMYhXPIa612ELFu+Y8zWaVCApzlQdE=",
                "digest_algorithm": "SHA256"
            },
            {
                "name": "10-11.docx",
                "digest": "u69UTpGwlSfNpIMYhXPIa612ELFu+Y8zWaVCApzlQdB=",
                "digest_algorithm": "SHA256"
            },
            {
                "name": "10-12.pdf",
                "digest": "u69UTpGwlSfNpIMYhXPIa612ELFu+Y8zWaVCApzlQdC=",
                "digest_algorithm": "SHA256"
            }
        ],
    "signatureIndex": "0"
}

Atbilde
JSON objekts:

{
    "data": [
        {
            "id": {String},
            "name": {String},
            "size": {Number},
            "type": {String}
        }
    ]
}

Paramters	Tips	Apraksts
`data`	Objekts (Object)	Datu objekts
`data.id`	Virkne (String)	Faila identifikators (documentId)
`data.name`	Virkne (String)	Faila nosaukums
`data.size`	Vesels skaitlis (Integer)	Faila lielums baitos (vienmēr būs "0", kopš tika pievienots faila nosaukums un īssavilkums)
`data.type`	Virkne (String)	Apstrādātā faila tips: "hash" - gadījumā, ja sesijai tiek pievienots faila īssavilkums un faila nosaukums

Viena faila īssavilkuma un nosaukuma piemērs

{
    "data": [
        {
            "id": "6921c9e8afd22a9a391d5318e08da85d",
            "name": "10-10.pdf",
            "size": 0,
            "type": "hash"
        }
    ]
}

Vairāku failu īssavilkuma un nosaukuma piemērs

{
    "data": [
        {
            "id": "6921c9e8afd22a9a391d5318e08da85d",
            "name": "10-10.pdf",
            "size": 0,
            "type": "hash"
        },
        {
            "id": "9f1702526028570f5f6c2813417797a0",
            "name": "10-11.docx",
            "size": 0,
            "type": "hash"
        },
        {
            "id": "5d05429bc930622ee008ed4ded1b2de1",
            "name": "10-12.pdf",
            "size": 0,
            "type": "hash"
        }
    ]
}

Failu saraksta iegūšana

Darbības joma
Retrieve a list of files in a file processing session.

Apraksts

Atgriež informāciju par failiem, kas saglabāti failu apstrādes sesijā:

1.1. Ja sesijas faili vēl nav parakstīti, tiek atgriezts visu failu saraksts;

1.2. Ja sesijas faili ir parakstīti, tiek atgriezts parakstītais fails (EDOC / PDF).

Pieprasījums
Pakalpojuma sniedzēja lietojumprogramma, izmantojot TLS, nosūta šādu GET pieprasījumu:

GET /api-storage/v1.0/{sessionId}/list

Parametrs	Tips	Lietošana	Apraksts
`sessionId`	Virkne (64) (String (64))	Obligāts	Failu apstrādes sesijas identifikators

Piemērs

GET /api-storage/v1.0/77740b301f0880ef498cb1e474e8060b3e538cfeea8ebf508c2bad4b72b56a87/list HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv

Atbilde
JSON objekts:

{
    "data": {
        "includedDocuments": [
            {
                "id": {String},
                "name": {String},
                "size": {Number},
                "type": {String}
           }
        ],
        "id": {String},
        "name": {String},
        "size": {Number},
        "type": {String}
           }
}

Parametrs	Tips	Apraksts
`data`	Objekts (Object)	Datu objekts
`data.includedDocuments`	Masīvs (Array)	Faili, kas iekļauti parakstītajā konteinerā
`data.includedDocuments.id`	Virkne(String)	Iekļautā faila identifikators (documentId)
`data.includedDocuments.name`	Virkne(String)	Iekļautā faila nosaukums
`data.includedDocuments.size`	Vesels skaitlis (Integer)	Iekļautā faila lielums baitos
`data.includedDocuments.type`	Virkne(String)	Apstrādātā faila tips: "file" — faila vai ASiC-E konteinera gadījumā "hash" — gadījumā, ja sesijai tiek pievienots faila īssavilkums un faila nosaukums
`data.id`	Virkne(String)	Faila identifikators (documentId)
`data.name`	Virkne(String)	Faila nosaukums
`data.size`	Virkne(String)	Faila lielums baitos
`data.type`	Virkne(String)	Apstrādātā faila tips: "file" — faila vai ASiC-E konteinera gadījumā "hash" — gadījumā, ja sesijai tiek pievienots faila īssavilkums un faila nosaukums

Piemēri

ASiC-E konteinera piemērs, kurā ir viens fails

{
    "data": {
        "includedDocuments": [
            {
                "id": "3cbc266934776e581bcb406f15bb5ffd",
                "name": "Receipt.doc",
                "size": 22528,
                "type": "file"
            }
        ],
        "id": "23a3abe0a211478ae55554649178568e",
        "name": "Receipt.edoc",
        "size": 14805,
        "type": "file"
           }
}

ASiC-E konteinera piemērs, kad faila īssavilkums un nosaukums ir parakstīts

{
    "data": [
        {
            "includedDocuments": [
                {
                    "id": "dc7a737f0d3dcb288902ed1df4942ee3",
                    "name": "Report.docx",
                    "size": 0,
                    "type": "hash"
                }
            ],
            "id": "592ad9f0c4f9356db0d0d3716a87d5f1",
            "name": "DigestEdoc.edoc",
            "size": 8891,
            "type": "file"
        }
    ]
}

Failu lejupielāde

Darbības joma
Lejupielādējiet failu no failu apstrādes sesijas

Apraksts
Atgriež pieprasīto failu.

Pieprasījums
Pakalpojuma sniedzēja lietojumprogramma, izmantojot TLS, nosūta šādu GET pieprasījumu:

GET /api-storage/v1.0/{sessionId}/{documentId}

Parametrs	Tips	Lietošana	Apraksts
`sessionId`	Virkne (64) (String (64))	Obligāts	Failu apstrādes sesijas identifikators
`documentId`	Virkne (64) (String (64)	Obligāts	Dokumenta identifikators, kas saņemts no darbības upload vai list kā parametrs id.

Parameteri

Nosaukums	Tips	Lietošana	Apraksts
`type=asice`	vaicājums (query)	neobligāts	Atgriež .asice, ja parakstītais dokuments ir .edoc

Piemērs

GET /api-storage/v1.0/cd6afb8b7e9fd6aa2b2ef7b981fa98cb59128fdef6c064f74dc9cef529a79d17/cc8bcb560bbfee4c190433ea63c549d1
HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv

Atbilde
Binārs objekts

Parametrs	Tips	Apraksts
`File`	Binārie dati	Pieprasītais fails

Piemērs ar type=asice

GET /api-storage/v1.0/866fc84c73b4cd6ed971aeabd2f1a7240c5f058d30f452a697ffd35798fd1419/c22a148157558425df5d97359b00d1c9?type=asice 
HTTP/1.1
Authorization: Bearer 26e899d3eb763d77b0f12707ae66bda0ffbe3997e43860d412dbec04e344abd7
Host: signapi-prep.eparaksts.lv

Atbilde
Binārs objekts

Parametrs	Tips	Apraksts
`File`	Binārie dati	Pieprasītais fails

Failu Dzēst

Darbības joma
Dzēsiet failu no failu apstrādes sesijas.

Apraksts
Norādītais fails tiek izdzēsts no sesijas.

Pieprasījums
Pakalpojuma sniedzēja lietojumprogramma, izmantojot TLS, nosūta šādu GET pieprasījumu:

DELETE /api-storage/v1.0/{sessionId}/{documentId}

Parametrs	Tips	Lietošana	Apraksts
`sessionId`	Virkne (64) (String (64))	Obligāts	Failu apstrādes sesijas identifikators
`documentId`	Virkne (64) (String (64))	Obligāts	Dokumenta identifikators, kas saņemts no darbības upload kā parametrs id.

DELETE /api-storage/v1.0/cd6afb8b7e9fd6aa2b2ef7b981fa98cb59128fdef6c064f74dc9cef529a79d17/cc8bcb560bbfee4c190433ea63c549d1
HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv

Atbilde
JSON objekts

{
    "data": "Document {documentId} deleted"
}

Parametrs	Tips	Apraksts
`documentId`	Virkne(String)	Dokumenta identifikators, kas saņemts no darbības upload kā parametrs id.

Piemērs

{
    "data": "Document cc8bcb560bbfee4c190433ea63c549d1 deleted"
}