Connecting your service
Sign’Stash solution 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” 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).
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. |
5 | 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 API is available in:
Business API
https://staging.must.digital/signstash/einvoice-integration-ws/swagger-ui/index.html
Username: einvoice-user
Password: einvoice-password
Service Endpoints
The following REST service endpoints are available for your integration:
Staging (for sandboxing and testing purposes) | Business API: https://staging.must.digital/signstash/einvoice-integration-ws Authentication API: https://staging.must.digital/oauth2/authorization-server |
Production | Business API: https://msignstash.multicert.com/signstash/einvoice-integration-ws Authentication API: https://msignstash.multicert.com/oauth2/authorization-server |
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 or accessed via API.
Please make sure that an unique id (external reference) is issued for each request and for each document in the request. This is useful for error recovery scenarios as described later in this section.
Step | Alternative Scenario | Behaviour |
|---|---|---|
3 | 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. |
4 | 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. |
8 | E-mail send failure | If Sign’Stash fails to send end client notification mail, will handle its retry at a later time. Retry sending will end after reaching a defined threshold (by default 3 retries). |
Response handling overview:
Retrieve Operation Detail
This section describes the necessary actions if a client service wishes to re-obtain the signed documents that were produced as a result of a document signatures request.
Step | Alternative Scenario | Behaviour |
|---|---|---|
1 | Operation does not exist or does not have access to | If operation Id is not present in the system, or does not belong to issuer company client service, an error will be returned stating that fact. |
Resend E-mail Notification
This section describes the necessary actions if a client service wishes to (re)send the notification e-mail of available documents regarding an operation to a given set of person receivers.
Step | Alternative Scenario | Behaviour |
|---|---|---|
1 | Operation does not exist or does not have access to | If operation Id is not present in the system, or does not belong to issuer company client service, an error will be returned stating that fact. |
Document Signing Error Recovery
For each document sign request, the client service needs to provide a unique external reference that will be used for error recovery.
Since that in a real world environment errors can occur that leaves the client service without being sure that the signature was properly executed (e.g. communication timeouts), this external reference issued by the client service can be used to check the request status and decide if a new signature needs to be requested or the previous one can be recovered.
The following diagram illustrates such case.
Step | Alternative Scenario | Behaviour |
|---|---|---|
6 | Error signing documents | Client service should execute new signature request. |
Advanced Scenarios
This section describes some specific use cases where using advanced attributes for the signature can be useful.
UBL Signing
To meet the requirements presented by the UBL standard, a new structure was defined at the signature request allowing to specify a set of additional attributes to customize the XAdES signature.
For this, a JSON structure located at the SignRequest.documents[].signatureInfo.advancedSignatureInfo.advancedSignatureInfo has been added to the REST API, that currently supporting the following properties:
canonicalTransform: States the custom canonicalization transform (XAdES Enveloped) to use.
signatureLocation: States the parent XML element where the signature will be contained (XAdES Enveloped). Please note that this parent XML element should already be present in the document, since Sign’Stash service will include the information under this element.
signatureTransform: States the custom digest calculation transform (XAdES Enveloped) to use.
UBL Signing Request Example
{
"description": "Some context.",
"documents": [
{
"documentRequest": {
"base64Content": "PD94bWwgdmVyc2lvbj0iMS4wIi...m90ZT4",
"contentType": "text/xml",
"externalReference": "Ext_Ref",
"name": "document_example.xml"
},
"signatureInfo": {
"advancedSignatureInfo": { <--
"canonicalTransform": "EXCLUSIVE_WITH_COMMENTS", <--
"signatureLocation": "SignatureInformation", <--
"signatureTransform": "ENVELOPED" <--
},
"applyTimestamp": false,
"signatureType": "XAdES"
}
}
],
"externalReference": "Ext_Ref",
"returnSignedContent": true
}