Signing API

An Access Token is required to authorize all API requests, as explained at the following link:

get Access Token

DIGITAL SIGNATURE REQUEST

REST service specs:

Method: POST
URL: {viafirma_fortress_url}/api/v1/signature

Security:

Authorization: Bearer {access_token}

Where:

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

Sample Request

Method: POST
URL: {viafirma_fortress_url}/api/v1/signature

Security Header: Authorization: Bearer 0b79bab50daca910b000d4f1a2b675d604257e42

Request Params

The request body contains information such as signature format, document to be signed, etc.

application/json format is used:

{
  "signatureConfigurations": [
    {
      "ref": "#1",
      "document": {
        "bytesB64": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQ...",
        "name": "contract.pdf"
      },
      "signatureType": "PADES_LTA",
      "signatureAlgorithm": "RSA_SHA256",
      "packaging": "ENVELOPED",
      "reason": " test PAdES signature ",
      "padesConfiguration": {
        "stamper": {
          "csvPath": "http://<someURL>/v#",
          "logoB64": "iVBORw0KGgoAAAANSUhEUgAAAWYAAABsCAYAAABZyhj...",
          "page": 1,
          "type": "QR_BARCODE128",
          "xAxis": 80,
          "yAxis": 700
        }
      }
    }
  ]
}

Note: params for padesConfiguration, xadesConfiguration, references,cadesConfiguration, tsa and policy are described later.

Where:

Si se informa una URL y la firma se realiza de forma asíncrona, al finalizar la firma Fortress realiza una petición POST a dicha URL con el estado final de ejecución. |

Configuración de los filtros de certificados

Esta configuración hace que a la hora de firmar, el usuario solo pueda firmar con los certificados que cumplan todos los requisitos.

{
  "certificateFilter": {
    "issuer.cn": [
      "AC FNMT Usuarios"
    ],
    "subject.cn": [
      "ZAMORANO DE EJEMPLO JOSE LUIS - 71121212M"
    ],
    "subject.serialnumber": [
        "99999999R",
        "71121212M"
    ],
    "oid": [
      "2.5.29.14",
      "2.5.29.15"
    ]
  }
}

Podemos filtrar de varias formas.

PAdES Configuration

Params only applicable to signatureType PAdES (PAdES B, PAdES T, PAdES LT, PAdES LTA).

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

The stamper object is optional, and it defines a visual stamp associated with the signature PAdES.

{
  "stamper": {
    "csvPath": "https://sandbox.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
  }
}

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

• If the request belongs to a user, we will use the user's timezone. If the user does not have one, but belongs to a group that does, we will use the timezone of the first group that does. Otherwise, we will apply the default configured in the system.

For the IMAGE stamp type, the stamp background image must be specified in Base64 format using the imageB64 attribute or by specifying a URL in the imageUrl attribute.

XAdES Configuration

Params only applicable to signatureType 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/",
  "manifestSignature": false
}

Where:

References

This setting only applies to signatures whose signatureType is of type XADES (XAdES B, XAdES T, XAdES LT, XAdES LTA) and has been indicated to be a signature of type manifest xadesConfiguration.manifestSignature.

{
    "uri":"src/test/examples/manifest/a_documento.pdf",
    "digestValue":"GQBXsIg1NFp6IYYeAFuH6l7sjLv3FbvnpvvTX6f8ZEEr1TwgOuXFuEl9IVn1hseZJG+S1a6LDhIJcKS1sCfJ/w=="
}

Where:

CAdES Configuration

This setting only applies to signatures whose signatureType is of type CAdES (CAdES B, CAdES T, CAdES LT, CAdES LTA).

{
    "hashSignature" : true,
    "hashDigestAlgorithm" : "SHA256"
}

Where:

TSA Configuration

TSA configuration is mandatory if a signature format that requires timestamp is used:

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

POLICIES Configuration

Only applicable to XAdES EPES format; a Signature Policy can be defined:

{
  "id": "102039485-10283757-102837575",
  "description": "Sample policy",
  "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"
}

<<<<<<< HEAD | Param | Type | Desc | |-----------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------| | id | string | Policy id | | description | string | Policy description | | digestAlgorithm | string | Cipher Algorithm:
- SHA1
- SHA224
- SHA256
- SHA384
- SHA512
- RIPEMD160
- MD2
- MD5 | | digestValueB64 | string | Policy Digest value (Base64) | | contentHintsDescription | string | Help Description |

| contentHintsType | string | Help content type |

26367b52051e0e30d23d28b90480e0e025b5537d

Response

Response in application/json format:

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

Where:

API Errors

Errors are returned using application/json format:

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

Where:

Errors:

USER AUTHENTICATION AND CERTIFICATE SELECTION

Please review the following User Authentication and Signature Authorization section to find more details.

SIGNATURE EXECUTION

REST service specs:

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

Where:

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

Sample Request

Method: POST
URL: {viafirma_fortress_url}/api/v1/signature/f116305e7f7c44f3a29385028c5374ba/execute

Params

The request body must be an empty JSON:

{
}

Sample Response

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

Where:

API Errors

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

Where:

Errors:

DOWNLOAD SIGNED DOCUMENT

Download signed document.

Service specs:

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

Where:

• viafirma_fortress_url: URL of the Fortress implementation, for example https://sandbox.viafirma.com/fortress or https://fortress.viafirma.com/fortress
• signature_code: signature code returned by fortress in the signature execution service

Sample Request

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

Response

Document in application/octet-stream format.

API Errors

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

Where:

Errors: