2. Download

This chapter explains how to configure the REST connection in the SIGNATUS settings, under the section “Download using REST channel”.

2.1 Login with basic authentication and cookies #

Login and Authentication #

Login is required to enable cookie-based authentication.

• With login URL configured:
• The login operation is the first step in communication with the server.
• The request includes the username and password in the Basic Authentication header.
• The server responds with a cookie.
• This cookie is then sent in the header of all subsequent requests.

• (Android version only) Without login URL configured:
  • If only the list URL is configured, Basic Authentication is used instead.
  • In this case, the username and password are sent in the Basic Authentication HTTP header with each request.
  • The credentials are used directly for business-related operations (e.g., list of documents, document download, document upload).

2.2 Login with Open ID Connect (Android version only) #

If the channel settings specify a non-empty Token URL, the system uses the OpenID Connect Authorization Code Flow. (See the OpenID Connect specification for details.)

User Authentication

• The login URL (the “authorization endpoint” in OpenID Connect terminology) is opened in a web browser.
• The user authenticates using any method supported by the authorization server.

Authorization Code Retrieval

• After successful authentication, the authorization server redirects the browser to the specified redirect_uri.
• This redirect includes an authorization code as a URL parameter.

Access Token Request

• SIGNATUS exchanges the authorization code for an access token.
• This is done via an HTTP POST request to the configured Token URL.
• The server responds with an access token (and optionally a refresh token).

Access Token Usage

• The access token is included in the Authorization header of all subsequent API requests.

Token Renewal

• If the token response contains a refresh token, it is used to obtain a new access token.
• The refresh occurs automatically when the access token is close to expiring or has already expired.

2.3 List of documents #

List is used to browse the download channel. It returns either:

• a list of documents available for download, or
• a list of folders that contain documents.

The List request returns a JSON object from the server.
Based on the data in this object, the SIGNATUS application generates a list of documents.

The JSON response includes the following properties:

Example response showing a list of documents:

[
	{
		"filename": "contract.pdf",
		"id": "123456789abcde"
		"url": "https://...?id=123456789abcde",
		"customerNamename": "custom metadata",
		"contractNumbernumber": "123456",
		"state": "tosign"
	},
	{
		"filename": "test.pdf",
	...
]

[
	{
		"filename": "contract.pdf",
		"id": "123456789abcde"
		"url": "https://...?id=123456789abcde",
		"customerNamename": "custom metadata",
		"contractNumbernumber": "123456",
		"state": "tosign"
	},
	{
		"filename": "test.pdf",
	...
]

Example response showing a list of folders:

[
	{
		"filename": "customer1_case1",
		"id": "2468abcd"
		"url": "https://...?id=2468abcd",
		"type": "F",
		"customerNamename": "customer1",
		"caseNumbernumber": "case1",
		"signedCount": 1,
		"totalCount": 2
	},
	{
		"filename": "customer1_case2",
	...
]

[
	{
		"filename": "customer1_case1",
		"id": "2468abcd"
		"url": "https://...?id=2468abcd",
		"type": "F",
		"customerNamename": "customer1",
		"caseNumbernumber": "case1",
		"signedCount": 1,
		"totalCount": 2
	},
	{
		"filename": "customer1_case2",
	...
]

2.4 Download document #

Download is triggered when the user selects a document from the list.
The SIGNATUS application then retrieves the PDF file using the URL provided in the JSON response of the List request.

2.5 State acknowledgment #

Acknowledge is used to notify the server about important events related to a document.
For example, after a document has been successfully downloaded to a device, the application sends an acknowledge message to the server.
This allows the server to update the document’s state (e.g., mark it as “in progress”) and prevent it from being offered for download to other users.

The request body parameters: