Signed documents

The customer can either get the signed document in a SDO or a PAdES format, generate a PAdES document from a SDO and merge and validate SDOs.

Available messages used to fetch or handle a signed document:

GetSDO
GetSDODetails
GetPAdES
GeneratePAdES
MerchantSignDocument
MergeSDOs
ValidateSDO

GetSDO

The GetSDO message is a request to fetch the complete SDOList for a given sign order. If the sign order is not complete, the response will be empty. To get the partial SDOLists generated for each document the GetDocuments XML message must be used.

Note: SDO's are available in the E-Signing database for 90 days. If you are not using E-Archive, this message must be used to retrieve the SDO.

Name	Description	Constraints
OrderID	The OrderID sent by the customer.	MinLength = 1 MaxLength = 80

GetSDO response

Name	Description	Constraints
OrderID	The OrderID sent by the customer.	MinLength = 1 MaxLength = 80
OrderStatus	The status of the sign order.	[Active \| CancelledByMerchant \| Expired \| RejectedBySigner \| Complete \| ExpiredByProxy \| Failed \| Deleted]
TransRef	String uniquely identifying the transaction in E-Signing.	NA
B64SDOBytes	The entire SDO for this particular sign order.	Base64 encoded.

GetSDODetails

The GetSDODetails message is a request to retrieve detailed information about the content of the input SDO. The VerifySDO boolean element may be set to true to force the validation of the SDO content integrity. The information in this message’s response can be used to extract sign information like signer, signing time, signed data among other things.

Name	Description	Constraints
B64SDOBytes	The input SDO that shall be analyzed.	Base64 encoded.
VerifySDO	Set this element to true to force the validation of the SDO content integrity.	[true \| false]
ReturnSSN	Set this element to true to return the SSN of the signers’ certificates.	[true \| false] This functionality is only available for BankID (NO), and a VA request to BankID will be performed for all end user signatures if the SSN is not found in the OCSP attached to the signature.
ReturnOrganizationNumber	Set this element to true to return the organisation number in case of a signature by an organisation.	[true \| false] This functionality is only available for BankID (NO).

GetSDODetails response

The GetSDODetailsResponse message returns the SDOList information.

Name	Description	Constraints
TransRef	String uniquely identifying the transaction in E-Signing.	NA
NumberOfSDOsInList	Number of SDO elements in the SDOList.	NA
SDOList	A structure that holds one to many numbers of SDO elements.	NA
SDOList / SDO / SDOSignatures	A structure that contains one to many SDOSignature elements. See details in the SDOSignatures section.	NA
SDOList / SDO / SDOSealSignature	A structure containing information about the seal certificate and signature. See details in the SDOSealSignature section.	NA
SDOList / SDO / CustomPropertySignature	A structure containing information about the certificate used to sign custom properties. This element is only included if there are any custom properties defined in the sign order. See details in the CustomPropertySignature section.	NA
SDOList / SDO / SignedData	The signed document in this SDO.	Base64 encoded.
SDOList / SDO / MetaData	A structure containing a set of name and value pairs. See details in the MetaData section.	NA
SDOList / SDO / CustomProperties	A structure containing custom properties provided as part of the sign order. This element is only included if there are any custom properties defined in the sign order. See details in the CustomProperties section.	NA

SDOSignatures

Name	Description	Constraints
SDOSignature / SignerCertificateInfo / CN	Common name from signer certificate (OID 2.5.4.3).	NA
SDOSignature / SignerCertificateInfo / O	Organisation name from signer certificate Subject (OID 2.5.4.10).	NA
SDOSignature / SignerCertificateInfo / ValidFrom	Signer certificate ValidFrom in ms since 1970.	NA
SDOSignature / SignerCertificateInfo / ValidTo	Signer certificate ValidTo in ms since 1970.	NA
SDOSignature / SignerCertificateInfo / CertificatePolicy	Highlevel description of the signer certificate policy OID. The policy OID is mapped to one of the valid values in the contraints column.	[Personal \| PersonalQualified \| Employee \| EmployeeQualified \| MerchantSoft \| MerchantHSM \| PersonalSoft \| PersonalSmartcard \| PersonalMobile]
SDOSignature / SignerCertificateInfo / CertificatePolicyOID	The policy OID.	NA
SDOSignature / SignerCertificateInfo / IssuerCN	The name of the issuer of the signer certificate.	NA
SDOSignature / SignerCertificateInfo / PKIVendor	Signer certificate eID provider.	[BankID \| NemID \| BankIDSE \| NemID-OpenSign \| BankIDNOMobile \| EuridaConnect \| PKI-OTP \| Tupas \| Nets]
SDOSignature / SignerCertificateInfo / UniqueId	Unique ID from the certificate.	NA
SDOSignature / SignerCertificateInfo / SSN	The SSN of the signer.	This functionality is only available for BankID (NO).
SDOSignature / SignerCertificateInfo / OrganizationNumber	The organisation number of an organisational certificate.	This functionality is only available for BankID (NO).
SDOSignature / SignatureInfo / SigningTime	The signing time in Java time format.	Only present if the signature contains signing time.

SDOSealSignature

Name	Description	Constraints
SDOSignature / SignerCertificateInfo / CN	Common name from signer certificate (OID 2.5.4.3).	NA
SDOSignature / SignerCertificateInfo / O	Organisation name from signer certificate Subject (OID 2.5.4.10).	NA
SDOSignature / SignerCertificateInfo / ValidFrom	Signer certificate ValidFrom in ms since 1970.	NA
SDOSignature / SignerCertificateInfo / ValidTo	Signer certificate ValidTo in ms since 1970.	NA
SDOSignature / SignerCertificateInfo /	Highlevel description of the signer certificate PolicyInformation OID. The Policy OID is mapped to one of the valid values in the contraints column.	[MerchantSoft \| MerchantHSM]
SDOSignature / SignerCertificateInfo / IssuerCN	The name of the issuer of the signer certificate.	NA
SDOSignature / SignerCertificateInfo / PKIVendor	Signer certificate eID provider.	[BankID \| NemID \| BankIDSE \| EuridaConnect]
SDOSignature / SignerCertificateInfo / OrganizationNumber	The organisation number for the SDO seal certificate.	This functionality is only available for BankID (NO).
SDOSignature / SignatureInfo / SigningTime	The signing time in Java time format.	Only present if the signature contains signing time.

CustomPropertySignature

Name	Description	Constraints
SDOSignature / SignerCertificateInfo / CN	Common name from signer certificate (OID 2.5.4.3).	NA
SDOSignature / SignerCertificateInfo / O	Organisation name from signer certificate Subject (OID 2.5.4.10).	NA
SDOSignature / SignerCertificateInfo / ValidFrom	Signer certificate ValidFrom in ms since 1970.	NA
SDOSignature / SignerCertificateInfo / ValidTo	Signer certificate ValidTo in ms since 1970.	NA
SDOSignature / SignerCertificateInfo / CertificatePolicy	Highlevel description of the signer certificate PolicyInformation OID.	[CustomPropertySigner]
SDOSignature / SignerCertificateInfo / IssuerCN	The name of the issuer of the signer certificate.	NA
SDOSignature / SignerCertificateInfo / PKIVendor	Always “NA”.	[NA]
SDOSignature / SignerCertificateInfo / UniqueId	Always “NA”	[NA]

MetaData

Name	Description	Constraints
NameValuePair / Name	The metadata name.	NA
NameValuePair / Value	The metadata value.	NA

CustomProperties

Name	Description	Constraints
Property / SDOSignatureRef	Optional reference to one of the signers in the sign order. If this element is not present, it means that the property is for all signers in the sign order. The number value refers to the order the signature is presented in the SDO. If the SignatureRef is set to [1] this refers to the first signature in the SDO, if set to [2] it refers to the second signature and so on.	NA
Property / Name	Custom name of the property.	MinLength = 1 MaxLength = 80
Property / Value	Custom value of the property	MinLength = 1 MaxLength = 200

Name

Description

Constraints

Property / SDOSignatureRef

Optional reference to one of the signers in the sign order. If this element is not present, it means that the property is for all signers in the sign order. The number value refers to the order the signature is presented in the SDO. If the SignatureRef is set to [1] this refers to the first signature in the SDO, if set to [2] it refers to the second signature and so on.

Property / Name

Custom name of the property.

MinLength = 1

MaxLength = 80

Property / Value

Custom value of the property

MinLength = 1

MaxLength = 200

GetPAdES

The GetPAdES message offers functionality to retrieve a signed PDF (PAdES) file from the E-Signing service based on an existing sign order. The LocalDocumentReference must refer to a PDF document.

Note: It is only possible to retrieve a signed PDF (PAdES) document 90 days after the sign order was set to complete as sign orders in E-Signing are deleted after 90 days.

GetPAdES

Name	Description	Constraints
OrderID	The OrderID sent by the customer.	MinLength = 1 MaxLength = 80
LocalDocumentReference	This is the reference given to the document when inserting this order to E-Signing.	MinLength = 1 MaxLength = 100
PAdESDocumentReference	This is a reference to the PDF document. The document reference will be added to all pages in the PDF, including the last page added by Nets. This parameter is only used when a PAdES is generated from a SDO.	MinLength = 1 MaxLength = 40
Language	This is the language used on the last page added by Nets. This parameter is only used when a PAdES is generated from a SDO.	[en-GB \| nb-NO \| nn-NO \| sv-SE \| sv-FI \| fi-FI \| da-DK] Default: en-GB
IncludeSSN	Control the return of SSN in the PAdES document. If set to true, SSN will be returned. If set to false, a personal identifier will be shown for BankID NO, BankID SE, FTN and MitID. Note: The default value is false, except for BankID SE where the default is true. This parameter is only used if the PAdES is generated from a SDO.	[true \| false]
IncludeCustomProperties	In the SDO, there might be custom property values. These are per default not returned in the PAdES document. By setting this element to true, any custom properties from the signed document will be added to the last page of the Nets generated PAdES document. An example of this can be seen here.	[true \| false]
TimeZone	This parameter is used to set the specified time zone for all PAdES timestamp values. Example: TimeZone could be CET, UTC, Europe/Oslo, etc.	MaxLength=50 Default: UTC

