In order to perform a digital signature on a document, a signature request needs to be created. A signature request defines the instructions for the signature engine — in its simplest form it specifies what is going to be signed and how it can be signed.
The request is sent to the DocumentService web service, the URL for which can be found here (look for WSDL): DocumentService
The typical life cycle of a document signature request is:
- Upload the documents to be signed to the Session Data Storage (SDS)
- Create a request with DocumentService
- Redirect the user to Signicat for the signing request
- Receive Status of the request
- Download the signed document from SDS
Due to the modular design of Signicat Signature, it is possible to deviate somewhat from this list — but for the moment we’ll go through each of these steps in detail:
1. Upload documents to be signed to the Session Data Storage
The SDS is a REST based interface where documents are stored temporarily. While it is possible to send the documents within the SOAP call made to DocumentService, it is generally recommended to use SDS for transfer of documents because SDS’s REST based interface is more efficient and can deal with larger file sizes.
Instructions for using SDS can be found here: SDS (Session Data Storage)
2. Create a request with DocumentService
A SOAP request needs to be made to DocumentService to specify the instructions for the request. Put simply, this is where you describe what to be signed, who needs to sign it and how they should sign.
Requests are made up of five main components:
- Task(s)
- DocumentAction(s)
- Document(s)
- Subject(s)
- Notification(s)
More details about request creation can be found in the documentation: DocumentService v3
3. Redirect the user to Signicat for the signing request
When you want the user to start a signing action you will need to construct a URL leading the user back to signicat.
The URL will have the following format:
https://env.signicat.com/std/docaction/service?request_id=request_id&task_id=task_id&artifact=artifact
Parameter | Description | Example value | Required |
---|---|---|---|
env | env is the environment. When you’re first starting out, this will typically be preprod — in production it will be id. In production, if you have acquired a Signicat Subdomain, this must be be used instead. | preprod (in pre-production) id (in production) |
Yes |
service | service is the name of your service as registered with Signicat. There is a pre-production service called demo which you may use as you’d like, but eventually you will want to start using your own service. |
Demo (in pre-production environment) yourdomainnamegoeshere.com (in production) |
Yes |
request_id | request_id is the unique identifier for the requests that was created. | Yes | |
task_id | task_id is the unique identifier for a specific task in the request. | Yes | |
artifact | artifact, optional, and should only be included if the return value from DocumentService createRequest includes an artifact, or if you specify an artifact later using DocumentService createArtifact. This is a short-lived Single sign-on artifact, valid for only 30 seconds, and can be used to secure the signing order if you prefer not to require the end-user to log in with a stronger ID (such as BankId) to be able to view the documents before signing. Please see Use artifacts to secure signing orders for a complete code example. Please also see the section Features and customization for a more thorough description of artifacts and their usage. | No |
NOTE: all URL parameters must be properly URL encoded using UTF-8, as per RFC 3986.
Example of a valid signing url: https://preprod.signicat.com/std/docaction/demo?request_id=10112015xwufkg8j94nfikhn0t26mvmme13mqzd37ok0tn5pv9am9y4hl&task_id=task0
For a code example of a simple request using C#, see the following: Creating a simple signing order with one subject using Danish NemID
Request workflow and task order
The order in which the tasks of signature request is completed can be arranged by using “depends-on-task” within the Task datatype, allowing for complex workflows. For example: two customers and a salesman need to sign a contract, but the sales person may only sign when both of the customers have completed their signatures.
In this scenario the request would consist of three tasks (one for each signatory), so lets call them task A, B and C.
- first option is to let the two customers sign in parallel, this would be achieved by letting task C depend on task A and B
- alternatively all signatures could be sequential, this could be achieved by letting task B depend on A, and task C depend on B
Changing an existing request
There could be various reasons that you would want to change an existing request — the email address or mobile number of one of the signatories could have changed, the relevant signatories could change or the request could simply become obsolete.
- Existing requests can be deleted by using deleteRequest
- Notifications can be disabled and new notifications can be added to an existing request by using disableNotification and addNotification
- Tasks can be disabled and new ones added to existing requests by using disableTask and addTask
4 – Receive Status of the request
When the signing order was created, you most likely defined a documentactionrequest
in order for notifications and callbacks to notify your server (or other recipient) about actions being taken by the signer — whether it’s a request being created, cancelled or completed. We provide three complementary mechanisms for this:
- Notification by redirect
- Notification by server-to-server callback
- Notification by messaging
All are optional and may be used independently.
Notification by redirect
When you’re creating a signing order, the documentactionrequest
allows you to specify three different URLs where Signicat can redirect the end user when they have signed (or declined to sign) a document. These cover the following scenarios:
URL
|
URL is used when
|
---|---|
on-task-cancel | The url where the end user should be returned if the task is cancelled. |
on-task-postpone | The url where the end user should be returned if he chooses to postpone the task. |
on-task-complete | The url where the end user should be returned when the task is completed. |
The URLs are specified for each signing order, and may contain HTTP parameters with session specific or transaction specific values. The end user will not be redirected at all if on-task-complete is missing in the request when a document has been signed.
HTTP redirection cannot be guaranteed, however; the end user may close his browser before the redirect has completed or network problems may prevent the HTTP request to reach your server.
Notification by server-to-server callback
The documentactionrequest
allows you to specify a URL on your server that Signicat should call when a signing order is created or completed. Signicat’s server will make an HTTPS call to this URL directly (or HTTP, but insecure HTTP calls are only supported in preprod). This is a server-to-server call, not involving the end user’s browser at all. You may specify a static URL that should be used for all signing orders, or you may specify a different URL for each order. The URL may contain any number of parameters such as session specific parameters or user specific information. You may also add parameters for added security, such as a static or dynamic password. Signicat will always add the requestId
in an extra HTTP parameter.
The HTTP call will be made by Signicat’s server and will come from a fixed IP address. In order for these to work, Signicat must be informed about the destination address on your end, as our firewall blocks notifications to unknown URL’s by default.
The notification is specified in the request with these values:
Attribute
|
Value
|
---|---|
type | The string “URL” |
recipient | The URL that Signicat should call (with any HTTP parameters). |
You may specify more than one notification if you want Signicat to make more than one callback. Delivery of the notification is guaranteed as long as your server is able to receive HTTP calls.
When doing server-to-server notification, you may choose to add additional security features to make the notification reliable. An example would be to:
- Create a one time token (a random number or string) for each request.
- Add the token to the callback url in a http parameter called i.e. “secure”.
- When Signicat makes the callback, validate that the value of the parameter is correct.
This would protect against fake HTTP callbacks since senders of fake callbacks would not be able to guess the correct parameter value.
Notification by messaging
The documentactionrequest
allows you to specify a (mobile) phone number or an email address where Signicat should send a message when a signing order is created or completed — you may specify one or more notifications like this. Typical uses of this is to send a message to a back office address, send a message to the end user or even send a message to a local workflow system. Each message is specified in each request, and the text can be personalized or contain user specific information like customer number, transaction details and so forth. Delivery of the notification depends on the SMS and email infrastructure and cannot be guaranteed.
The notification is specified in the documentactionrequest
with these values:
Attribute
|
Value
|
---|---|
sender | The sender address. |
header | Subject in email. Not used for SMS. |
message | The text message in the email or SMS. |
type | The string “SMS” or “EMAIL”. |
recipient | Phone number (with country code prefix) or email address. |
An example can be found here: Notify and get notified when a signing order status changes
Notes about security
You should not depend on the correctness of the information you get in the notifications. The notification should be regarded as a “hint” about a possible status change in the signing order. You must always call getStatus
on Signicat’s web service after you have received a notification to get reliable, updated status information.
The “Notification by server-to-server callback” can be extended to include security mechanisms that would make the notification reliable. However, Signicat still recommends that you always call getStatus
to get reliable information. The information you get in return from the getStatus
web service call will always be correct and reliable.
Other web service calls
It is possible to get information about existing requests by using getStatus and getRequestHistory which, in combination, yields a precise picture of any given request’s as well as related status events.
An example of this can be found here: Check the status and result of a signing order
NOTE: getStatus can be used for checking status on selected request, but in general, polling should be avoided. Instead, notifications and callbacks should be used.
5 – Download the signed document from SDS/Signicat Archive
In order to do this, you should know about the different formats the signed document may take. This is described in greater detail in the next section: The Signature Result.