The Integration Client component provides two manners to enable your client services a full integration:

As a dependency in a Java client application;
Or installed as a micro web service running in the client environment and exposing a REST API to receive the client services requests.

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

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.

The fields non-related with the digital signature of the documents hashes - such as delivery, storage, or preservation fields - are not used and therefore are not filled by the method.

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.

Integration Flows

This section describes the main flows that your implementation needs to guarantee for a successful integration.

While using the Integration 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.

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.

TODO > colocar novo diagrama (imagem) aqui

TODO > prrencher tabela abaixo com fluxos possiveis do novo diagrama

Step	Alternative Scenario	Behaviour

Connecting your service (On-Premise)