Storage API

File Upload

Scope
New file adding to the specific file processing session.

Description

The file is attached to the file processing session;
The file description information is returned.

Request
The Service provider's application sends the following GET request using TLS:

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

Authorization
The request must contain an Authorization header with an OAuth Introspect access token obtained via Integration Platform a Service provider's credentials grant flow.

Body

Property	Type	Usage	Description
file	Binary data	Mandatory	File to be uploaded

Example

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

Response
JSON object:

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

Property	Type	Description
data	Object	Data Object
data.includedDocuments	Array	If uploaded file is ASICE (EDOC), list of files included in ASIC container
data.includedDocuments.id	String	Included file identifier, must be used if you need to download current included file
data.includedDocuments.name	String	Included file name
data.includedDocuments.size	Number	Included file size in bytes
data.includedDocuments.type	String	Processed file type. "file" - In case of file or ASICE container
data.id	String	File Identifier (documentId)
data.name	String	File name
data.size	Integer	File size in bytes
data.type	String	Processed file type: "file" - In case of file or ASICE container

Example if uploaded file is not ASICE container

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

Example if ASICE container is uploaded

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

Add Document Digest

Scope
Purpose of the "Add document digest" operation is to avoid file transfering (if there is extra security requirements) out of internal network.

Operation add signable file digest (HASH) and filename to the file processing session.

Only possible for signing ASICE (EDOC) document types.

Description

The file digest and file name is attached to the file processing session;
The file description information is returned.

Request
The Service provider's application sends the following GET request using TLS:

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

Property	Type	Usage	Description
sessionId	String (64)	Mandatory	File processing session identifier

Authorization
The request must contain an Authorization header with an OAuth Introspect access token obtained via Integration Platform a Service provider's credentials grant flow.

Body

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

Property	Type	Usage	Description
files	Array	Mandatory	File digest and name array
files.name	String	Mandatory	The name of the file (with extension) from which the digest was calculated
files.digest	String	Mandatory	Calculated file digest in Base64 encoding. ⚠️ See note below
files.digest_algorithm	String	Mandatory	Used HASH Algorithm (Only SHA256 is supported)
signatureIndex	String	Optional	Signature sequence index, starting with "0", which means the first signature (XAdES signature file name signatures0.xml) If Property is not used, signature index will be "0". ⚠️ If there is planed that file will be signed by more than one signer, this parameter shall be increased by 1 for each next signature. ASICE container can't contain more then one signature with same file name. Otherwise, service provider shall rename signature file before adding it to ASICE container.

🚧
File diggest calculation
⚠️ Only SHA256 at this moment is supported.
💡 Fist calculate SHA256 HASH from the file you need to sign. Then take SHA256 HASH and make HEX to Base64 encoding. For example encoding you can use https://base64.guru/converter/encode/hex

👍
Guidelines for using file digest till ASICE finalizing
Digest preparation and signing

Hash from files to be signed shall be calculated at service provider premises.

Digest shall be encoded from calculated hash (HEX to Base64).

Service provider shall receive authorisation token (Introspect scope) for accessing SignAPI

Request "Add document digest" operation (POST /api-storage/v1.0/{sessionId}/addDocumentDigest)

Request "Calculate Digest" operation (POST /api-sign/v1.0/calculateDigest)

Request "Finalize Signing" operation (POST /api-sign/v1.0/finalizeSigning)

Request "File list" operation (GET /api-session/v1.0/{sessionId}/list) - get ASICE container "documentId" property

Request "File download" operation (GET /api-session/v1.0/{sessionId}/{documentId}) - download signed ASICE container.

Open container with zip processing tools (probably need to rename extension to ".zip").

Add file, from which digest was calculated to container's root folder.

When file is added - change extension back to ".edoc" or ".asice" if needed.

Adding additional signature to existing ASICE container
(in case when file digest is signed by more than one signer)

If you have already signed ASICE with at least one signature, and you don't have stored signed file/s digest:

Unpack ASICE container - extract file/s to be signed;

Follow steps 1 to 9 from "Digest preparation and signing";

Go to "META-INF" folder and extract signature XML file (Shall contain "signatures" name within file name (signatures1.xml));

