Full flow PAdES API and implementation guide.

Overview

Merchant request an access token with the signdoc/read_write scope (i.e. client credentials grant) to be used in request to the SignDoc resource server.
Merchant creates and uploads the sign order by sending a request to the SignDoc resource server and receives a reference, i.e. sign_id.
The signing transaction is initiated by adding the sign scope and the sign_id reference as query parameters to the authorization request.
End user performs the signing using the BankID web client (netcentric).
Merchant downloads the signing result from the SignDoc resource server.

Sign order expiration time

The sign order will expire in 90 seconds after it is created if user signing is not initiated (i.e. request to authorization endpoint).

The timeout for the sign order when user is signing is determined by the timeoutSeconds (default 1800 seconds) specified when the order was uploaded.

After the user has signed the order, the sign order will be valid for another 90 seconds before it expires.

Sequence diagram

Granting access to the SignDoc resource server

Requests to the SignDoc resource server requires an access token with the signdoc/read_write scope.
The access token can be retrieved using the client credentials grant. See Access Tokens for more details.

Upload sign order to SignDoc resource server

POST [signdoc-baseurl]/signdoc/pades

Request

Headers

Key	Value
Authorization	Bearer `access_token`
Content-Type	application/json

Request body

Key

Type / Description

Example JSON

signProperties (required)

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
}

padesSignProperties
(required)

JSON object:

key	type	description	default value
addVisualSeals	boolean	If true, add visual signature seals to PDF.	(required)

"padesSignProperties": {
    "addVisualSeals": true
}

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, i.e. "My order name - 1" for the first document.

(optional)

pdf

string

Base64 encoded PDF

(required)

endUserOnly

boolean

Set to true if only the end user signature is desired.

false

merchantSealPosition

JSON object:

key	type	description
x	number	Horizontal positioning of seal.
y	number	Vertical positioning of seal.
page	integer	Page number to place seal.

Specifies the position of merchant signature seal in PDF.

The seal will be positioned according to the x and y coordinates (in points) with origin in the upper left corner. The visual seal size is adjusted according to the DPI of the document.

If the page number is out of range it will be the seal will be placed on the first page. If the coordinates are out of bounds the seal will be placed below and left of existing seals or in the upper left corner if no other seals exist.

See COI documentation for further details.

(optional)

endUserSealPos

JSON object:

key	type	description
x	number	Horizontal positioning of seal.
y	number	Vertical positioning of seal.
page	integer	Page number to place seal.

Specifies the position of merchant signature seal in PDF.

The seal will be positioned according to the x and y coordinates (in points) with origin in the upper left corner. The visual seal size is adjusted according to the DPI of the document.

If the page number is out of range it will be the seal will be placed on the first page. If the coordinates are out of bounds the seal will be placed below and left of existing seals or in the upper left corner if no other seals exist.

See COI documentation for further details.

(optional)

"documents": [
{

    "description": "My document",
    "pdf": "JVBER...",
    "merchantSealPosition": {
        "x": 100,
        "y": 80,
        "page": 1
    },
    "endUserSealPosition": {
        "x": 200,
        "y": 80,
        "page": 1
    }
}
]

resultContent

(required)

JSON array of string. Must contain at either "padesSignedPdf" or "padesAppendix" or both.

The string values will determine the content result when retrieving a completed sign order later:

"padesSignedPdf": Result contains the signed PDF as a base64 encoded string.
"documentHash": Result contains the SHA256 hash over the unsigned and sign document hash.
"padesAppendix": Result contains the appended signature data to the original PDF document as a base64 encoded string.

See result specifiers in the PAdES section in Scopes and claims for details.

["padesSignedPdf", "padesAppendix", "documentHash"]

Response

Content-Type: application/json

Code

Description

Example JSON response content

201 Created

Successfully uploaded PAdES sign order

{
    "sign_id": "4120de56-4391-4e5a-adea-a28e62daac7e"
}

400 Bad request

Could not create order due to error in request. See the "errors"-array in the response for details.

{
    "errors": [
        "Missing field: 'orderName'",
        "Missing field: 'padesSignProperties'",
        "'resultContent' must contain at least one of 'padesSignedPdf' or 'padesAppendix' for PAdES orders"
    ]
}