GetPAdES response

Name	Description	Constraints
OrderID	The OrderID sent by the customer.	MinLength = 1 MaxLength = 80
TransRef	String uniquely identifying the transaction in E-Signing.	NA
PAdESDocumentReference	This is the document reference given by the customer in the corresponding request.	NA
PAdESSignedDocumentBytes	The PAdES document.	NA

GeneratePAdES

The GeneratePAdES message offers functionality to generate a PAdES document based on a specified SDO. The SDO is given as the input in this message.

Name	Description	Constraints
PAdESDocumentReference	This is a reference to the PDF document. The document ref-erence will be added to all pages in the PDF, including the last page added by Nets.	MinLength = 1 MaxLength = 40
Language	This is the language used on the last page added by Nets.	[en-GB \| nb-NO \| nn-NO \| sv-SE \| sv-FI \| fi-FI \| da-DK] Default: en-GB
IncludeSSN	Control the return of SSN in the PAdES document. If set to true, SSN will be returned. If set to false, a personal identifier will be shown for BankID NO, BankID SE, FTN and MitID. Note: The default value is false, except for BankID SE where the default is true.	[true \| false]
IncludeCustomProperties	In the SDO, there might be custom property values. These are per default not returned in the PAdES document. By setting this element to true, any custom properties from the signed document will be added to the last page of the Nets generated PAdES document. An example of this can be seen here.	[true \| false]
SDO / Base64SDOBytes	The SDO file that shall be used to generate the PAdES document.	The SDO file can only include one SDO with one PDF document.
TimeZone	This parameter is used to set the specified time zone for all PAdES timestamp values. Example: TimeZone could be CET, UTC, Europe/Oslo, etc.	MaxLength=50 Default: UTC

GeneratePAdES response

Name	Description	Constraints
PAdESDocumentReference	This is the document reference given by the customer in the corresponding request.	NA
PAdESSignedDocumentBytes	The PAdES document.	NA

MerchantSignDocument

The MerchantSignDocument can be used to automatically add a merchant signature to a document. The document to be signed is the input together with the signing eID, and if successful it returnes the signed SDO.

Name	Description	Constraints
Document / Description	Description of the document. This is added to the SDO.	MinLength = 4 MaxLength = 240 There is an input validation on this element rejecting sign orders with the characters “<” and “>” in this element.
Document / DocType / PDF / B64DocumentBytes	The PDF document is placed here.	Base64 encoded.
Document / DocType / TEXT / B64DocumentBytes	The TEXT document is placed here. If the document is a TEXT, provide the document UTF-8 bytes.	Base64 encoded.
Document / DocType / XML / B64XMLBytes	The XML document is placed here.	Base64 encoded. Only BankID (NO) supports this document format.
Document / DocType / XML / B64XSLBytes	The XSL document format is placed here. The XSL used to transform the input xml into HTML.	Base64 encoded. Only BankID (NO) supports this document format.
SigningPKIType	This defines which of the customer's eID to use for signing.	[BankID \| EuridaConnect \| NemID]

MerchantSignDocument response

Name	Description	Constraints
TransRef	String uniquely identifying the transaction in E-Signing.	NA
B64SDOBytes	The entire SDO for this particular sign order.	Base64 encoded.

MergeSDOs

Two SDOs can be merged into a single SDO that contains all signatures in both provided SDOs. The signed document within the incoming SDOs must be identical, and each SDO can only contain one document. In return, the customer will get one SDO with all signatures from the two original SDOs.

Name	Description	Constraints
B64SDOBytes	This element must be populated with the SDOs to merge.	The base 64 encoded representation of the UTF-8 encoded SDOs.

MergeSDOs response

Name	Description	Constraints
TransRef	String uniquely identifying the transaction in E-Signing.	NA
B64MergedSDOBytes	A single SDO containing all signatures from the two original SDOs. The single SDO is sealed with the customer's organisation certificate.	NA

ValidateSDO

The ValidateSDO message is a request to validate the base 64 encoded SDOList.

Name	Description	Constraints
B64SDOBytes	The SDOList to validate.	Base 64 encoded.
SDOSealed	If the value is set to true, a check if the SDO is sealed will be performed. Invalid will be returned if it is not sealed.	[true \| false]

ValidateSDO response

Name	Description	Constraints
TransRef	String uniquely identifying the transaction in E-Signing.	NA
SDOStatus	The SDOstatus telling if the input SDOList is valid or invalid.	[Valid \| Invalid]
ValidationErrorMessage	This element is only present if the SDO status is Invalid.

E-Signing

Signed documents

GetSDO

GetSDO response

GetSDODetails