Asynchronous Mode (API)

Owned by Fernando Vicente
Last updated: Jan 20, 2022
4 min read

REST API Asynchronous Mode

Tipically used in situations where integration by API is preferred, the number of files to be signed has an acceptable range (100 - 2500) considering an average size of 200KB and where the asynchronous response of the signed documents is feasible.

The asynchronous mode provides the capacity of finishing the signature process in two steps. The first allows to start/register a new signature operation which returns an object containing the unique id, status and the host/port of the host that fulfilled the request.

The host/port information is an essential aspect when there are multiple instances of the Sign’Stash Proxy running behind a load balancer or similar. There is no synchronization between the various instances of the Sign'Stash Proxy running and therefore each one keeps its own state (signature operations).

Additionally, the Sign’Stash Proxy exposes 2 methods that allow, informing the external reference used during the creation phase, to consult the status of the operation(s) and, once it is finished, to retrieve information about the signature process that includes all signed documents.

Again, notice that according to your architecture, this new request must be made through the Sign’Stash instance that handled the initial request using the host/port obtained from it.

To enable this mode it is necessary to include parameters in addition to those of the SYNC mode.

Parameter

Description

Parameter

Description

HOST

Address of the host running the docker image (e.g. 192.168.1.1).

PATH_TO_WORK_FOLDER

Path to the working folder containing the configuration file (e.g. /path/to/work/folder).

 

Architecture

The Sign’Stash Proxy components are in gray background, the Sign’Stash SaaS is on a green background, and the blue background pertains to the client service components.

 

 

Hardware Requirements

This mode requires the following specifications in terms of disk space consumption (container volume):

  • Internal database: ~2MB/request with 1000 files (a significant percentage is reclaimed monthly by applying database housekeeping strategies automatically).

  • Temporary files: Extrapolated according the rule Double(Maximum load in number of files x File average size). E.g., 2x(20.000 files x 200KB) = 8GB.

Ideally, the processor used by this service must have intensive processing capacities such as the following models:

  • Intel Xeon Skylake

  • Intel Xeon Broadwell

Scenario

1 to 2 simultaneous requests (container memory)

Multiple simultaneous requests (container memory)

Scenario

1 to 2 simultaneous requests (container memory)

Multiple simultaneous requests (container memory)

Common use case of ~20MB of payload

(e.q. list of 100 files of 200KB each)

  • Minimum:

    • 512MB

  • Recommended:

    • 768MB

  • Minimum:

    • 1GB

  • Recommended:

    • 2GB

Extreme use case of ~500MB of payload

(e.q. list of 2500 files of 200KB each)

  • Minimum:

    • 2GB

  • Recommended:

    • 4GB

  • Minimum:

    • 4GB

  • Recommended:

    • 8GB

Based on internal stress tests, there are significant improvements in the metrics related to signature time when a request aggregates multiple documents. It means that it is significantly worse to create 50 requests with just one document each than to create a single request with 50 documents.

This aspect must be considered in order to optimize the performance and the load of the systems involved.

 

Software Requirements

Please refer to Sign'Stash Proxy Service Execution | Execution Requirements

 

Configuration File

A new configuration file named 'client-services-config.json' must be created inside the [PATH_TO_WORK_FOLDER] according to the following structure:

  • [CLIENT_SERVICE_ID]: States the client service Id used to authenticate against the REST API (e.g. PRT.505767457-PRT.123654123-84dd8c).

  • [CLIENT_SERVICE_SECRET]: States the client service secret used to authenticate against the REST API (e.g. my_secret)

{ "[CLIENT_SERVICE_ID1]": { "secret": "[CLIENT_SERVICE_SECRET1]" }, "[CLIENT_SERVICE_ID2]": { "secret": "[CLIENT_SERVICE_SECRET2]" } ... }

 

Running Docker image

Start the Sign’Stash Proxy service by defining the docker command according to the following format:

docker run -d --mount source=vol[UID],target=/tmp --mount type=bind,source=[PATH_TO_WORK_FOLDER],target=/home -p [PORT]:8080 --memory=[MEMORY] [IMAGE_ID] --server.host.port=[HOST]:[PORT] --einvoice-integration-client.service.domain=[SAAS_DOMAIN] --einvoice-integration-client.rest.provider.proxy.hostname=[PROXY_HOSTNAME] --einvoice-integration-client.rest.provider.proxy.port=[PROXY_PORT]

 

Execution example using staging environment:

docker run -d --mount source=vol1,target=/tmp --mount type=bind,source=C:/temp,target=/home -p 8081:8080 --memory=4g teammust/einvoice:integration-client-ws-eeeb1c66db7fc864d4203c3e857b095f29a7a2e6-87 --server.host.port=127.0.0.1:8081 --einvoice-integration-client.service.domain=https://staging.must.digital/

 

API Methods

The methods supporting this service mode are:

 

Signature integration scheme

Typical interactions between systems in this mode are presented in the following sequence diagram:

 

Each document(s) signature request will produce a new operation in the system that could later be consulted on the backoffice.

 

Signature response handling

General response handling overview:

Â