Web service functions

​Documents signing are handled through a web service interface. The interface is built up as an ordering system where the customers define a sign order with the signers, documents, web contexts etc. and sends it to E-Signing for execution. The web service interface are described in details below and on the underlying pages.

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.

Request_header[1].png 

​Name​Description​Constraints
​MerchantIDThis value represents the customer, and the value is set upon customer configuration in E-Signing.​NA
​Time​This value is the current date and time in UTC.

​Time in UTC ie “2017-11-02T11:00:00Z”

The value must be within the current time window – ie +/- 10 minutes.

​MessageID​The MessageID is  defined by the customer application and is returned in the response. The customer may use the MessageID to see which request the response-message belongs to.​Each MessageID must be unique for the given customer.
​AdditionalInfo​The AdditionalInfo element can be used by customers to add information like cost center etc. The value is only added when used together with the InsertOrder request. It is ignored when using it with other type of requests.

MinLength = 1
MaxLength = 50

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:

 

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:

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

Definitions

Sign order

A sign order is an order sent to the E-Signing service which defines the document(s) to be signed, the signer(s), the web context to sign the document(s) in, any connection to an organisation, all actions to be performed and post-processing details like archival and checking signature rights. The sign order is composed using the InsertOrder XML message.

Step

​A step is a collection of sign processes that may be executed simultaneously. The step with the lowest step number is executed first. A sign order may consist of many steps. Only one step may be active at any given time.

Sign process

​A sign process is constructed holding information about a single signer, a single document, a single web context and optionally a deadline and reminder settings. A signer may only sign one document at a time.

Sign workflow options

Sequential sign workflow:

​A sequential sign workflow is a workflow with one sign process in each step. The steps in a sign order must equal the number of sign processes. Each sign process will then be performed in the order of the step where the first sign process must be completed before the next can be started.

 

Parallel sign workflow:

​A parallel sign workflow is a workflow where all sign processes are defined in one step. The sign processes can be performed simultaneously.

  

Combined sign workflow:

​The combined sign workflow is a combination of the sequential sign workflow and the parallel 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

​Status​Description
​Active

​The Active status is the first status a sign order will be given. The sign order is in this status as long as there are steps within the Active status.

When the sign order is registered it gets the Active status. Step 1 and all its sign processes get the Active status. The rest of the steps, and their sign processes, get the Pending status.

​CancelledByMerchant​The CancelledByMerchant status is given to a sign order when the customers application sends a CancelOrder message on a specified sign order to E-Signing. The sign order is cancelled. This is a final state.
​Expired​The sign order is expired. This state is applied when a deadline is reached. The sign order can be returned to an Active status using the ModifyOrderDeadline message.
​ExpiredByProxy​The sign order is set to the ExpiredByProxy status when either a step or a sign process has reached its deadline. The deadline can be modified using the ModifyOrderDeadline message
​RejectedBySigner

​A sign order is set to RejectedBySigner if the following occurs:

  • The signer has rejected to sign a document. 
  • The TerminateOrderOnSignerRejection setting in the InsertOrder is set to true

This state may also be reached if the customer uses the ModifySigningProcess message. This state is a final state.

​Complete​The sign order is set to Complete when all steps and sign processes are completed and all post-processing of a sign order has been completed. Post-processing includes creating and sealing the SDO, send notifications and archival. The sign order will also reach this state if one or more of the sign processes have been rejected, but the TerminateOrderOnSignerRejection is set to false. This is a final state.
​Failed​A sign order is set to Failed if one of the signers of a document did not have the right to sign the document. This state will only occur in conjunction with the use of ID-Rights functionality. This is a final state.
​Deleted​The sign order is set to Deleted if the DeleteDocumentData message has been performed for that particular order.

Step status

​Status​Description
​Active​A step is set to the Active status when the steps prior to this step have been completed with either a Complete or RejectedBySigner status. The first step is set to Active at the same time as the sign order is set to Active. Only one step may be in the Active status at the same time.
​Pending​A step is set to Pending if the previous steps have not been completed.
​CancelledByMerchant​A step is given the CancelledByMerchant status is the customers sends a CancelOrder message to E-Signing.
​Expired​A step is set to Expired if the step’s deadline has been reached. This can be modified using the ModifyOrderDeadline message.
​ExpiredByProxy​The step is set to ExpiredByProxy if one or more of the sign processes in the step have reached its deadline. This can be modified using the ModifyOrderDeadline message.
​RejectedBySigner​A step is set to RejectedBySigner if the following occurs:
  • The signer has rejected to sign a document. 
  • The TerminateOrderOnSignerRejection setting in the InsertOrder is set to true

This state may also be reached if the customer uses the ModifySigningProcess message. This state is a final state.

​Complete​T​he step is set to Complete when all sign processes are completed. The step will also reach this state if one or more of the sign processes have been rejected, but the TerminateOrderOnSignerRejection is set to false. This is a final state. The next step will now reach the Active state.

Sign process status

​Status​Description
​Active​All sign processes in a step are set to Active when the step reaches the Active status.  A sign URL for the Active sign processes are now available, and the signer can sign the document in this sign process.
​Pending​A sign process is set to Pending if the sign process is not ready for signing. The previous steps have not been completed.
​CancelledByMerchant​The sign process is given the CancelledByMerchant status if the customer sends a CancelOrder message to E-Signing.
​Expired​The sign process is set to Expired if the sign process’ deadline has been reached. This can be modified using the ModifyOrderDeadline message.
​RejectedBySigner​The signer has rejected to sign the document in the sign process. This state may also be reached if the customer uses the ModifySigningProcess message. This state is a final state.
​CompleteThe signer has signed the document, and the sign process is completed. The sign process is set to Complete. This is a final state.

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.

​TriggerReceipient​​Description
​OnOrderCancellation

​Customer

Signer

​A sign order has been cancelled by the customers application. The sign order status is now Cancelled, and a cancelled notification is distributed.
​OnOrderCompletion

​Customer

Signer

​A sign order has been completed. The sign order status is now Complete and a complete notification is distributed.
​OnOrderRejection​Customer

Signer

​A sign order has been set to the RejectedBySigner state. The optional reject text from the signer is included. Read more for details on how to reach the RejectedBySigner status.
​OnOrderExpiration​Customer

Signer

​A sign order deadline has passed. The sign order status is now Expired.
​OnOrderFailed​​Customer

Signer

​The sign order has failed, and the sign order status is now Failed.
​OnStepReady​Customer

Signer

Means that the recipient will receive a notification to the channel specified whenever a step switches its state to Active.
Note: The OnStepReady signer notification will include one signing URL covering several sign processes when the signer shall use the BankID 2.1 clients multi-document signing functionality.

​OnStepExpiration​Customer​Means that the customer will receive a notification to the channel specified when a step is expired.
​OnStepCompletionCustomer​​Means that the customer will receive a notification to the channel specified when a step completed successfully.
​OnSignProcessReady​Signer​Means that the signer will receive a notification when a sign process is ready to be executed. This is triggered when a sign process is set to the Active state.
​OnSignProcessRejection​Customer​Means that the customer will receive a notification when a sign process is rejected by a signer. The optional reject text from the signer is included.
​OnSignProcessExpiration

​Customer

Signer

​Means that the recipient will receive a notification when a sign process is expired.
​OnSignProcessCompletion​Customer​Means that the customr will receive a notification when a sign process completed successfully.
​OnReminderEvent​Signer​This trigger must be seen in combination with a sign process. If set, the signer will receive a reminder notification if the ReminderSettings is present on any of the sign processes that involves this signer.