REST API
signoSign/Universal has a REST API for integration. This section will focus less on the technical application of the API and more on the underlying concept.
A list of all available API calls plus structure and documentation can be found in the Swagger UI.
The API is divided into the following areas:
The individual areas will be discussed in greater detail later.
General information for understanding
This technical documentation explains the terms and facts in connection with instance tokens, sessions, containers, viewers, and access URLs.
Instance token:
An instance token is a unique character string, comparable to an API key. It must be provided as a means of authorization each time a protected REST endpoint is called and acts as an access key to a container.
Container:
A container describes the context of a user on the server. A container can be accessed independently of a session using the instance token. In most cases, it is assumed that a single viewer is present in a container, but it is also possible to have several viewers in one container.
Session:
A session describes the session context of a browser with the server. It represents the interaction of a user with the application during a certain period of time.
Viewer:
Viewers are always part of a container. They provide a context into which a document can be loaded. In most use cases, it is assumed that a container contains a single viewer. However, it is possible for a container to potentially contain several viewers.
Loading a document:
A document is always loaded into a viewer. The document remains loaded until it is actively unloaded, the instance token is revoked, or the associated session expires.
Session expiry:
A session depends on the timeout defined in web.xml. The default setting is 60 minutes. External calls of shared documents are an exception. Your session ends automatically after 10 seconds when you exit the viewer.
Access URL:
An access URL is a uniquely usable URL that connects a session to a viewer container. It is always issued for a specific viewer. When an access URL is called up, a connection is automatically established between the session used and the corresponding viewer container. An access URL should be created immediately before use, as it is automatically destroyed after use to ensure maximum security.
Recommendations:
An instance token is an important access key to the context of a user on the server. To ensure smooth and secure operation, we recommend the following best practices for handling instance tokens:
Creation of instance tokens:
An instance token should always be created for a session. It is advisable to generate an instance token for each session to enable clear assignment.
Consistent assignment of instance tokens and sessions:
A session should not be linked to different instance tokens. It is important that a session only uses one instance token at a time during its runtime in order to avoid inconsistent states or access problems.
Active unloading of documents:
After a process has been completed, documents should be actively unloaded to free up resources and reduce memory consumption. This can be done either by unloading the document manually or by revoking the associated instance token.
By following these recommendations, you can ensure consistent and efficient use of instance tokens and avoid potential issues related to session management and document loading.
Using the Viewer
The concept for using the Viewer is defined as such that an instance is...
Generated—by requesting an instancetoken.
and removed—by revoking the instancetoken.
If a Viewer is not removed by revoking the instancetoken, the instancetoken and the associated Viewer may continue to be used. In multi-Viewer scenarios, the Viewers should ideally be created by one instancetoken, instead of generating an instancetoken for each Viewer.
Preparing the Viewer
As soon as a Viewer has been instantiated, it can be configured and a document can be loaded. The preparation can be divided into two areas:
Preparation of the Viewer itself, for example:
adding, modifying and deleting cookies to communicate with third-party systems (for example, remote saving)
Preparation of a loaded document, for example
A Viewer can only ever have one document loaded at a time. As soon as another document is loaded, the old document is overwritten together with any document-related settings.
Calling the Viewer
A Viewer generated through an API can only be accessed via a URL that can be called with a call to the API. This access URL is a URL to signoSign/Universal containing a generated character string that grants one-time authorised access to the Viewer. When calling, the session of the calling client is logged in using the access data with which the instancetoken was also requested. The client remains logged in until an explicit logout is carried out or the instancetoken is revoked. Calling the URL automatically invalidates this. Please also note that any number of URL can be created for an instance.
A server session can open any number of Viewers of one instancetoken. The Viewers of a second instancetoken can only be opened once all Viewers of the first instancetoken have been closed.
Managing persistent documents
The API allows you to manage persistent documents in the configured database. Documents in the database can be loaded directly into the Viewer using their numeric ID.
The API provides the following functions here:
Does not work when using a custom persistence implementation.
Managing shared documents (sharing cases)
Shared documents can also be managed via the API.
The API provides the following functions here:
Does not work when using a custom persistence implementation.
Managing keystores (certificates)
signoSign/Universal requires two difference certificates; one for digital signatures and one for the encryption of biometric data. These certificates must be made available to signoSign/Universal in keystores.
This concept has two steps:
Uploading a keystore containing the necessary certificates
Assigning certificates to a user within a keystore with a certain purpose
Certificate purposes:
Assigning a certificate to a user always fulfills a certain purpose. Assigning a certificate can fulfil one of the following purposes:
SIGNING is used to sign the document digitally. This ensures the integrity of the document. signoSign/Universal requires both a private key and a public certificate here.
ENCRYPTION is used to encrypt the signer’s biometric data. This ensures the traceability of a signature. signoSign/Universal only requires a public certificate here; the associated private key should be stored in a separate, safe location.
The API provides the following functions here:
If a user is not assigned any certificates, signoSign/Universal creates the relevant certificates itself if a certificate is required.
Does not work when using a custom persistence implementation or a global keystore.
User roles and the ownerId
Some functions have an ownerId parameter. This parameter allows functions to be executed in the name of this user. For example, user A can download a document from user B. However, this is only possible if user A has both the ssu-user role and the ssu-admin role.
If the ownerId parameter is left empty, it will be assumed that this value is the name of the user making the request. An access violation occurs if a user without the ownerId role transfers the parameter and this does not match the name of the user performing the action.
Requesting detailed document information
Information on a document can be requested as soon as it has been loaded in the Viewer.
The resource GET /viewer/document/information is used for this purpose.
The following information can be retrieved:
General information on the document such as
the document ID
the total number of signature fields
the total number of signed signature fields
the total number of signed mandatory signature fields
the total number of form fields
the total number of form fields that have been filled out
the total number of mandatory form fields that have been filled out
the number of pages
Information on all signature fields
the HTML ID below which the signature field is displayed in the Viewer
the horizontal position of the page in pixels
the vertical position of the page in pixels
the width in pixels
the height in pixels
the name of the signature field in the PDF
a Boolean value stating whether the signature is mandatory
a Boolean value stating whether the field is displayed in the Viewer
Rendered images of the pages as Base64 strings
The current state of the document in binary data
Proprietary HTTP status codes
In individual cases, the REST API uses proprietary codes in addition to standard codes to enable special cases to be handled.
Code | Message | Description |
|---|---|---|
599 | Conflict configuration | The request cannot be processed because it is in conflict with the server settings or the required functionality has not been configured sufficiently. |
Managing workflows
signoSign/Universal makes it possible to automate workflows with the resource REST API Resource Workflows. A workflow and the data used in it are specified in a template (blueprint) which can then be started any number of times.
Blueprints
A blueprint defines a complete workflow and the data processed within it. A newly created workflow is empty and must be filled with steps. It is then possible to start the blueprint. Every start creates a process. Subsequent changes to the blueprint have no effect on the processes.
Deleting a blueprint deletes the steps and all processes. Blueprints that are linked to an active process cannot be deleted.
Blueprint steps
The blueprint steps define what actions are to be performed and in what sequence. Steps can be performed sequentially, in parallel or in a mixture of the two variants.
Actions
When a step is created, its type specifies the type of action. The REST API provides an endpoint for each type.
DEMAND_SIGNATURE
A document folder is shared via e-mail. The documents can be opened and signed in the signoSign/Universal Viewer via a link in the e-mail.
POST /workflows/blueprints/{blueprintId}/steps/demandSignature
POST /workflows/blueprints/steps/{stepId}/demandSignature/documents
Sequence
Indices are used to define the start sequence for the workflow steps. Each step contains an attribute stepIndex and nextStepIndex.
stepIndex
The stepIndex attribute specifies when the step is to be performed. An index can be used by several or all steps. The list of indices for all steps together must begin with 1 and continue with consecutive numbers (1, 2, 3, etc.), otherwise it will not be possible to start the blueprint.nextStepIndex
The nextStepIndex attribute specifies that steps with this stepIndex are to be performed afterwards. A step with stepIndex == N is only performed once all steps with nextStepIndex == N have been completed. Steps that are not blocked by a nextStepIndex attribute are started when the blueprint is started.
Document folders
Workflow steps are linked with documents by means of collections (DocumentFolder). A folder can contain any number of documents and a document can only be linked to one folder.
As standard, an empty folder is created for each step that involves processing documents. If a document is allocated to the step, a copy of the document is stored in the folder. If two steps are to process the same document, they must use the same folder. The folder can be specified either when the step is created or later on when the document is linked. In each case, the parameter documentFolderId is used.
Processes
A workflow process represents a blueprint that has been started. For each blueprint step, the process contains an event with a copy of the work data of the blueprint step. Subsequent changes to the blueprint do not affect the process or its events.
The REST API can be used to start, query and delete processes. Deletion removes the process and its events, including the work data, such as the documents. Active process cannot be deleted.