Sign’Stash Proxy Client provides a REST API to enable your client services a full integration.
Please make sure that you have executed the steps in the “Getting Started (On-Premise)” section in order to have a valid client service credential to consume Sign’Stash services.
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).
Both the clientID and the client secret refer to the configurations of the Sign’Stash client service that you wish to connect to. Thus, clientID is the client service alias and client secret is the defined credentials to it.
Step | Alternative Scenario | Behaviour |
|---|---|---|
1 | OAuth authentication error | Basic credentials presented are invalid. New Basic Authentication must be requested by the client with the proper credentials. Please make sure that clientID is the service alias known in Sign’Stash, and client secret is the password that you have defined in Sign’Stash backoffice. |
6 | Sign’Stash authentication error | OAuth token is invalid. New OAuth token must be retrieved from OAuth server. |
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:
Authentication API (Swagger):
Service Endpoints
The following REST service endpoints are available for your integration:
Staging (for sandboxing and testing purposes) | Business API: https://your_proxy_client_service_location/signstash/einvoice-integration-client-ws Authentication API: https://staging.must.digital/oauth2/authorization-server |
Production | Business API: https://your_proxy_client_service_location/signstash/einvoice-integration-client-ws Authentication API: https://msignstash.multicert.com/oauth2/authorization-server |
Requirements
Hardware
This section describes the minimum and recommended hardware requirements for running the service based on a common and an extreme scenario.
This information is applied to an unique instance of the service and should be extrapolated according to the specific environment and architecture.
Scenario | 1 to 2 simultaneous requests | Multiple simultaneous requests |
|---|---|---|
Common use case of ~10MB of payload (e.q. list of 50 files of 200KB each) |
|
|
Extreme use case of ~1GB of payload (e.q. list of 50 files of 20MB each) |
|
|
Ideally, the processor used by this service must have intensive processing capacities such as the following models:
Intel Xeon Skylake
Intel Xeon Broadwell
A minimum of free disk space 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 number of requests processed in parallel.
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+.
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 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.
Integration Flows
This section describes the main flows that your implementation needs to guarantee for a successful integration.
While using the Sign’Stash Proxy Client component, it is only possible to execute digital signatures on a set of supplied documents, unlike the Integration Service, where it is also possible to consult documents details.
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.
Only the operation details can be consulted since the document is not stored either preserved in the system.
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. Issuer operator should access Sign’Stash backoffice and configure a proper certificate for the client service. |