The signdoc
API is used in the context of SEID-SDO electronic signing. For a quick-start, please refer to our Get started with electronic signing guide for electronic signing.
Overview
Upload sign order to SignDoc resource server
POSTÂ [signdoc-baseurl]/signdoc
Request
Key | Value |
---|
Authorization | Bearer access_token |
Content-Type | application/json |
Request body
Key | Type / Description | Example JSON |
---|
signProperties | JSON object: key | type | description | default value |
---|
orderName | string | Order name | (required) | documentDisplayMode | string | Must be "interior", "window" or "overlay". | "interior" | showConfirmation | boolean | Show "Signing completed" in client after signing. | true | showUnderstanding | boolean | Show box for "Content is understood" in client. | true | timeoutSeconds | integer | Timeout in seconds for end user signing. | 1800 |
| "signProperties": { "orderName": "My order name", "documentDisplayMode": "interior", "showConfirmation": true, "showUnderstanding": true, "timeoutSeconds": 1800 }
|
documents | JSON array of documents to be signed (minimum one). The document to be signed is represented as a JSON object: key | type | description | default value |
---|
description | string | Description of document. Displayed to end user in client. If not specified, orderName from signProperties will be used combined with a number, e.g. "My order name - 1" for the first document. | (optional) | text | string | Text to sign. | (optional)* | pdf | string | Base64 encoded PDF. | (optional)* | xml | string | XML. Must be used together with "xsl". | (optional)* | xsl | string | XML Stylesheet. Must be used together with "xml". | (optional)* |
*Each document must provide a value for either "text", "pdf" or the pair "xml" and "xsl". | "documents": [ { "description": "My PDF document", "pdf": "JVBER..." }, { "description": "My text", "text": "My text to sign...", }, { "xml": "<?xml version=\"1.0\" encoding=\"ISO-8859-1\" ?> ...", "xls": "<?xml version=\"1.0\" encoding=\"ISO-8859-1\" ?><xsl:stylesheet ..." } ] |
resultContent | JSON array of string. The string values will determine the content result when retrieving a completed sign order: result specifier | description |
---|
basicSignature | Result contains the end user and merchant signatures (in ISO-8859 text format) | documentHash | Result contains the SHA256 hash over the documents to be signed (in UTF-8 text format). | sdo | Result contains the documents and signature data in the SEID-SDO format. |
| ["basicSignature", "documentHash", "sdo"] |
Example request
POSTÂ [signdoc-base-url]/signdoc Request body: { "signProperties": { "orderName": "My order name", "documentDisplayMode": "interior", "showConfirmation": true, "showUnderstanding": true }, "documents": [ { "text": "My text to sign" }, { "description": "My PDF order", "pdf": "JVBER..." } ], "resultContent": [ "sdo", "basicSignature", "documentHash" ] } |
Response
Content-Type: application/json
Code | Description | Example JSON response content |
---|
201 Created | Successfully created sign order. | { "sign_id": "2a8d69ba-2607-9a1e-9e60-bdb6cc67eacf", } |
400 Bad request | Could not create order due to error in request. | An order must have a name - Please provide reference: GHIjKl if reporting the problem. |
403 Forbidden
| Access token is invalid or missing. | AccessToken is invalid - Please provide reference: GHIjKl if reporting the problem. |
Check status of sign order
GETÂ [signdoc-baseurl]/signdoc
Request
Key | Value |
---|
Authorization | Bearer access_token |
Query parameters
Parameter | Type | Description |
---|
sign_id | string | The sign_id that was returned when creating the sign order. |
Example request
GETÂ [signdoc_baseurl]/signdoc/pades?sign_id=2a8d69ba-2607-9a1e-9e60-bdb6cc67eacf |
Response
Code | Description | Example JSON response content |
---|
200 OK | Sign order was found. Returns the order state. Possible values are: ORDER_RECEIVED GRABBED_BY_IDP USER_SIGNING FAILED CANCELLED SIGN_COMPLETED
|
|
204 No Content | Sign order was not found |
|
400 Bad Request | The query parameter sign_id was not provided. |
|
403 Forbidden | Access token is invalid or missing. |
|
Delete sign order and download signing results
DELETE [signdoc-baseurl]/signdoc
The sign order will be deleted if this request is made, regardless of sign order state.
Request
Key | Value |
---|
Authorization | Bearer access_token |
Query parameters
Parameter | Type | Description |
---|
sign_id | string | The sign_id that was returned when creating the sign order. |
Example request
DELETE [signdoc-baseurl]/signdoc?sign_id=2a8d69ba-2607-9a1e-9e60-bdb6cc67eacf |
Response
Code | Description | Example JSON response content |
---|
200 OK | Sign order was found. The claims returned in the signing results depends on the values pass to the resultContent array when creating the order: set by | claim | description |
---|
basicSignature
| merchantSignatures
| Array of merchant signatures in ISO-8859 text format for each document in the same order they were provided when creating the sign order. | basicSignature
| endUserSignatures
| Array of end user signatures in ISO-8859 text format for each document in the same order they were provided when creating the sign order. | documentHash
| documentHashes
| Array of hashes over the documents to be signed in the same order as the documents in the signing order | sdo
| sdos
| The SEID-SDO represented as base64 (unpack to UTF-8), one for each document |
| signId
| The sign_id used |
| clientId
| The OIDC client used |
| orderState
| Current order state |
| orderName
| Name of order |
If order is not completed, i.e. order state is not SIGN_COMPLETED , the signing results will be an empty array. | { "documentHashes": [ "5OKv0...", "l5hoT...", "PyLlx..." ], "merchantSignatures": [ "MIAGC...", "MIAGC...", "MIAGC..." ], "sdos": [ "PD94b...", "PD94b...", "PD94b...", ], "endUserSignatures": [ "MIAGC...", "MIAGC...", "MIAGC..." ], "clientId": "my-oidc-client-id", "signId": "2a8d69ba-2607-9a1e-9e60-bdb6cc67eacf", "orderState": "SIGN_COMPLETED", "orderName": "My order name" } |
204 No Content | Sign order was not found. This could be caused by timeout or an invalid sign_id . | (empty) |
400 Bad Request | The query parameter sign_id was not provided. | signId should not be empty - Please provide reference: GHIjKl if reporting the problem. |
403 Forbidden | Access token is invalid or missing. | Could not find accessToken - Please provide reference: GHIjKl if reporting the problem. |
Additional examples of sign order upload requests to SignDoc resource server
Simplified sign flow expressed like a full flow
The signing order below behaves identically to the simplified flow given by sign_txt=VGhlIHNpbmdfdHh0IGdpdmVuIGlzIHBsYWNlZCBoZXJl
{ "signProperties": { "orderName":"bankID", Â Â Â Â Â Â Â Â "showUnderstanding":"true", Â Â Â Â Â Â Â Â "showConfirmation":"false", Â Â Â Â Â Â Â Â "documentDisplayMode":Â "interior", Â Â Â Â Â Â Â Â "timeoutSeconds":600 Â Â Â Â }, Â Â Â Â "documents": [ Â Â Â Â Â Â Â Â { "text":"The sign_txt given is placed here" } Â Â Â Â ], Â Â Â Â "resultContent": [ "basicSignature", "documentHash" ] } |
SEID-SDO: Two texts and one XML
{ "signProperties": { "orderName": "test order", "showUnderstanding": "true", "showConfirmation": "false", "documentDisplayMode": "overlay" }, "resultContent": [ "sdo" ], "documents": [ { "description": "my first document to sign", "text": "Testing å and ø...." }, { "text": "Short version of a document having two linefeeds\n\ndescription when listet in BankID WebClient should be 'test order - 2" }, { "description": "An xslt transformation", "xml": "<?xml version=\"1.0\" encoding=\"ISO-8859-1\" ?><Persons><Person><Name>Ola Normann</Name><Street>Olaveien 99</Street><Zip>0014</Zip><City>Oslo</City></Person><Person><Name>Kalle</Name><Street>Ibsens veg 30</Street><Zip>9876</Zip><City>Stockholm</City></Person><Person><Name>Kari IngridsDottir</Name><Street>Nedre Sofustrøa 2</Street><Zip>7070</Zip><City>Bosberg</City></Person><Person><Name>Olava Olsen</Name><Street>Øvre Strete 12</Street><Zip>2211</Zip><City>Sørpå</City></Person></Persons>", "xsl": "<?xml version=\"1.0\" encoding=\"ISO-8859-1\" ?><xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\"> xsl:output method=\"html\" encoding=\"ISO-8859-1\" doctype-system=\"http://www.w3.org/TR/html4/loose.dtd\" doctype-public=\"-//W3C//DTD HTML 4.01 Transitional//EN\" indent=\"yes\" /><xsl:template match=\"/\"><HTML><BODY><h2>Eksempel på XML/XSL.</h2><p>Under er en liste personer tatt fra XML-en</p><ul><xsl:for-each select=\"Persons/Person\"><xsl:if test=\"0 = position() mod 2\"><li style='color:red'><xsl:value-of select=\"Name\"/>,<xsl:value-of select=\"Street\"/>,<xsl:value-of select=\"Zip\"/>,<xsl:value-of select=\"City\"/></li></xsl:if><xsl:if test=\"1 = position() mod 2\"><li style='color:green'><xsl:value-of select=\"Name\"/>,<xsl:value-of select=\"Street\"/>,<xsl:value-of select=\"Zip\"/>,<xsl:value-of select=\"City\"/></li></xsl:if></xsl:for-each></ul></BODY></HTML></xsl:template></xsl:stylesheet>" } ] } |