JAR API Specification

Owned by Ivo Rocha
Last updated: Feb 11, 2021 by Claudio Vicente (Unlicensed)
7 min read

 

This section focuses on the procedure to integrate the Sign’Stash Proxy Client as a JAR or Maven dependency in a Java client application.

If you already integrated with Sign’Stash Proxy Client via REST API, please ignore this section.

Sign’Stash Proxy Client as a Dependency

To integrate the Proxy Client component in your Java client product or application, you must add the following Maven dependency in your project’s pom.xml file:

<dependency> <groupId>com.must.einvoice</groupId> <artifactId>einvoice-integration-client</artifactId> <version>[PROVIDED_VERSION]</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

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

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

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

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

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

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

AdvancedSignatureInfo Specification Class:

Field

Presence

Type

Description

Field

Presence

Type

Description

signatureLocation

OPTIONAL

String

States the parent XML element where the signature will be contained (XAdES Enveloped).

Example: SignatureInformation

signatureTransform

OPTIONAL

String

States the custom digest calculation transform (XAdES Enveloped) to apply. Supported values:

  • ENVELOPED: Chooses the enveloped transformation format.

  • XPATH: Chooses the XPath transformation format.

  • XPATH2_FILTER (default): Chooses the XPath-2-Filter transformation format.

Example: ENVELOPED

canonicalTransform

OPTIONAL

String

States the custom canonicalization transform (XAdES Enveloped) to apply. Supported values:

Example: EXCLUSIVE

2. Outputs

Field

Presence

Type

Description

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

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

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

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

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

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