The Integration Sign’Stash Proxy Client component provides two manners a REST API to enable your client services a full integration:

.

Authentication

To use the Integration Client, you will also need to authenticate your client service using the OAuth2 scheme, as explained in the “Authentication” section of the Connecting your service page.

Component Integrated In Client Application

The Integration Client can be directly integrated in a Java client product or application through a dependency or library distributed via Maven, named einvoice-integration-client.

To add this dependency to your client application, you need to insert the following code snippet into the pom.xml file of the application project.

<dependency>
    <groupId>com.must.einvoice</groupId>
    <artifactId>einvoice-integration-client</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>

Initialization

To use the component functionalities it is first required to initialize a signature service named HashSignatureService. The initialization operation will generate an instance of the service ready to use.

HashSignatureService hashSignatureService = new SignatureService().initialize();

Documents Signing

To request the application of digital signatures on a set of documents. you need to use the method signDocumentHash from HashSignatureService. The following code snippet presents its method signature.

public interface HashSignatureService{
    SignOperation signDocumentHash(BaseSignRequest<BinaryDocument> signRequest, String token) 
                throws UnexpectedException, ExternalReferenceAlreadyExistsException, IntegrationRequestException
                InvalidVisibleSignatureConfigurationException, InvalidSignatureContentConfigurationException;
}

1. Inputs

Field

Presence

Type

Description

signRequest

REQUIRED

BaseSignRequest<BinaryDocument>

Details about the signature request.

token

REQUIRED

String

Access token required to invoke Sign’Stash API (einvoice-integration-ws). This token is obtained from the OAuth2 server as explained in the previous section.

BaseSignRequest<BinaryDocument> Specification Class:

Field

Presence

Type

Description

description

REQUIRED

String

Contextualization of the request. This information will be presented to signers, if applicable.

documents

REQUIRED

Array of SignDocument<BinaryDocument>

Details about the document list to sign.

externalReference

REQUIRED

String

Unique external reference id set by the client service. A good approach is to have the service client id prefixed to the external reference to avoid collisions with other external references already registered in the system.

SignDocument<BinaryDocument> Specification Class:

Field

Presence

Type

Description

documentRequest

REQUIRED

BinaryDocument

Details about the a document with its content in binary format.

signatureInfo

REQUIRED

SignatureInfo

Information attributes for the signature to be created on the documentRequest.

BinaryDocument Specification Class:

Field

Presence

Type

Description

binaryContent

REQUIRED

Array of byte

Document content in binary format.

contentType

REQUIRED

String

Content type of the document.

externalReference

REQUIRED

String

Unique external reference id set by the client service. A good approach is to have the service client id prefixed to the external reference to avoid collisions with other external references already registered in the system.

name

REQUIRED

String

Name of the document.

SignatureInfo Specification Class:

Field

Presence

Type

Description

applyTimestamp

OPTIONAL

boolean

Will apply timestamp to signature. Will use the default system timestamp server.

location

OPTIONAL

String

Signature location (free text) to be set on document metadata. Support is restricted to PAdES based signature types.

reason

OPTIONAL

String

Signature reason (free text) to be set on document metadata. Support is restricted to PAdES based signature types.

signatureType

REQUIRED

String

Signature profile to be applied. Available profiles:

• PAdES: Usually applied to PDF files.

• XAdES: Usually applied to XML text files.

• CAdES: Usually applied to binary files.

visibleSignatureInfo

OPTIONAL

VisibleSignatureInfo

Visible information to be applied upon signature creation. Support is restricted to PAdES based signature types.

VisibleSignatureInfo Specification Class:

Field

Presence

Type

Description

area

OPTIONAL

String

Area of the signature canvas. If not set will default to system settings.

Example: width=200,height=400

font

OPTIONAL

String

Font style of the signature text. If not set will default to system settings.

Example: color=#ea9dd3,size=11

locationType

REQUIRED

String

States which type of location strategy will be used to pinpoint the location where the lower left point of the signature canvas will begin to be drawn. Available strategies:

• SIGN_FIELD: Use a signature field present in the document. The signature field name should be set in the locationValue request attribute.

• COORDINATE: Use a coordinate to find the correct document position.

  • Supported format: page=<page_number>,x=<lower_left_x>,y=<lower_left_y>

• PLACEHOLDER: Use a placeholder (unique word). System will scan the document for the given placeholder and stop in the first occurrence.

  • The lower left part of the word will be used as a coordinate to start the drawing of the signature canvas from top/left orientation.

  • If the placeholder is not found, an error will be thrown and the signature will not be applied.

  • The placeholder value should be set in the locationValue request attribute.

locationValue

REQUIRED

String

Location value for the appropriate locationType defined.

Example: page=1,x=100,y=200

oneOffTemplate

OPTIONAL

String

If templateType=ONE_OFF, then a velocity template value format must be set here.

Example: Digitally Signed by $certificate.getCommonName().

templateType

OPTIONAL

String

States the type of signature creation template to be used. If not set, will first try to use service issuer template. As a final fallback will use system default template: Available types of templates:

• ONE_OFF: Visible signature template in a velocity format will be provided in the oneOffTemplate request attribute.

• SERVICE_CUSTOMIZATION: Uses the issuer service default visible signature template or if not found falls back on the system template.

Example: ONE_OFF

2. Outputs

Field

Presence

Type

Description

signOperation

REQUIRED

SignOperation

An object containing the supplied documents digitally signed and the informations about the signature operation.

SignOperation Specification Class:

Field

Presence

Type

Description

creationDate

OPTIONAL

String

Operation registry date.

deliveryInfo

OPTIONAL

DeliveryInfo

Information attributes for the delivery of the documentRequest to a third Party.

documentList

OPTIONAL

Array of DocumentResponse

List of documents of the operation and aggregated in the defined folder.

folder

OPTIONAL

Folder

Folder that holds all the documents handled on a given request.

id

REQUIRED

integer

Operation unique id.

issuerClientServiceAlias

OPTIONAL

String

Issuer client service that created the operation.

issuerCompany

OPTIONAL

Company

Issuer Company id and basic info.

status

OPTIONAL

String

Operation status:

• PENDING_EXECUTION: Operation registered and awaiting execution.

• EXECUTED: Operation executed successfully.

• EXECUTION_ERROR: Error occurred when trying to execute operation. Will try again.

• EXECUTION_FAILED: Exceeded all retries for execution errors, system has given up and will not try again.

type

OPTIONAL

String

Operation type:

• SIGN: Execute signature operation.

• EXTEND_PRESERVATION: Extend document preservation.

DocumentResponse Specification Class:

Field

Presence

Type

Description

additionalContentLength

OPTIONAL

integer

Additional original/pre-signature content length in bytes that exceeded the subscribed service limit.

cipherStatus

OPTIONAL

String

Status of the cipher action (if requested).

contentLength

OPTIONAL

integer

Content length in bytes of the original/pre-signature content.

contentType

REQUIRED

String

Content type of the document.

Example: application/pdf

externalReference

REQUIRED

String

Unique external reference id set by the client service. A good approach is to have the service client id prefixed to the external reference to avoid collisions with other external references already registered in the system.

internalId

OPTIONAL

integer

Internal Id of the document in the Sign’Stash system.

name

REQUIRED

String

Name of the document.

receptionDate

OPTIONAL

String

Instant when the document was received in the system.

signError

OPTIONAL

String

Error code of the signature error if it occurred.

signStatus

OPTIONAL

String

Status of the signature action:

• RECEIVED: Document has been received but no further action was taken.

• ERROR_SIGNING: An error has occured when signing was attempted.

• SIGNED: A digital signature was successfully applied to the document.

signedContent

OPTIONAL

String

Signed content, encoded in base 64 format, of the original document.

storageEndDate

OPTIONAL

String

Instant until when the the document will be stored in the system.

storagePeriod

OPTIONAL

String

Period length (in months) to when the document will be stored. Storage date limit is computed with receptionData + storagePeriod.

storageStatus

OPTIONAL

String

Status of the storage action (if requested).

Folder Specification Class:

Field

Presence

Type

Description

description

OPTIONAL

String

Folder description information.

externalReference

OPTIONAL

String

Folder external reference as submitted by the client service.

folderContent

OPTIONAL

String

Folder content type:

• DOCUMENT: The folder represents a list of documents.

• HASH: The folder represents a list of hashes.

folderId

OPTIONAL

String

Folder unique id that holds all the documents handled on a given request.

Company Specification Class:

Field

Presence

Type

Description

additionalInfo

OPTIONAL

String

Additional information on the company.

auditLogsActive

OPTIONAL

boolean

Audit logs activation status of the company.

countryCode

REQUIRED

String

Country code in ISO 3166 Alpha 3 format where the VAT number of the company was issued (full country list available on https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3).

creationDate

OPTIONAL

String

The company registry date.

email

OPTIONAL

String

The company e-mail. Will serve for contact purposes.

i18nCode

REQUIRED

String

i18n locale code of the language configured for the company.

invoiceAddress

OPTIONAL

String

Company address to where the invoice with the service consumptions will be issued.

name

REQUIRED

String

Name of the company.

status

OPTIONAL

String

Status of the company:

• REGISTERED: enrollment request is registered but not yet processed.

• ACTIVE: company is active for usage

• SUSPENDED: company suspended due to own operator management action

• BLOCKED: company blocked due to admin action

• DELETED: company mark for deletion

vatNumber

REQUIRED

String

VAT Number of the company.

3. Most Common Errors

Error case

Exception

The accessToken field does not match the pattern “Bearer [token]”.

IllegalArgumentException

The token provided is invalid or expired.

IntegrationRequestException

The document list to sign contains documents with the same external reference.

ExternalReferenceAlreadyExistsException

The signatureType applied to the contentType is not supported for a given document.

InvalidSignatureContentConfigurationException

The visible signature configuration was applied to a signatureType different from PAdES.

InvalidVisibleSignatureConfigurationException

The client service has no valid digital certificate configured.

IntegrationRequestException

The signature request requires a timestamp application, but there is no timestamp provider set.

IntegrationRequestException

An unhandled error has occurred during the hash generation process.

UnexpectedException

REST Web Service

The Integration Client component can also be wrapped by a micro web service (einvoice-integration-client-ws) that exposes a REST Interface to receive client services requests for executing digital signatures on the supplied documents such as the Integration Service. The client product or application will need to invoke this REST service to execute the document hash signatures, similarly as they did with Integration Service, avoiding to integrate directly the component.

API Definition and Examples

The complete definition of the Integration Client Service API is available through the following JSON file:

You can download the file and import or open in a Swagger client to visualize the API and examples.Sign’Stash Proxy Client 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 Proxy Client API (einvoice-integration-client-ws).

// TODO diagrama autenticação novo aqui

API Definition and Examples

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

• Business API:

  • You can download the following JSON file and import in a Swagger client (such as Swagger.io) to visualize the API and examples.

• Authentication API

  • https://staging.must.digital/oauth2/authorization-server/swagger-ui.html

Service Endpoints

The following REST service endpoints are available for your integration:

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.

TODO > colocar novo diagrama (imagem) aqui

TODO > prrencher tabela abaixo com fluxos possiveis do novo diagrama