1 Authentication
2 API Definition and Examples
- 2.1 Service Endpoints
3 Integration Flows
- 3.1 Document Signing
- 3.2 Retrieve Operation Detail
- 3.3 Resend E-mail Notification
- 3.4 Document Signing Error Recovery
4 Advanced Scenarios
- 4.1 UBL Signing
- 4.2 UBL Signing Request Example

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

Authentication API
- https://staging.must.digital/oauth2/authorization-server/swagger-ui/index.html

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.

Please be advised that the Sign’Stash service is limited to maximum payload of 5MB per request. If you have document requirements that are limited by this restriction, please consult our Sign'Stash Proxy Service Execution alternative.

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.

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
}

SignStash

Connecting your service