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
  }
}

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: