Plugin action

A signDocument plugin is responsible for serving these actions:

signDocument:getCertificates returns a certificate list of which the user can select a certificate for signing.
signDocument:addSignature signs a specific, already existing signature field of a PDF document.

The plugin receives a JSON object with all required parameters and returns as result a JSON object as defined below.

The implementing code must ensure that the PDF is only saved using the incremental save method. SignDoc SDK supports this feature. If the code does not take care of this, the signed document will be rejected by SignDoc.

Optional attributes may be null or not be present.

signDocument:getCertificates

JSON input

action (required, string, utf-8): Defines the action to perform. Fixed value: signDocument:getCertificates

Input example:

{
  "action": "signDocument:getCertificates"
}

JSON output

The plugin must return a JSON object that lists all certificates the user can choose from in this format:

certificates (required, JSON array): A list of certificate objects (see below) that can be used for signing.

Certificate object (see certificates):

certificate (required, DER, Base64): The binary certificate.
subject (required, string, utf-8): The common name of the certificate's subject.
issuer (required, string, utf-8): The common name of the certificate's issuer.
expiry (required, date-time string ISO 8601-1:2019, utf-8): The certificate expiry date and time.
key (required, string, utf-8): The type (RSA or ECC) and length in bits of the certificate's key, separated by a dash.

Output example:

{
  "certificates": [
    {
      "certificate": "MIIF8zCC...kf5L9fQdYo",
      "subject": "Jane Doe",
      "issuer": "GlobalSign GCC R6 AATL CA 2020",
      "expiry": "2023-04-12T11:28:55Z",
      "key": "RSA-2048"
    },
    {
      "certificate": "MIIC1TC...PjKHoJ",
      "subject": "John Doe",
      "issuer": "ACME inc",
      "expiry": "2024-05-11T10:12:52Z",
      "key": "RSA-2048"
    }
  ]
}

signDocument:addSignature

JSON input

action (required, string, utf-8): Defines the action to perform. Fixed value: signDocument:addSignature
activationKey (required, string, utf-8): A key that can be used to activate and use SignDoc SDK.
document (required, byte[] / PDF, Base64): The PDF document that should be signed by the plugin.
field (required, string, utf-8): The plugin shall sign the specified signature field.
signerInfo (required, JSON object, utf-8): Some additional signer information map. At least the key "name" is present. "email" is usually also present but cannot be guaranteed. Besides these two attributes there might be other signer related information present.
certificate (required, DER, Base64 ): The certificate to use for the digital signature.
biometricKey (optional, byte[], Base64): If biometricKey is present, it should be used by the plugin to add encrypted biometric data to the document when signing the signature field. If not present, no biometric data shall be stored with the signature.
biometricData (optional, byte[] / SignDoc SDK biometric signature data, Base64): If biometricData is present, the plugin shall use the data to render the signature appearance and/or store the biometricData in the document when signing - whatever applies.
appearanceImage (optional, byte[] / png or jpeg, Base64): If present, the appearanceImage shall be used by the plugin to set the signature field appearance. This has precedence over the image rendering of biometricData.
custom (optional, string, utf-8): Custom plugin configuration that can be defined per SignDoc account by a SignDoc account administrator. The data is a single string that can be set in the SignDoc account configuration. If complex or binary data is required, it can be stored as Base64-encoded data in the SignDoc account configuration. It is completely up to the plugin to decipher and interpret this attribute.
language (optional, string, utf-8): The signer's language setting as ISO 639 two-letter code.
country (optional, J string, utf-8): The country/region code for this locale, which should either be the empty string, an uppercase ISO 3166 two-letter code, or a UN M.49 3-digit code.

Input example:

{
  "action" : "signDocument:addSignature",
  "activationKey":"h:SignDoc SDK 5.0.1\nx:2022-03-24T09:38:44Z\ns:6912b56e3...",
  "document" : "JY/ZzsKqxQyRkcaZcGL4jJ...",
  "field" : "fieldname",
  "signerInfo" : {
    "name" : "John Doe",
    "email" : "signer@example.com"
  },
  "certificate" : "c29tZSBleGFtcGxlIHRleHQ=...",
  "biometricKey" : "qpjMhpQpXtM...",
  "biometricData" : "0lfMIYPUIhpmY0oY...",
  "appearanceImage" : "lAf+b4T7y...",
  "custom" : "1234567890\n23456",
  "language" : "en",
  "country" : "US"
}

JSON output

After successfully performing the action, the plugin must return a JSON object that follows this specification:

document (required, byte[] / PDF, Base64): The signed document.

Output example:

{
  "document" : "KqxQyRkcaZcGL4jJ..."
}