Web service functions

• The web service protocol
• List of all XML messages
• Recommended XML messages to implement

• Definitions
• Statuses in the service
• Notification triggers

The web service protocol

E-Signing exposes an interface that understands the TrustSignMessage XML protocol. This protocol consists of several XML-based request/response messages where each message performs a set of operations on the E-Signing service. Each message is built up in three parts:

1. Request header​
2. The message
3. XML signature

The communication between the customer and Nets is based on two-way SSL using client certificates issued by Nets. Download the TrustSignMessage XML schema. Note: Refer the XSD for namespace/version.

Request header

The request header is common for all messages to E-Signing. Note: The service has a time window and expects all customers to have synchronized clocks using the Network Time Protocol (NTP). If a message is received outside the time window, the customer will get an ErrorResponse.

The message

The E-Signing service gives a set of messages that can be categorised in four categories:

• Insert sign order
• Manage sign orders
• Get sign order info
• Signed documents

See the list below for short info an links to all messages. 
 

XML signature

All messages to the E-Signing service must be signed with XMLDSIG to be able to reach the service. The XMLDSIG must be of the enveloping kind. The entire message must be signed using a Nets issued signing certificate the customer is given upon configuration in the customer test and production environment respectively.  E-Signing validates the signature, authenticates the calling party and performs authorization checks based on the request at hand. If the calling party is authenticated and authorized then the request are handled by E-Signing.

Some external links about XMLDSIG:

• Specification: https://www.w3.org/TR/xmldsig-core/

• Wikipedia: https://en.wikipedia.org/wiki/XML_Signature

Back to top

List of all XML messages

Insert sign order

• InsertOrder: This is the main message used in E-Signing. It defines the document, signers and everything about the sign workflow for a particular signing.
   

Manage sign orders

• CancelOrder: The CancelOrder message will cancel an existing order if the sign order is in an active state.
• ModifySigner: This message offers functionality to modify a signers name and ID in an already existing sign order.
• ModifySigningProcesses: This message offers the ability to set a sign process to the RejectedBySigner status.
• ModifyOrderDeadline: This message is used to modify a sign order's deadline.
• FinalizeOrder: This message offers functionality to finalize the sign order before all signers have signed the document.
• DeleteDocumentData: This message offers functionality to delete documents, SDO’s and signatures from the E-Signing database.
  

Get sign order info

• GetSigningProcesses: This message is used to fetch all signing processes for a given order and signer. It returns among other things a list of all sign processes for a given signer, status of the processes, the sign URL (if not signed) and the signing time (if signed).
• GetOrderStatus: This message is used to request the complete status of a sign order. The message returns the status of the sign order, the documents, the signers, the steps and the sign processes.
• GetOrderDetails: This message returns a subset of the sign order as it was inserted. The response to this message is not as comprehensive as the GetOrder message, but it gives an overview of the sign order and the current statuses.
• GetOrder: This message returns the entire sign order as it was when the customer inserted it, but with some possible differences related to deadline values.
• GetOrders: This message is a search message that can filter on sign order status, signers, meta data and/or time.
• GetDocuments: This message may return a single or all documents in the specified sign order and/or the SDO or partial SDO’s.
• GetSignature: This message is used to retrieve a signature from a sign order along with the OCSP and SSN of the signer if available.
• GetNotificationLog: This message returns information about all notifiactions that have been sent to the customer itself and to signers involved in the specified sign order.

Signed document

• GetSDO: This message is a request to fetch the complete SDOList for a given sign order.
• GetSDODetails: This message is used to retrieve detailed information about the content in a SDO.
• GetPAdES: This message offers functionality to retrieve a signed PDF (PAdES) file from the E-Signing service based on an existing sign order.
• GeneratePAdES: This message offers functionality to generate a PAdES document based on a specified SDO.
• MergeSDOs: This message can be used to merge to SDOs with the same document into one SDO with signatures from both SDOs.
• ValidateSDO​: This message checks the validity of a specified SDO.

Back to top

Recommended XML messages to implement

As a minimum it is recommended to implement these XML messages:

• InsertOrder: To create and start the sign processes
• GetSigningProcesses: To get the sign URLs to present for the signers
• GetOrderStatus: To easy get a status of the sign orders

An easy guide to get started in three steps is made available. Read more in the Get started guide.

Definitions

Sign order

Step

Sign process

Sign workflow options

Sequential sign workflow:

Parallel sign workflow:

Combined sign workflow:

Back to top

Statuses in the service

E-Signing keeps track  of signer orders by giving the sign order, each step and each sign process in each step a status. The status hierarchy is managed by strict rules. In addition, the document in each sign order is given a status.  

Sign order status

Step status

Sign process status

Document status

The document status is derived by the status of all sign processes where a document is involved. The following rules apply:

• If the sign order status is CancelledByMerchant, Expired or RejectedBySigner then all documents statuses get the same status.
• If the sign order status is Active and a document is referenced from a sign process that is Active then the document status is Active.
• If the sign order status is Active and a document is referenced from sign processes that all are Complete, then the document status is Complete.
• If the sign order status is Active and a document is referenced from a sign process that is Pending then the document status is Pending.

Signer status​

This signer status is derived from statuses of signing processes that reference the signer. The following rules apply:

• If the sign order status is CancelledByMerchant, Expired or RejectedBySigner then all signer statuses get the same status.
• If the sign order status is Active and a signer is referenced from a sign process that is Active then the signer status is Active.
• If the sign order status is Active and a signer is referenced from sign processes that all are Complete, then the signer status is Complete.
• If the sign order status is Active and a signer is referenced from a sign process that is Pending then the signer status is Pending.    
  

Back to top

Notification triggers

The customer can be notified using XML, SMS and/or e-mail as notification channels and the signer can be notified using SMS and/or e-mail as the notification channels. Here is a list of triggers. Some of them willl only trigger a notification to the customer, and not to the signer. See the recipient column for the receiver of the trigger. For XML notification, see the Notification call back page for information about the content of the XML.