Synchronous Mode (API)

Owned by Fernando Vicente
Last updated: Oct 17, 2022 by Antonio Filho
3 min read

REST API Synchronous Mode

In this format, the response to a signature request is the detail of the signature operation which, when successful, means returning the signed documents.

This mode is tipically used in situations where API integration is preferred, the number of files/request signing is low (<100) considering an average size of 200KB and with a synchronous response of the signed documents.

 

Architecture

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

 

 

Hardware Requirements

This section describes the minimum and recommended hardware requirements for running the service based on a common and an extreme scenario .

A minimum of disk space (container volume) equal to 5x the total payload size must be guaranteed but it is recommended 10x.

This value is applicable to a single request and must be extrapolated according to the total number of requests being processed.

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)

Several simultaneous requests (container memory)

Scenario

1 to 2 simultaneous requests (container memory)

Several simultaneous requests (container memory)

Common use case of ~10MB of payload

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

  • Minimum:

    • 512MB

  • Recommended:

    • 768MB

  • Minimum:

    • 1GB

  • Recommended:

    • 2GB

Extreme use case of ~500MB of payload

(e.q. list of 25 files of 20MB 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

Running Docker image

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

docker run -d --mount source=vol[UID],target=/tmp -p [PORT]:8080 --memory=[MEMORY] [IMAGE_ID] --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]

Please refer to Docker run documentation for additional information

 

Execution example using staging environment:

docker run -d --mount source=vol1,target=/tmp -p 8081:8080 --memory=4g [IMAGE_ID] --einvoice-integration-client.service.domain=https://staging.must.digital/

 

Please to get information about your IMAGE_ID you can use the command:

docker image ls

API Methods

The methods supporting this mode are:

Full API REST Swagger documentation is exposed by your locally deployed docker service in:

http://[HOST]:[PORT]/signstash/einvoice-integration-client-ws/swagger-ui/index.html

(For proxy versions older than v1.6+b88 the URL is http://[HOST]:[PORT]/signstash/einvoice-integration-client-ws/swagger-ui.html)

 

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: