Getting started (Postman Collection)

The provided Postman Collection can be used to take the first steps toward integrating the signoSign/Universal REST API.

Preparation

The demo is based on the collection and the following PDF document, which contains the corresponding search texts and input fields for the examples.

• signotec signoSignUniversal Demo Document.pdf

• https://www.postman.com/signotec/signotec-signosign-universal

After importing the Postman Collection, the collection variables for username and password must be adjusted. To do this, double-click to open the imported folder and select the “Variables” tab.

Once the server and access data have been correctly stored, the following use cases can be executed.

Upload document and sign locally

The “Upload and Sign a Document” folder contains all API calls that can be used to upload a document, open it locally, and sign it.

1. Log in to generate an instance token.

2. When uploading a document, add the document to the body in the parameter “document” and execute.

3. Load document into the Viewer.

4. (Optional) Set an index so that an assignment can be made during remote save. The index value must be adjusted in the body.

5. Set dynamic signature fields using a search text.

6. Set dynamic signature fields using another search text.

7. Placement of a static signature field.

8. Update the Viewer configuration to set the “Remote Save URL” and configure other Viewer settings.

9. The URL of the current Viewer: retrieve it.

10. Open the URL in a new tab, fill out the document, and sign it.

Upload document and send for remote signature

The “Upload and Share a Document” folder contains all API calls that can be used to upload a document and send it to the signer.

1. Log in to generate an instance token.

2. When uploading a document, add the document to the body in the parameter “document” and execute.

3. Creating the “sharing cases”. The body must be adjusted in this call.

   1. If a notification is to be sent directly from the system by email, the recipient must be specified in the parameter “emailAddressee”.

   2. The parameter “documentConfiguration” can be used to specify a configuration for the sharing case and document, in which, for example, the forwarding destination or the positions of the signature fields can be specified.

   3. There are four options for authentication in the call:

      1. “password” is left blank → No authentication required

      2. “password” is provided → The recipient must enter the password before the document can be opened.

      3. “tanAddressee” is included → Authentication via TAN required.

      4. Neither “tanAddressee” nor “password” provided → Password is automatically generated and returned in the response.

4. (Optional) Adjust the sharing case configuration if individual settings need to be adjusted again.

5. There are various ways in which the signatory can be informed about the sharing case that has now been created.

   1. If the notification is to be sent from the integration, the link to the sharing case can be retrieved. This can then be communicated to the recipient in a flexible manner.

   2. The notification can also be sent directly from the system. To do this, the notification endpoint (“notify”) is called. When calling, the language of the notification can be selected using the body parameter “locale”.

If you want to delete the sharing case, you can do so at any time by selecting “Abort sharing case.” The associated links become invalid, so that users who have already been notified can no longer access the document. The document itself remains in the application and must be deleted separately if required.

Upload document and send it in the workflow

The “Upload and Workflow Document” folder contains all API calls that can be used to upload a document and create and start a workflow.

1. Log in to generate an instance token.

2. Creating the “workflow plan”. The name of the plan can be customized using the parameter “name”.

3. Create a document folder. This is where the documents for the workflow are collected.

4. Upload the document in the body in the parameter “document” and add it to the created document folder.

5. Next, the workflow steps are created. Any number of recipients can receive the document simultaneously or in a specific order. It is also possible that the document folder varies depending on the recipient. Before execution, at least the following parameters should be adjusted to ensure that the document reaches the correct recipient:

   1. The name of the recipient can be specified using the parameter “signerName”.

   2. The email address to which the process is sent is specified in the parameter “signerEmail”.

   3. To additionally protect the recipient’s documents with a password, this can be specified in the parameter “password”.

   4. As an alternative to the password, and similar to the sharing case, a TAN recipient can be created with the parameter “tanAddressee”.

6. Creates a second workflow step that is executed after the first one has been completed. For this call, at least “signerName” and “signerEmail” should be adjusted before execution.

7. Starts the created workflow. When starting, a name can be added in the body parameter “name.” This name will also be displayed in the user interface and can simplify assignment. After a successful start, the persons from step 1 will also be notified by email. All further steps then run automatically.

If a started workflow process is to be deleted, this can be done at any time by calling up “Delete Workflow.” The associated links become invalid, so that users who have already been notified can no longer access the document.

Create and send a workflow plan

The “Create and Use a Workflow Blueprint” folder contains all API calls that can be used to create a workflow plan and then start it. A workflow plan is a reusable template for workflows. It defines, for example, the number and order of recipients as well as the documents or placeholders for them.

1. Log in to generate an instance token.

2. Create a document folder. This is where the documents for the workflow plan are collected.

3. Add documents to the document folder:

   1. The document is uploaded in the body in the parameter “document” and added to the created document folder. The parameter “placeholder” specifies that this document must be replaced at the start.

   2. Add a document from an external source via URL. The parameter “downloadUrl” specifies the URL from which the document is loaded into the document folder.

4. Creating the “workflow plan”. The name of the plan can be customized using the parameter “name”. The parameter “hidden” specifies whether the workflow plan is displayed to the user in the signoSign/Universal portal (UI) or not.

5. Create the workflow steps. Any number of recipients can receive the document simultaneously or in a specific order. It is also possible that the document folder varies depending on the recipient. Before execution, at least the following parameters should be adjusted to ensure that the document reaches the correct recipient. Instead of a fixed value, a placeholder can also be specified. This must be marked with @@placeholder name@@. All placeholders must be specified when starting in step 6.

   1. The name of the recipient can be specified using the parameter “signerName”, for example using the placeholder @@NAME_USER_1@@.

   2. The email address to which the process is sent is specified in the parameter “signerEmail”, for example using the placeholder @@MAIL_USER_1@@.

   3. To additionally protect the recipient’s documents, access can be secured with a password using the parameter “password”, for example using the placeholder @@PASS@@.

   4. As an alternative to the password, a TAN recipient can be created with the parameter “tanAddressee”, for example using the placeholder @@TAN@@.

6. Start of a new workflow from the created workflow plan. When starting, the name can be defined in the body parameter “name”. This is also displayed in the user interface and can simplify assignment. In the parameter “documents”, all placeholder documents must be replaced; the assignment is made via the document name, which must match the name from the document folder in step 3. The placeholders set for the workflow steps are passed in the parameter “parameters” in the form of a JSON object.

7. After a successful start, the persons from step 1 are automatically requested by email to process it. All further steps then run automatically.

If a started workflow process is to be deleted, this can be done at any time by calling up “Delete Workflow.” The associated links become invalid, so that users who have already been notified can no longer access the document either.

Download document

The “Download a Document” folder contains all API calls that can be used to download a document again and delete it in signoSign/Universal.

1. Log in to generate an instance token.

2. Download the document from the system.

3. After successful download, the document should be removed from the platform.