The V1 API is the encouraged choice for sending one or more documents in a single request for signing or downloading and obtaining the result afterwards. For specialized operations, please see our V2 API interface. It is possible to use V2 API calls after calling StartSignFlow.
| Tip |
|---|
PKIsigning is using Swagger for API documentation. Please look at the API documentation in our Swagger interface. |
The PKIsigning API consists of four operations:
StartSignFlow
RetrieveDocument
RemoveDocument
GetWorkgroupWithClearanceLevel
StartSignFlow
| Urgent |
|---|
The API documentation is showing several fields in the request that are only present for backwards compatibility. /document These properties have been replaced by their successors in the /documents array and therefore allow for sending multiple files. |
...
For each signer an ordinal is required. The order of signers is based on the deadline specified. In case where deadlines of signers are equal, the ordinal is used to create an order.
As the request is sent after processing, at least one signer or recipient has to be specified for a document.
For each document, a document type and mime type have to be specified. Please see our list of Document types and Mime types for valid values.
When creating a new request, a workgroup together with a clearance level can be specified. When specifying these values, a request is immediately added to a workgroup and available for other members of the workgroup to see. To prevent all members of a workgroup to see a specific request, a clearance level can be specified. Only users with the same clearance level or a clearance level that is higher than specified will be able to see and open the request.
...
It is not possible to set a higher clearance level than specified in the list retrieved from GetWorkgroupWithClearanceLevel.
| Urgent |
|---|
As PKIsigning charges credits for requests when fulfilled, credits are being reserved at the moment of submitting the request to prevent running out of credits while actually fulfilling it. If the amount of credits is insufficient to fulfill the request, a HTTP status 402 (Payment required) is returned. During development phase, please use either short deadlines or delete requests from the platform and clean up the recyblebin to prevent running out of credits. If a request is not signed nor downloaded by a recipient, any credits that were reserved for that request will become available again when the request is removed. |
Callback
It is possible to subscribe to status events on the PKIsigning platform. To subscribe, specify a callbackUrl in the StartSignFlow call. For each change in status, this url will be called using HTTP POST with a body like the following example:
| Codeblok | ||
|---|---|---|
| ||
{
"pkisId": "453…72e86",
"dossierStatus": "Completed",
"reason": "optional value indicating the reason of a status change",
"authenticationKey": "92d5ba9f…9202377"
} |
When the status is Completed, the RetrieveDocument call can be executed to obtain all signed documents.
The authentication key is only available for use in the V2 API.
To validate the origin of the callback, the callback is signed using three values in the HTTP header.
x-pkisigning-timestamp: the value of this header prevents against replay attacks and should be checked by the receiver. Normally there should not be more than a few seconds difference in time when the time of receiving system is synced through NTP.
x-pkisigning-publickey: This value contains a PKCS7 encoded certificate that was used to sign the callback request. Validate if the certificate is provided by a valid trusted service provider, is not revoked, is within its validity period and most important if the certificate contains a PKIsigning (sub)domain (we use the top level domains PKIsigning.io and PKIsigning.nl).
x-pkisigning-signature: this value contains the RSASHA256 signature of the contents combined with the timestamp. To check the signature follow the following procedure:
obtain the raw bytes of the payload (UTF-8 encoding)
obtain the bytes of the timestamp (UTF-8 encoding)
concatenate both byte sequences into one byte sequence
verify the signature against the certificate
RetrieveDocument
The RetrieveDocument call can be used to obtain a zip-file containing all documents of a single request. When a callback url was specified during the StartSignFlow call, this url is called upon status updates, after which RetrieveDocument may be called.
...