Datafiles API description

Introduction

This document describes the methods used for datafile container manipulation.

Creating container

Method for creating container structure.

Method	URL
POST	/containers

Request parameters

Parameter	Type	Mandatory	Description
containerName	String	+	Name of the container.
dataFiles	Array	+	Array containing data file objects.
dataFile	Object	+	Object containing information of data files.
dataFile.fileName[0]	String	+	Name of the data file. Folder structure for data files is not supported.
dataFile.fileContent[0]	String	+	PLACEHOLDER

Response parameters

Parameter	Type	Mandatory	Description
containerId	String	+	Container ID that is used to identify the container in use.

Upload container

Method for uploading datafile container.

Method	URL
POST	/upload/containers

Request parameters

Parameter	Type	Mandatory	Description
containerName	String	+	Name of the container.
container	String	+	Base64 encoded container.

Response parameters

Parameter	Type	Mandatory	Description
containerId	String	+	Container ID that is used to identify the container in use.

Add datafiles to unsigned container

Method for adding data files to container. NB! It is possible to add data files only to unsigned container!

Method	URL
POST	/containers/{containerId}/datafiles

Request parameters

Parameter	Type	Mandatory	Description
dataFiles	Array	-	Array containing data file objects.
dataFile	Object	+	Object containing information of data files.
dataFile[0].fileName	String	+	Name of the data file. Folder structure for data files is not supported.
dataFile[0].fileContent	String	+	PLACEHOLDER

Response parameters

Parameter	Type	Mandatory	Description
result	String	+	OK on success.

Get data files list

Method for retrieving container data file list.

Method	URL
GET	/containers/{containerId}/datafiles

Response parameters

Parameter	Type	Mandatory	Description
dataFiles	Array	-	Array containing data file objects.
dataFile	Object	+	Object containing data files information.
dataFile[0].fileName	String	+	Name of the data file.
dataFile[0].fileContent	String	+	PLACEHOLDER

Delete datafile from unsigned container

Method for deleting data files from container. NB! It is possible to remove data files only from unsigned container!

Method	URL
DELETE	/containers/{containerId}/datafiles/{datafileName}

Response parameters

Parameter	Type	Mandatory	Description
result	String	+	OK on succes.

Start remote signing

Method for generating data to be signed externally

Method	URL
POST	/containers/{containerId}/remotesigning

Request parameters

Parameter	Type	Mandatory	Description
signingCertificate	String	+	DER encoded X.509 signers certificate in Base64.
signatureProfile	String	+	Profile of the signature. Available values LT - TimeStamp based and LT_TM - TimeMark based signatures.
roles	Array	-	Array of strings describing the signer role.
signatureProductionPlace	object	-	Object containing signing location.
signatureProductionPlace.countryName	String	-	Signing country.
signatureProductionPlace.city	String	-	Signing city.
signatureProductionPlace.stateOrProvince	String	-	Signing state or province.
signatureProductionPlace.postalCode	String	-	Signing postal code.

Response parameters

Parameter	Type	Mandatory	Description
generatedSignatureId	String	+	Signature ID needed for finalization of signature.
dataToSign	String	+	Data to be signed on client side. XML structure to be signed encoded in Base64.
digestAlgorithm	String	+	Digest algorithm used to calculate dataToSign. Service uses SHA512.

Finalize remote signing

Method for returning signature value to service

Method	URL
PUT	/containers/{containerId}/remotesigning/{signatureId}

Request parameters

Parameter	Type	Mandatory	Description
signatureValue	String	+	Signature value created by client encoded in Base64. Signature must be created using the algorithm returned in POST /containers/{containerId}/remotesigning response (SHA512).

Response parameters

Parameter	Type	Mandatory	Description
result	String	+	OK is returned.

Start Mobile-ID signing

Method for starting Mobile-ID signing of container

Method	URL
POST	/containers/{containerId}/mobileidsigning

Request parameters

