BankID Signing Pades-V1 Field Description¶
POST¶
Parameters¶
signProperties¶
Object containing properties that influence the signing process.
signProperties.orderName¶
A name for the sign order. Currently no other effect than identification for merchant and BankID.
signProperties.timeoutSeconds¶
Defines the time period that is allowed between the merchant creating a sign order and the signing user starting the signing process (by clicking the sign button). After the signing process is started by the user this timeout has no further influence and fixed timeout values come into play to detect hanging or abandoned sessions etc..
Defined in seconds, the default currently is 1800s (30 minutes).
Technically this is the time allowed for the sign order to remain in the order state ORDER_RECEIVED.
Should the signing not be started before the timeout is reached, the sign order will time out and eventually be deleted.
signProperties.redirectUrl¶
Defines a merchant endpoint to which BankID Signing will redirect the user after signing is completed (successfully or not).
padesSignProperties¶
Object containing Pades-specific properties.
padesSignProperties.addVisualSeals¶
Controls if the visual seal (graphic representing the signature) is added to the document or not. Even if set false the document still contains signatures of course.
padesSignProperties.extendToLTA¶
Requests an LTA timestamp to be added to the document(s) after signing is completed.
padesSignProperties.useConversion¶
Validates and if necessary converts the document (PDF) to specified PDF/A version and conformance level.
Note that conversion does changes to the document and will not accept already signed PDFs as this would invalidate the signatures!
Currently only PDFA_2B is supported.
documents¶
JSON array of document-objects containing the documents to be signed.
documents.description¶
Description of the document. Displayed to the end user in the UI as the document title.
If not specified, orderName from signProperties will be used combined with a number, i.e. "My order name - 1" for the first document.
documents.pdf¶
PDF document contents as Base64 encoded string.
Maximum file size and number of files are limited.
Note that large files (typically files with a large number of images) or a large number of files can impact performance and processing time severely. We reserve the right to adjust the limits to the number of documents and size of single documents accordingly.
documents.endUserOnly¶
Set to true if only the end user signature is desired. Currently not yet evaluated.
documents.endUserSealPos¶
Defines an alternate position of the end user´s visual seal in the document.
The seal will be positioned according to the x and y coordinates (in points) with origin in the upper left corner. The default position is x=0 and y=0 on page 1.
Coordinates and page number will be validated and this method will return errors in the error list of the response if the values given are invalid. Errors will also be returned if the seal position overlaps with another seal or existing annotation in the PDF.
This means that at the moment the responsibility for either making sure that the default seal position is free or placing the seal correctly using this parameter lies with the merchant. Note that this also concerns multiple signatures of the same document. An automatic adjustment of at least the default the seal position will follow soon.
documents.pdfSpec¶
Defines the targeted PDF specification for conversion. Currently only PDFA_2B is supported.
resultContent¶
Object containing properties that influence the result returned from signing.
resultContent.requestSignerInfo¶
Requests a JSON Web Token containing signer information to be added to the result. Not yet implemented.
Response Fields (HTTP-201)¶
The fields in the response will vary, empty fields are not returned.
sign_id¶
The sign order ID given to the sign order created. Use this for the GET and DELETE methods and also to refer the end user to the signing UI.
conversionResults¶
Array of JSON objects containing results and warnings per document, in the order documents were submitted.
conversionResults.converted¶
Shows if the document was converted or not. Usually this shows false if conversion was not requested or if the conversion failed.
conversionResults.conversionErrors¶
Array of error messages describing why the document was rejected.
conversionResults.conversionWarnings¶
Array of warnings notifying about possible problems with the document. Warnings do not prevent acceptance or conversion of a document.
DELETE¶
Parameters¶
sign_id¶
Sign order ID of the sign order that is to be deleted.
Response Fields (HTTP-200)¶
The fields in the response will vary depending on if the signing was completed or not. If not, only the first three fields will be used.
signId¶
Sign order ID of the sign order that was deleted.
orderName¶
Oder name of the sign order that was deleted.
orderState¶
Order state of the sign order at the time of deletion.
signerInfo¶
JSON Web Token containing signer information. Only present if signerInfo is set to true in resultContent.
signingResults¶
Array of JSON objects containing results of the signing process. Only present for successfully completed sign orders.
signingResults.signedDocumentSha256¶
SHA256 of the signed document.
signingResults.padesSignedPdf¶
Signed PDF document as Base64 encoded string.
signingResults.description¶
Description of the document being either the submitted description or one created if none was given.
signingResults.unsignedDocumentSha256¶
SHA256 of the unsigned document.