Open existing ASICE (where you want to add signature);

Open "META-INF" folder:

Check, if folder did not contain signature file with same filename as extracted in step 4:
a. if contains, rename index of signature XML file extracted in step 4

Add signature XML file to the "META-INF" folder

When signature XML file is added - change extension back to ".edoc" or ".asice" if needed.

Example with one file digest and name

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"
}

Example with multiple file digest and name

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"
}

Response
JSON object:

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

Property	Type	Description
data	Object	Data Object
data.id	String	File Identifier (documentId)
data.name	String	File name
data.size	Integer	File size in bytes (always will be "0" since filename and digest was added)
data.type	String	Processed file type: "hash" - In case if file digest and file name is added to session

Example of one file digest and name

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

Example of multiple file digest and name

{
    "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"
        }
    ]
}

File List

Scope
Retrieve a list of files in a file processing session.

Description

Returns information about files stored in the file processing session:
1.1. If the session files are not yet signed, a list of all files is returned;
1.2. If the session files are signed, the signed file (EDOC / PDF) is returned.

Request
The Service provider's application sends the following GET request using TLS:

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

Property	Type	Usage	Description
sessionId	String (64)	Mandatory	File processing session identifier

Authorization
The request must contain an Authorization header with an OAuth Introspect access token obtained via Integration Platform a Service provider's credentials grant flow.

Example

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

Response
JSON object:

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

Property	Type	Description
data	Object	Data Object
data.includedDocuments	Array	Files included in signed container
data.includedDocuments.id	String	Included file Identifier (documentId)
data.includedDocuments.name	String	Included file name
data.includedDocuments.size	Integer	Included file size in bytes
data.includedDocuments.type	String	Processed file type: "file" - In case of file or ASICE container "hash" - In case if file digest and file name is added to session
data.id	String	File Identifier (documentId)
data.name	String	File name File size in bytes
data.size	String	File size in bytes
data.type	String	Processed file type: "file" - In case of file or ASICE container "hash" - In case if file digest and file name is added to session

Examples

Example of ASICE container containing one file

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

Example of ASICE container when file digest and name is signed

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

File Download

Scope
Download a file from the file processing session

Description
Returns a requested file.

Request
The Service provider's application sends the following GET request using TLS:

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

Property	Type	Usage	Description
sessionId	String (64)	Mandatory	File processing session identifier
documentId	String (64)	Mandatory	Document identifier, received from "upload" or "list" operation as "id" property

Parameters

Name	Type	Usage	Description
type=asice	query	optional	Returns .asice if signed document is .edoc

Authorization
The request must contain an Authorization header with an OAuth Introspect access token obtained via Integration Platform a Service provider's credentials grant flow.

Example

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

Response
Binary object

Property	Type	Description
File	Binary data	Requested file

Example with type=asice

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

Response
Binary object

Property	Type	Description
File	Binary data	Requested file

File Delete

Scope
Delete a file in a file processing session.

Description
The specified file is deleted from the session.

Request
The Service provider's application sends the following GET request using TLS:

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

Property	Type	Usage	Description
sessionId	String (64)	Mandatory	File processing session identifier
documentId	String (64)	Mandatory	Document identifier, received from "upload" operation as "id" property

Authorization
The request must contain an Authorization header with an OAuth Introspect access token obtained via Integration Platform a Service provider's credentials grant flow.

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

Response
JSON object:

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

Property	Type	Description
documentId	String	Document identifier, received from "upload" operation as "id" property

Example

{
    "data": "Document cc8bcb560bbfee4c190433ea63c549d1 deleted"
}

Storage API

File Upload

Add Document Digest

🚧
File diggest calculation

👍
Guidelines for using file digest till ASICE finalizing

Digest preparation and signing

Adding additional signature to existing ASICE container

File List

File Download

File Delete

File Upload

Add Document Digest

🚧File diggest calculation

👍Guidelines for using file digest till ASICE finalizing

Digest preparation and signing

Adding additional signature to existing ASICE container

File List

File Download

File Delete

🚧
File diggest calculation

👍
Guidelines for using file digest till ASICE finalizing