API: Methods related to unattended signature with certificate

Last update: November 13, 2024

The unattended signature process in Viafirma Fortress will consist of the processes of:

• Client authentication
• Signature request
• Signature execution
• Getting the signed document/s

In the following sections we will describe the methods available in Viafirma Fortress, associated with signature operations:

Note: To access these methods it is necessary to have an access token(access_token) obtained through an authentication and authorization request with ascope of type client and a grant_typeof type client_credentials, [for which you must follow the steps indicated in this section of the documentation] (../../auth/README.md).

Unattended signature request

Use of the service

Method:POST
URL: {viafirma_fortress_ url}/api/v1/signature

Where:

• viafirma_fortress_url: Base URL of the Viafirma Fortress implementation, for example https://sandbox.viafirma.com/fortress or https://fortress.viafirma.com/fortress

Additionally, the access token (access_token) must be included in the HTTP header of thePOSTrequest as follows:

Authorization: Bearer {access_token}

Example:

Method:POST
URL:{viafirma_fortress_ url}/api/v1/signature
Request header :Authorization : Bearer 0b79bab50daca910b000d4f1a2b675d604257e42

Service parameters

This service receives through parameters the configuration of the signature used for each document to be signed, which indicates, among other things, the type of signature to be made, the document to be signed...

The parameters that are received (inapplication/jsonformat ) have the following form:

{
  "certificateCode":"b8a25e04ab864583bb5ea8d02883e832",
  "signatureConfigurations": [
  {
    "ref":"#1",
    "document": {
      "bytesB64":"JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQ...",
      "name":"contract.pdf"
    },
    "signatureType":"PADES_B",
    "signatureAlgorithm":"RSA_SHA256",
    "packaging":"ENVELOPED",
    "padesConfiguration": {
      "stamper": {
        "csvPath":"http://localhost:7080/fortress/v#",
        "logoB64":"iVBORw0KGgoAAAANSUhEUgAAAWYAAABsCAYAAABZyhj...",
        "page": 1,
        "type":"QR_BARCODE128",
        "xAxis": 80,
        "yAxis": 700
      }
    }
  }
]
}

Note: Details of thepadesConfiguration,xadesConfiguration,tsaandpolicyparameters are shown below.

Where:

PAdES configuration

This setting only applies for signatures whosesignatureTypeis of type PAdES ( PAdES B, PAdES T, PAdES LT, PAdES LTA).

"padesConfiguration": {
"stamper": { }
}

The stamper object is optional, and serves to define a visual stamp associated with the PAdES signature .

{
  "stamper": {
    "csvPath":"https://fortress.viafirma.com/fortress/v#",
    "imageB64":"JVBERi0xLjMKJcTl8uXlRU9GC...",
    "logoB64":"JVBERi0xLjMKJcTl8uXlRU9GC...",
    "page": 1,
    "rotation":"ROTATE_90",
    "textLine1":"Sample line 1",
    "textLine2":"Sample line 2",
    "textLine3":"Sample line 3",
    "type":"QR_BARCODE128",
    "xAxis": 100,
    "yAxis": 100,
    "timeZoneId":"America/Santo_Domingo"
  }
}

Depending on thetypechosen, the stamp will have pre-established dimensions (in pixels):

• PDF417: 300x130
• QR_BARCODE128: 600x100
• QR: 450x50
• BARCODE128: 550x70
• IMAGE: Maintains the dimensions of the image specified inimageB64
• TEXT: 400x50

timeZoneId value is NOT reported in the API call, we will apply the following criteria:

• In case of unattended signature, if the Client System belongs to a group that has it informed, we apply the one of the first group that has it informed, if not we apply the one configured by default in the system.

XAdES Configuration

This setting only applies for signatures whosesignatureTypeis of type XAdES ( XAdES B, XAdES T, XAdES LT, XAdES LTA)