Parameter	Type	Mandatory	Description
personIdentifier	String	+	Signers personal national identification code.
phoneNo	String	+	Signers phone number with +372 prefix.
language	String	+	Language for user dialog in mobile phone. 3-character capitalized acronyms are used. Possible values: ENG, EST, RUS, LIT.
messageToDisplay	String	-	Text displayed in addition to ServiceName and before asking PIN2. Maximum length is 40 bytes. In case of Latin letters, this means also a 40 character long text, but Cyrillic characters may be encoded by two bytes and you will not be able to send more than 20 symbols.
signatureProfile	String	+	Profile of the signature. Available values LT - TimeStamp based and LT_TM - TimeMark based signatures.
roles	Array	-	Array of strings describing the signer role.
signatureProductionPlace	object	-	Object containing signing location.
signatureProductionPlace.countryName	String	-	Signing country.
signatureProductionPlace.city	String	-	Signing city.
signatureProductionPlace.stateOrProvince	String	-	Signing state or province.
signatureProductionPlace.postalCode	String	-	Signing postal code.

Response parameters

Parameter	Type	Mandatory	Description
generatedSignatureId	String	+	Signature ID needed for finalization of signature.
challengeId	String	+	4-character control code calculated on basis of the Challenge value to be signed. This code is displayed on mobile phone's screen and must be also displayed by integrating web service in order to ensure the user on authencity of the query.

In case of not MID user and revoked/suspended certificate error is returned.

For testing in Demo environment TEST Mobile-ID number can be found here

Request Mobile-ID signing status

Method for requesting status of the signing process (signer to enter a PIN on the mobile device). This method should be polled with interval while the status is OUTSTANDING_TRANSACTION in all other statuses polling should be stopped.

Method	URL
GET	/containers/{containerId}/mobileidsigning/{signatureId}/status

Response parameters

Parameter	Type	Mandatory	Description
midStatus	String	+	SIGNATURE – signature was successfully created; OUTSTANDING_TRANSACTION – signing is still on the way, the status query shall be repeated; EXPIRED_TRANSACTION – service timed out before user managed to complete the signing; USER_CANCEL – the user refused or cancelled the signing proces; MID_NOT_READY – the Mobile-ID of the SIM is not yet ready for the operations; INTERNAL_ERROR – technical error. NOT_VALID - signature is not valid SENDING_ERROR – other error when sending message (phone is incapable of receiving the message, error in messaging server etc.); SIM_ERROR – SIM application error; PHONE_ABSENT – phone is switched off or out of coverage;

Start Smart-ID signing

Method for starting Smart-ID signing of container.

Method	URL
POST	/containers/{containerId}/smartidsigning

Request parameters

Parameter	Type	Mandatory	Description
personIdentifier	String	+	Signers personal national identification code.
country	String	+	Signers country of residence. 2 character ISO 3166-1 alpha-2 country code.
messageToDisplay	String	-	Text displayed in addition to ServiceName and before asking PIN2. Maximum length is 40 bytes. In case of Latin letters, this means also a 40 character long text, but Cyrillic characters may be encoded by two bytes and you will not be able to send more than 20 symbols.
signatureProfile	String	+	Profile of the signature. Available values LT - TimeStamp based and LT_TM - TimeMark based signatures.
roles	Array	-	Array of strings describing the signer role.
signatureProductionPlace	Object	-	Object containing signing location.
signatureProductionPlace.countryName	String	-	Signing country.
signatureProductionPlace.city	String	-	Signing city.
signatureProductionPlace.stateOrProvince	String	-	Signing state or province.
signatureProductionPlace.postalCode	String	-	Signing postal code.

Response parameters

Parameter	Type	Mandatory	Description
generatedSignatureId	String	+	Signature ID needed for finalization of signature.
challengeId	String	+	4-character control code calculated on basis of the Challenge value to be signed. This code is displayed on mobile phone's screen and must be also displayed by integrating web service in order to ensure the user on authencity of the query.

Request Smart-ID signing status

Method for requesting status of the signing process.

Method	URL
GET	/containers/{containerId}/smartidsigning/{signatureId}/status

Response parameters

Parameter	Type	Mandatory	Description
sidStatus	String	+	RUNNING – process is ongoing; COMPLETE – process is complete;

Request signature list of given container

Method for returning all the signers of the container.

Method	URL
GET	/containers/{containerId}/signatures

Response parameters

Parameter	Type	Mandatory	Description
signatures	Array	-	Array of signature objects.
signature	Object	+	Object containing signature information.
signature[0].id	String	+	Signature id taken from signature.
signature[0].generatedSignatureId	String	+	Unique signature id generated by the service to enable manipulation of signatures.
signature[0].signerInfo	String	+	Signers certificate DN field. Example "SERIALNUMBER=PNOEE-38001085718, GIVENNAME=JAAK-KRISTJAN, SURNAME=JÕEORG, CN="JÕEORG,JAAK-KRISTJAN,38001085718", C=EE".
signature[0].signatureProfile	String	+	Signature profile.

Request signer info on given signature

Method of returning information on a specific signer of the container.

Method	URL
GET	/containers/{containerId}/signatures/{signatureId}

Response parameters

Parameter	Type	Mandatory	Description
id	String	+	Signature id taken from signature
signerInfo	String	+	Signers certificate DN field. Example "SERIALNUMBER=PNOEE-38001085718, GIVENNAME=JAAK-KRISTJAN, SURNAME=JÕEORG, CN="JÕEORG,JAAK-KRISTJAN,38001085718", C=EE".
signatureProfile	String	+	Signature profile.
ocspCertificate	String	-	Certificate of OCSP provider.
timeStampTokenCertificate	String	-	Certificate of timestamp provider.
ocspResponseCreationTime	String	-	OCSP creation time.
timeStampCreationTime	String	-	Timestamp creation time.
trustedSigningTime	String	-	Time considered as trusted signature creation time. Can be either timestamp or OCSP time, depending on signature profile.
signingCertificate	String	+	Signers certificate.
claimedSigningTime	String	+	Computer time on signature creation. This is not trusted signing time!
roles	Array	-	Array of strings describing the signer role.
signatureProductionPlace	object	-	Object containing signing location.
signatureProductionPlace.countryName	String	-	Signing country.
signatureProductionPlace.city	String	-	Signing city.
signatureProductionPlace.stateOrProvince	String	-	Signing state or province.
signatureProductionPlace.postalCode	String	-	Signing postal code.

Request validation of container in session

Method for retrieving validation report (simple report from SIVA service is returned).

Method	URL
GET	/containers/{containerId}/validationreport

Response parameters

Parameter	Type	Mandatory	Description
validationConclusion	Object	+	Check SIVA validationConclusion block

Request validation of container without session

Method for validating a container.

Method	URL
POST	/containers/validationreport

Request parameters

Parameter	Type	Mandatory	Description
containerName	String	+	Name of the container.
container	String	+	Base64 encoded container. ASIC-E, BDOC and DDOC forms are supported.

Response parameters

Parameter	Type	Mandatory	Description
validationConclusion	Object	+	Check SIVA validationConclusion block

Request container

Method for retrieving the container.

Method	URL
GET	/containers/{containerId}

Response parameters

Parameter	Type	Mandatory	Description
containerName	String	+	Name of the container.
container	String	+	Base64 encoded container. ASIC-E, BDOC and DDOC forms are supported.

Delete container

Method for deleting container in use. This closes the active "session". It is recommended to delete container after usage as unclosed sessions may max out allowed connections count for the service.

Method	URL
DELETE	/containers/{containerId}

Response parameters

Parameter	Type	Mandatory	Description
result	String	+	OK is returned

Error responses

Parameter	Type	Mandatory	Description
errorCode	String	+	Error code
errorMessage	String	+	Error description