403 Forbidden

Access token is invalid.

AccessToken is invalid - Please provide reference: AbcDEf if reporting the problem.

Example request

POST [signdoc-baseurl]/signdoc/pades
Request body:

    "signProperties": {
        "orderName": "My order name",
        "documentDisplayMode": "interior",
        "showConfirmation": true,
        "showUnderstanding": true
    },
    "padesSignProperties": {
        "addVisualSeals": true
    },
    "documents": [
        {
            "description": "Document to sign",
            "pdf": "JVBER...",
            "endUserOnly": false,
            "merchantSealPos": {
                "x": 20,
                "y": 20,
                "page": 1
            },
            "endUserSealPos": {
                "x": 200,
                "y": 20,
                "page": 1
            }
        },
        {
            "description": "Another document to sign",
            "pdf": "JVBER...",
            "endUserOnly": true
        }
    ],
    "resultContent": [
        "padesSignedPdf",
        "padesAppendix",
        "documentHash"
    ]
}

Check status of sign order

GET [signdoc-baseurl]/signdoc/pades

Request

Headers

Key	Value
Authorization	Bearer `access_token`

Query parameters

Parameter	Type	Description
sign_id	string	The sign_id that was return when uploading the signing order.

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 GENERATING_MERCHANT_SEALS USER_SIGNING ADD_DOCUMENT_SECURITY_STORE FAILED CANCELLED SIGN_COMPLETED	{ "orderState": "ORDER_RECEIVED" }
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 can not be empty - Please provide reference: AbcDEf if reporting the problem.
403 Forbidden	Access token is invalid or missing.	AccessToken is invalid - Please provide reference: AbcDEf if reporting the problem.

Example request

GET [signdoc-baseurl]/signdoc/pades?sign_id=4120de56-4391-4e5a-adea-a28e62daac7e

Delete sign order and download signing results

DELETE [signdoc-baseurl]/signdoc/pades

The sign order will be deleted if this request is made, regardless of sign order state.

Request

Headers

Key	Value
Authorization	Bearer `access_token`

Query parameters

Parameter	Type	Description
sign_id	string	The sign_id that was return when uploading the signing order.

Response

Code	Description	Example JSON response content
200 OK	Sign order was found. Returns signing results, sign_id, order state and order name. If order is not completed, i.e. order state is not "SIGN_COMPLETED", the signing results will be an empty array.	{ "signingResults": [ { "signedDocumentSha256": "u0XXG...", "padesSignedPdf": "JVBER..." "padesAppendix": "DQoxMiAw..." "description": "My order name - 1", "unsignedDocumentSha256": "QJ2y8..." } ], "signId": "4120de56-4391-4e5a-adea-a28e62daac7e", "orderName": "My order name", "orderState": "SIGN_COMPLETED" }
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 can not be empty - Please provide reference: AbcDEf if reporting the problem.
403 Forbidden	Access token is invalid or missing.	AccessToken is invalid - Please provide reference: AbcDEf if reporting the problem.

Example request

DELETE [signdoc-baseurl]/signdoc/pades?sign_id=4120de56-4391-4e5a-adea-a28e62daac7e

Multiple end user signatures in the same envelope

Multiple end user signatures in the same envelope is supported through serial signing. In serial signing, the order of the signatories matters because any signatures that already exists in the document are part of the data that is signed over. The output from one signing session is used as input for the next. That means that the signed document is uploaded to the SignDoc resource server, the merchant receives a new sign_id and initiates a new signing session with this sign_id for the next end user to sign and then downloads the document with multiple end user signatures. For any signature sessions following the first, you would like to set endUserOnly to true for all documents when uploading the order to the SignDoc resource server to prevent multiple merchant signatures.

Page tree

Full flow PAdES API and implementation guide

Overview

Sequence diagram

Granting access to the SignDoc resource server

Upload sign order to SignDoc resource server

Request

Headers

Request body

Response

Example request

Check status of sign order

Request

Headers

Query parameters

Response

Example request

Delete sign order and download signing results

Request

Headers

Query parameters

Response

Example request

Multiple end user signatures in the same envelope