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:

{
  "certificateFilter": {
    "issuer.cn": [
      "AC FNMT Usuarios"
    ],
    "subject.cn": [
      "ZAMORANO DE EJEMPLO JOSE LUIS - 71121212M"
    ],
    "oid": [
      "2.5.29.14",
      "2.5.29.15"
    ]
  },
  "signatureConfigurations": [
    {
      "ref": "#1",
      "document": {
        "bytesB64": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQ...",
        "name": "contract.pdf"
      },
      "signatureType": "PADES_LTA",
      "signatureAlgorithm": "RSA_SHA256",
      "packaging": "ENVELOPED",
      "reason": " test PAdES signature ",
      "location": "Sevilla",
      "padesConfiguration": {
        "stamper": {
          "csvPath": "http://<someURL>/v#",
          "logoB64": "iVBORw0KGgoAAAANSUhEUgAAAWYAAABsCAYAAABZyhj...",
          "page": 1,
          "type": "QR_BARCODE128",
          "xAxis": 80,
          "yAxis": 700
        }
      },
      "tsa": {
        "type": "URL",
        "url": "https://testservices.viafirma.com/via-tsa/tsa"
      }
    }
  ]
}

Note: params for padesConfiguration, xadesConfiguration, 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"
    ],
    "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/"
}

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",
  "contentHintsDescription": "Lorem ipsum dolor sit amet",
  "contentHintsType": "Lorem ipsum dolor sit amet"
}

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: