5.2 Add document to package
5.2.1 Description
This call will add a document to an existing package.
Notes:
- A package must not exceed 150 MB.
- A package must not contain more than 15 documents and each document must not exceed 30 MB.
- An .xml must not contain more than 2 million characters per file. A package must not contain more than 15 .xml files.
- Large files might affect signing performance depending on the user's Internet connection.
- A PDF document’s physical dimensions must not exceed 3.99 m by 3.99 m.
Signature field locations for PDFs can be set either using coordinates in the document or the id of an object in the document. See section 10.2 for more info about such objects.
The supported upload document formats are docx, doc, pdf, plain text, and xml. Note: some of these formats might be disabled in the eSignatures configuration.
The response on this request will return a unique document GUID and unique ids for each of the proposed signing field locations.
Note: it is possible to add a document to a package where the "Set Process Information" call has already been run (see section 5.4). However, it is then necessary to run the “Set Process Information” call again before changing the package status to Pending.
Remarks:
Uploading PDF/A documents is only allowed if the format is PDF/A_2A or PDF/A_1A. When using itsme as signing method, it is mandatory to use PdfA1A or PdfA2A as TargetType. Note however that Connective does not perform any checks whether this TargetType has been selected.
Rotated PDFs should not be used together with text markers. Detected signature locations will not be rotated to match the PDF text direction but will be placed near the text marker on a best-effort approach.
When you upload PDF documents that contain Text Fields of which the name/id complies with the Text Field format you have configured in the Configuration Index, the Text Fields will be converted to empty signature fields in the output document and the original Text Field will not be displayed. This is intended behavior.
Note: the remark above does not apply in case you upload a document that already contains one or more signatures – whether they have been created in eSignatures or another signing application.
When uploading PDF documents that already contain signature fields - which you created in a PDF solution such as Adobe Acrobat Pro DC - make sure the signature field names only contain letters and numbers, or a combination of both. Any special characters such as accented letters, slashes, dots, etc. are not supported and must not be used. The same limitations apply when uploading PDF documents that contain text fields.
Packages currently can't contain both XML documents and PDF documents on which signatures will be placed. The type of package is determined by the first uploaded document.
5.2.2 URL
https://[servername]:[port]/webportalapi/v3/packages/{id}/documents
5.2.3 HTTP Method
POST
5.2.4 MIME Type (JSON + Base64)
application/json
5.2.5 MIME Type (Multipart)
multipart/form-data
This call expects the same input and will deliver the same output as the non-multipart version above, but the Document variable in the JSON must not contain a base-64 encoded pdf file. Instead the call will expect the document to be included as a different “part” of the request:
Request entity | Content type | Description |
---|---|---|
Data | application/json;charset=utf-8 | Json request |
Document | application/octet-stream | Document which needs to be signed |
Representation | application/octet-stream | A PDF to be shown together with the document to be signed. See the Representation parameter below for its restrictions. |
Note: eSignatures v5.1 and earlier looked for a part named ‘pdf’. This is deprecated but still works.
5.2.6 Template parameters
Parameter | Occurrence | Content / Description | Type |
---|---|---|---|
id | Required | Unique id for the signing package | String |
5.2.7 Request parameters
Parameter | Occurrence | Content / Description | Type |
---|---|---|---|
Document | Conditional | Attached document in base64 encoded format. Required unless Multipart format is used. |
String |
DocumentLanguage | Required | Language to use in signature texts. Currently supported: en, nl, de, fr, es. This is also the language that will be used for legal notices when LegalNoticeCode is filled for an Actor. |
String |
DocumentName | Required | Name of the document to be shown in the eSignatures Portal. Note: do not add an extension to the DocumentName value. Important: Pay attention when choosing a document name. Don’t use forbidden file name characters such as slash (/), backslash (), question mark (?), percent (%), asterisk (*), colon (:), pipe (), quote (‘), double quote ("), less than (<), greater than (>). Note however, that is list is not exhaustive. Don’t use characters that are HTML-sensitive such as ampersand (&) or apostrophe (‘). Note: when using itsme signing, only use characters that are supported by ISO 8859-15. This character set supports most usual characters, but some software-generated characters like curly apostrophes and long dashes are not supported. |
String |
SigningFields | Required | See section 5.2.7.1 below. | Array of objects |
CorrelationId | Conditional | Id that indicates which documents within this package are correlated with documents that have been signed in the past in other packages. This CorrelationId can later be used to retrieve all Audit proofs related to this document across many packages. See section 7 for more information. Important: the CorrelationId value must be unique within the same Package. Important: The Audit proofs setting must be enabled in the eSignatures Configuration Index to use this parameter. |
String |
DocumentType | Optional Required for XML signing |
Type of document that will be signed. Supported values: application/pdf (default) application/xml Word processing and text files are always converted to PDF. |
String |
ExternalDocumentReference | Optional | Reference given by the calling application. This parameter will not be used by the eSignatures Portal. | String |
PdfErrorHandling | Optional | How to deal with PDFs containing minor flaws. See section 4 below for more info. Values: Ignore DetectWarn DetectFail DetectFixWarn DetectFixFail |
Object |
Representation | Optional Forbidden for PDF signing |
Attached representation document in base64 format. This must be PDF data. | String |
RepresentationType | Conditional | Type of the representation document. Must be present when Representation is filled. Only "application/pdf" is supported. | String |
TargetType | Optional | The TargetType defines if an extra conversion to PDF/A needs to be done before signing. Values: PdfA1A PdfA2A Notes: This will only work if the Document Conversion settings have been enabled in the Configuration Index. Existing signatures will be removed unless the PDF is of the specified type. When using itsme as signing method, it is mandatory to use PdfA1A or PdfA2A as TargetType. Note however that Connective does not perform any checks whether this TargetType has been selected. |
String |
5.2.7.1 Signing Field Position
Important: A single document must not contain more than 30 signing fields.
PDF signing
The location of each signature field on a PDF can be set by either using coordinates in the document (PageNumber, Width, Heigth, etc.) or by using the id of an object in the document (the MarkerOrFieldId parameter.) See section 10 for more info.
When placing a field on a PDF it should at least be 112 points wide and 70 points high. Note: it is recommended to use slightly higher values than the minimum ones. E.g. 75 points x 120 points. Using the absolute minimum values may lead to round-off errors during conversions.
When using the MarkerOrFieldId parameter, then all other parameters except Label are forbidden. The label will by default be generated from the text marker id part, text field id or signature field id. Specifying the Label parameter overrides the default label.
When you choose not to use the MarkerOrFieldId parameter, then you must use all coordinates parameters: PageNumber, Width, Heigth, Left, Top.
XML signing
XML signing does not allow for coordinates or markers to form a visual signature. Instead, all signature data will become part of the XML document and will be added at the end. This is determined by the XML signing specification eSignatures uses. It's the specification that determines how the signature is placed between the XML tags.
Note that all parameters except Label are forbidden. The Label parameter is required.
Note: every Label value should be unique within a document. This also implies that when a MarkerOrFieldId parameter is used without Label as override that this marker id should be unique in the document and not clash with other labels.
Parameter | Occurrence | Content / Description | Type |
---|---|---|---|
SigningFields(array of objects) | Required (1-n) | One or more signing locations in the document | Array of objects |
PageNumber | Conditional | Number of the page on which to add a signing location. First page is number 1. Zero (0) is not supported. Negative page numbers work as described in section 10.1. | Integer |
Width | Conditional | Width Minimum value is 112. It is recommended to use slightly higher values than the minimum ones. |
String |
Height | Conditional | Height Minimum value is 70. It is recommended to use slightly higher values than the minimum ones. |
String |
Left | Conditional | Position from the left of the page. Minimum value is 1. Negative values are not supported. |
String |
Top | Conditional | Position from top of the page. Minimum value is 1. Negative values are not supported. |
String |
Label | Conditional | Text string which identifies this location for later use | String |
MarkerOrFieldId | Conditional | Unique reference to a signing field, text marker or textfield. See section 10.2 for more details. | String |
5.2.8 Response parameters
Parameter | Content / Description | Type |
---|---|---|
DocumentId | Unique id for the document | String |
CreationTimestamp | Date and time the flow was created. Format: YYYY-MM-DDThh:mm:ss+zz:zz | String |
Locations | See table below | Array of objects |
Parameter | Content / Description | Type |
---|---|---|
Locations (array of objects) | Represents a possible location for a signature | Array of objects |
Id | Unique id for this location | String |
Label | Detected or specified label | String |
PageNumber | The page on which the location was found. Numbering starts with 1 and the highest possible index is equal to the number of pages in the document. | Integer |
5.2.9 Example request
{
"Document": "JVBERi....rest-of-the-document",
"DocumentName" : "Invoice",
"DocumentLanguage" : "nl",
"ExternalDocumentReference" : "INV-2019-04-01-0038",
"SigningFields" : [
{
"PageNumber" : 1,
"Width" : "120",
"Height" : "200",
"Left" : "100",
"Top" : "200",
"Label" : "ThisIdentifiesJohnDoeHisSignatureLabel"
}
]
}
5.2.10 Example response
{
"DocumentId": "e0cb4de4-673d-49fc-9bd1-7c81248984f9",
"CreationTimestamp": "2019-03-28T08:54:38+00:00",
"Locations": [
{
"Id": "8a96613f-b6ed-4227-9bde-c20d3ee0c9d6",
"Label": "ThisIdentifiesJohnDoeHisSignatureLabel",
"PageNumber": 1
}
]
}
5.2.11 Response codes
Response status code | Description |
---|---|
200 OK | The document was correctly added to the package. The response contains more information about the locations where a signer can place a signature. |
400 Bad Request | The request contained parameters which could not be accepted. |
404 Not Found | The package id could not be found in the database. |
409 Conflict | When certain document conversions are forbidden, when the input document has issues, or when marker ids are not matched. |
5.2.12 Error codes
HTTP Code | Code |
---|---|
400 | Request.RequiredFieldIsMissing |
400 | Document.InvalidTargetFileType |
400 | Document.NameInvalidLength |
400 | SigningField.MarkerAndCoordinatesCannotBeMixed |
400 | SigningField.MarkerNotUnique |
400 | SigningField.InvalidWidthCoordinate |
400 | SigningField.InvalidHeightCoordinate |
400 | SigningField.InvalidPage |
400 | Document.PasswordProtected |
400 | Pdf.UploadDoesNotComplyToSpec |
400 | PdfErrorHandling.InvalidType |
400 | Document.UnsupportedLanguage |
409 | Package.ApiVersionMismatch |
409 | Package.InvalidStatus |
409 | User.NotFound |
409 | Document.InvalidSourceFileType |
409 | Document.InvalidTargetFileType |
409 | SigningField.InvalidWidthMarker |
409 | SigningField.InvalidPage |
409 | SigningField.InvalidHeightMarker |
5.2.13 PDF Error Handling Details
Some PDFs might have minor flaws which prohibit signing. Depending on the request parameters and the configuration settings, PDFs are either only checked or also modified to remove those flaws.
Note: The PDF will never be fixed if it already contains signatures, otherwise these signatures would become invalid. The presence of signatures and a PDF flaw might then trigger an error or warning depending on the choices below.
The PdfErrorHandling parameter defines the behavior, though the configuration settings might define the behavior if this parameter is not specified. Here are the different actions for the parameter:
Ignore
Ignore means no checks or fixes will be done. Any document will be accepted but this might later be impossible to sign or result in a PDF with signature validation errors should a PDF flaw be present. This is the default value if this parameter is not specified and the eSignatures configuration has no different value.
DetectWarn
When there is an issue, it will be detected and a warning is added to the eSignatures log file. The upload will still proceed. The upload will still proceed.
DetectFail
When there is an issue, an error is added to the response and the upload is stopped.
DetectFixWarn
When there is an issue, the system will detect and try to fix it. When it’s not possible to fix it, a warning is added to the eSignatures log but the upload will still proceed.
DetectFixFail
When there is an issue, the system will detect and try to fix it. When it’s not possible to fix the document, an error is added to the response and the upload is blocked.
Note: these actions – ‘Ignore’ excluded – influence the speed of the system in different ways. See appendix II of the eSignatures Configuration Guide for an overview of the steps a document goes through when the other options are selected.