{
"signedInfoCanonicalizationMethod":"http://www.w3.org/TR/2001/REC-xml-c14n-20010315",
"signedPropertiesCanonicalizationMethod":"http://www.w3.org/TR/2001/REC-xml-c14n-20010315",
"xPathLocationString":"//book[@id='bk101-1']",
"claimedSignerRoles": [
   "role1",
   "role2"
],
"transformAlgorithms": [
"http://www.w3.org/TR/2001/REC-xml-c14n-20010315"
  ],
"dssReferenceUri":"http://dsa-reference.example.com/"
}

Where:

TSA Settings

For signature types that include time stamping, the TSA settings must be reported.

{
  "url":"http://tsa.example.com/",
  "user":"tsa_user",
  "password":"tsa_pass",
  "type":"USER",
  "certificateCode":"tsa_certificate_code"
}

Policy settings

So that the signature has a policy and can be considered EPES type, we can define its values with this configuration.

{
  "id":"102039485-10283757-102837575",
  "description":"Sample policies",
  "digestAlgorithm":"SHA256",
  "digestValueB64":"JVBERi0xLjMKJcTl8uXlRU9GC",
  "url" : "https://sample/lorem_ipsum_dolor_sit_amet.pdf",
  "contentHintsDescription":"Lorem ipsum dolor sit amet",
  "contentHintsType":"Lorem ipsum dolor sit amet"
}

Service response

The response from this service will be given (inapplication/jsonformat ) as follows:

{
  "authCode":"1aeb979ddcf247e9ad46ee73e19a326d",
  "exeCode":"f116305e7f7c44f3a29385028c5374ba"
}

Where:

Service errors

The errors returned by the service (returned inapplication/jsonformat ) look like this:

{
  "error":"error_code",
  "error_description":"error_description"
}

Where:

Possible mistakes:

Signature execution

With this method we will sign the documents associated with the signature preparation operation.

Use of the service

Method:POST URL:{viafirma_fortress_ url}/api/v1/signature/{executionCode}/execute

Additionally, the access token (access_token) must be included in the HTTP header of thePOSTrequest as follows:

Authorization: Bearer {access_token}

Where:

• viafirma_fortress_url: Base URL of the Viafirma Fortress implementation, for example https://sandbox.viafirma.com/fortress or https://fortress.viafirma.com/fortress
• executionCode: Execution code returned by the signature method

Example:

Method: POST
URL: {viafirma_fortress_ url}/api/v1/signature/f116305e7f7c44f3a29385028c5374ba/execute
Request header: Authorization : Bearer 0b79bab50daca910b000d4f1a2b675d604257e42

Service parameters

This service receives by parameters the execution code executionCode , resulting from the signature preparation procedure, with this code we will obtain the information associated with each signing operation.

It must be provided ( inapplication/jsonformat ) empty:

{
}

Service Response

The response from this service will be given (inapplication/jsonformat ) as follows:

[
  {
    "bytesB64":"a910b000d4f1a2b...",
    "signatureCode":"e2470412-33cc-467a-b357-880fe621920f",
    "mimeType":"application/pdf",
    "ref":"#1"
  },
...
]

Where:

Service errors

The errors returned by the service (returned inapplication/jsonformat ) look like this:

{
  "error":"error_code",
  "error_description":"error_description"
}

Where:

Possible mistakes:

Download signed document

With this method we can download a signed document using a signature identifier.

Use of the service

Method:GET URL:{viafirma_fortress_ url}/api/v1/signature/download/{signature_code}

Additionally, the access token (access_token) must be included in the HTTP header of theGETrequest as follows:

Authorization: Bearer {access_token}

Where:

• viafirma_fortress_url: Base URL of the Viafirma Fortress implementation, for example https://sandbox.viafirma.com/fortress or https://fortress.viafirma.com/fortress
• signature_code: Code of the signature from which you want to download the document

Example:

Method: GET URL: {viafirma_fortress_ url}/api/v1/signature/download/C0XJ-XOAK-OF1O-TYJ7-S164-3197-3571-05

Service Response

The response from this service will be given (inapplication/octet-streamformat )

Service errors

The errors returned by the service (returned inapplication/jsonformat ) look like this:

{
  "error":"error_code",
  "error_description":"error_description"
}

Where:

Possible mistakes: