Sign’Stash Proxy Client provides a REST API to enable your client services a full integration.

Authentication

Sign’Stash API is protected with an OAuth2 authentication scheme with client_credentials flow.

For more information on this standard, please consult OAuth Client Credentials Flow.

The following diagram depict the typical flow that your client service needs to ensure to retrieve an access token to invoke Sign’Stash API (einvoice-integration-ws) through the Proxy Client API (einvoice-integration-client-ws).

Authentication example request:

curl -v -X POST https://staging.must.digital/oauth2/authorization-server/oauth/token -d "grant_type=client_credentials" -H "Authorization: Basic <base64 of client_id:client_secret>"

Authentication example response:

{"access_token":"eyJhbG....cian84R9Q","token_type":"bearer","expires_in":86399,"scope":"read write","jti":"0e33b...a99a9d"}

API Definition and Examples

The complete definition of the Sign’Stash Proxy Client API is available in:

• Business API (Swagger):

  • Start the Sign’Stash Proxy service, whether in a docker image or fat jar version, and access the following endpoint with the necessary adaptations:

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

• Authentication API (Swagger):

  • https://staging.must.digital/oauth2/authorization-server/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

Service Endpoints

The following REST service endpoints are available for your integration:

Requirements

Hardware

This section describes the minimum and recommended hardware requirements for running the service based on a common and an extreme scenario in three different integration use cases: API synchronous mode, API asynchronous mode, Hot folder mode.

This information is applied to an unique instance of the service and should be extrapolated according to the specific environment and architecture.

API in synchronous mode

Useful 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.

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.

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

API in asynchronous mode

Useful 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.

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.

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

Hot folder mode

Useful in situations where the number of files is large (>2500) and a strategy of input/output folders processing is suitable.

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.

• Throughput: >30files/s

Scenario

Page size of 1000 (container memory)

Input folder with ~10.000 files

• Minimum:

  • 2GB

• Recommended:

  • 4GB

Input folder with ~2.000.000 files

• Minimum:

  • 4GB

• Recommended:

  • 8GB

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

• Intel Xeon Skylake

• Intel Xeon Broadwell

Software

This section describes the software requirements for running the service.

As the official distribution format is through docker images, this service requires the installation of Docker Engine 19+.

Integration Flows

This section describes the main flows that your implementation needs to guarantee for a successful integration.

Document Signing

The following diagram illustrates the actions that a client service needs to execute to request the application of digital signatures on a set of documents.

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

Image Removed

Step

Alternative Scenario

Behaviour

5

Client service not active

Client service or issuer is in not in active status, thus not allowing service usage.

Issuer operator should access Sign’Stash backoffice and check its configurations.

6

Digital certificate not provisioned

If client service has no valid digital certificate set, the Sign’Stash service will not be able to sign the document.

>> Sign'Stash Proxy Service Execution