The Sign’Stash Proxy allows 3 integration modes, some of which requiring specific configuration parameters.
The different modes are presented in order of capabilities which are cumulative, meaning that when using a particular mode, e.g. Hot-Folder Async Mode, it is still possible to use the previous ones, e.g. API Sync and Async Modes.
All specific configuration parameters will be presented in a dedicated section.
General Architecture
For global reference 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.
Common Parameters
Regardless of the format chosen, the parameters described below are mandatory and transversal to all modes, and must be associated with the docker run command according to your requirements.
Parameter | Description |
|---|---|
UID | Id suffix of the volume to attach to the container (e.g. _ssproxy). |
PORT | Exposed port for public access (e.g. 8085). |
MEMORY | Maximum memory that the docker can use (e.g. 4g). |
IMAGE_ID | Id/Unique name of the docker image to execute (e.g. 07da08a1e977). |
SAAS_DOMAIN | Domain of the Sign'Stash SaaS enviroment to invoke (e.g. https://staging.must.digital/). |
PROXY_HOSTNAME (optional) | Customer infrastructure proxy hostname. |
PROXY_PORT (optional) | Customer infrastructure proxy port. |
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.
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.
Docker Command
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]
API Methods
The methods supporting this mode are:
Sequence diagram
Typical interactions between systems in this mode are presented in the following sequence diagram:
Response handling
General response handling overview:
REST API Asynchronous Mode
The asynchronous mode adds to the previous one 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 |
|---|---|
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.
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]"
}
...
}
Docker Command
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]
API Methods
The methods supporting this service mode are:
Sequence diagram
Typical interactions between systems in this mode are presented in the following sequence diagram:
Response handling
General response handling overview:
HOT-FOLDER Asynchronous Mode
Hot-folder mode adds to Async Mode the ability to process files directly from/to a set of configured input/output folders.
This mode requires, in addition to the configuration file created for the asynchronous mode, that 3 folders be added to the [PATH_TO_WORK_FOLDER] directory, in particular:
Input folder: It is the input interface with the client service and stores the documents to be signed.
Backup folder: Keeps a copy of each file processed. In case of success, only the original file is moved, otherwise, an text file with details of the error is attached.
Output folder: It is the output interface with the client service and stores the signed documents or a text file, named as the original file, with details about the error that occurred.
To enable this mode it is necessary to include the following parameter in addition to those of the ASYNC mode and then set it to TRUE.
Parameter | Description |
|---|---|
HT_ENABLED | Turn on/off the hot folder mode (ex: TRUE|FALSE). |
Architecture
The Sign’Stash Proxy components are in gray background, the Sign’Stash SaaS is in green background, and the blue background pertains to the client service components.
Configuration File
This mode requires to update the configuration file using the following parameters related with the additional folders created.
[INPUT_FOLDER_NAME]: States the relative path of the folder from which the files to be signed will be obtained (e.g. /inputFolder)
[BACKUP_FOLDER_NAME]: States the relative path of the folder to which the processed files will be secured (e.g. /backupFolder)
[OUTPUT_FOLDER_NAME]: States the relative path of the folder to which the signed files (or errors) will be saved (e.g. /outputFolder)
{
"[CLIENT_SERVICE_ID]": {
"secret": "[CLIENT_SERVICE_SECRET]",
"inputFolder": "[INPUT_FOLDER_NAME]",
"backupFolder": "[BACKUP_FOLDER_NAME]",
"outputFolder": "[OUTPUT_FOLDER_NAME]"
}
...
}
Optionally, it is also possible to expand this configuration with information to enable visible signatures attributes for PDF documents, using:
[LOCATION_TYPE]: States which type of location strategy will be used to set the visible signature. Allowed values: SIGN_FIELD, COORDINATE, PLACEHOLDER.
[LOCATION_VALUE]: States the location value for the appropriate locationType defined (e.g. page=1,x=100,y=200).
[VISIBLE_TEXT_TEMPLATE_TYPE]: States the type of signature template to be used. Allowed values: ONE_OFF, SERVICE_CUSTOMIZATION.
[ONE_OFF_TEMPLATE_TEXT]: If templateType=ONE_OFF, then set the text value format to display (e.g. Digitally Signed by $certificate.getCommonName()).
{
"[CLIENT_SERVICE_ID]": {
"secret": "[CLIENT_SERVICE_SECRET]",
"inputFolder": "[INPUT_FOLDER_NAME]",
"backupFolder": "[BACKUP_FOLDER_NAME]",
"outputFolder": "[OUTPUT_FOLDER_NAME]",
"padesVisibleSignature": {
"locationType": "[LOCATION_TYPE]",
"locationValue": "[LOCATION_VALUE]",
"templateType": "[VISIBLE_TEXT_TEMPLATE_TYPE]",
"oneOffTemplate": "[ONE_OFF_TEMPLATE_TEXT]"
}
}
...
}
It is possible to find additional information about these parameters through the Swagger documentation exposed by the service’s REST API.
Docker Command
Start the 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] --hot.folder.enabled=[HT_ENABLED]
Sequence diagram
Typical interactions between systems in this mode are presented in the following sequence diagram:
Response handling
General response handling overview:
Swagger Documentation
In any of the described modes, after starting the service correctly, it should be possible to access the swagger documentation through the URL:
http://[HOST]:[PORT]/signstash/einvoice-integration-client-ws/swagger-ui.html