API: Métodos relacionados con la firma con certificado

El proceso de firma en Viafirma Fortress, constará de los procesos de:

• Autenticación del cliente
• Solicitud de firma
• Autenticación y autorización de la solicitud de firma
• Ejecución de la firma
• Obtención del documento/s firmado/s

En los siguientes apartados describiremos los métodos disponibles en Viafirma Fortress, asociados a las operaciones de firma:

Nota: Para acceder a estos métodos es necesario tener un token de acceso (access_token) obtenido mediante una petición de autenticación y autorización con un scope de tipo client y un grant_type de tipo client_credentials, para lo que hay que seguir los pasos indicados en esta sección de la documentación.

Solicitud de firma

Uso del servicio

Método: POST
URL: {viafirma_fortress_url}/api/v1/signature

Donde:

• viafirma_fortress_url: URL base de la implementación de Viafirma Fortress, por ejemplo https://sandbox.viafirma.com/fortress o https://fortress.viafirma.com/fortress

Además, en la cabecera HTTP de la petición POST debe incluirse el token de acceso (access_token) de la siguiente forma:

Authorization: Bearer {access_token}

Ejemplo:

Método: POST
URL: {viafirma_fortress_url}/api/v1/signature
Header de la petición: Authorization: Bearer 0b79bab50daca910b000d4f1a2b675d604257e42

Parámetros del servicio

Este servicio recibe por parámetros la configuración de la firma empleada por cada documento a firmar, donde se indica, entre otras cosas, el tipo de firma que se quiere realizar, el documento a firmar…

Los parámetros que se reciben (en formato application/json) tienen la siguiente forma:

{
  "multifactorAuth": false,
  "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": "contrato.pdf"
      },
      "signatureType": "PADES_LTA",
      "signatureAlgorithm": "RSA_SHA256",
      "packaging": "ENVELOPED",
      "reason": " test PAdES signature ",
      "location": "Sevilla",
      "padesConfiguration": {
        "stamper": {
          "csvPath": "http://localhost:7080/fortress/v#",
          "logoB64": "iVBORw0KGgoAAAANSUhEUgAAAWYAAABsCAYAAABZyhj...",
          "page": 1,
          "type": "QR_BARCODE128",
          "xAxis": 80,
          "yAxis": 700
        }
      },
      "tsa": {
        "type": "URL",
        "url": "https://testservices.viafirma.com/via-tsa/tsa"
      }
    }
  ]
}

Nota: Los detalles de los parámetros padesConfiguration, xadesConfiguration, tsa y policy se muestran más adelante.

Donde:

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.

Configuración PAdES

Esta configuración solo se aplica para las firmas cuyo signatureType es de tipo PAdES (PAdES B, PAdES T, PAdES LT, PAdES LTA).

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

El objeto stamper es opcional, y sirve para definir un sello visual asociado a la firma PAdES.

{
  "stamper": {
    "csvPath": "https://fortress.viafirma.com/fortress/v#",
    "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"
  }
}

Si en la llamada a la API NO viene informado el valor timeZoneId aplicaremos el siguiente criterio:

• Si la petición pertenece a un usuario, emplearemos el timezone del usuario, si no lo tiene informado, pero pertenece a algún grupo que lo tenga informado, aplicamos el del primer grupo que lo tenga informado, si no aplicamos el configurado por defecto en el sistema.

Para el tipo de sello IMAGE se debe especificar la imagen de fondo del sello en formato Base64 usando el atributo imageB64 o indicando una URL en el atributo imageUrl.

Configuración XAdES

Esta configuración solo se aplica para las firmas cuyo signatureType es de tipo 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/"
}

Donde:

Configuración TSA

Para los tipos de firma que incluyan sellado de tiempo, se debe informar la configuración de la TSA.

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

Configuración de políticas

Para que la firma tenga una política y se la pueda considerar de tipo EPES, podemos definir los valores de la misma con esta configuración.

{
  "id": "102039485-10283757-102837575",
  "description": "Sample policy",
  "digestAlgorithm": "SHA256",
  "digestValueB64": "JVBERi0xLjMKJcTl8uXlRU9GC",
  "contentHintsDescription": "Lorem ipsum dolor sit amet",
  "contentHintsType": "Lorem ipsum dolor sit amet"
}

Respuesta del servicio

La respuesta de este servicio vendrá dada (en formato application/json) de la siguiente forma:

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

Donde:

Errores del servicio

Los errores devueltos por el servicio (devueltos en formato application/json) tienen el siguiente aspecto:

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

Donde:

Posibles errores:

Autenticación del usuario en Viafirma Fortress y selección de certificado

En la sección Autenticación del usuario y autorización de operaciones de firma, se describe el procedimiento de autenticación y selección de certificado empleados en el proceso de firma.

Como resultado del proceso, se actualizará la operación de preparación de firma, asignando el certificado, y autorizando la operación para poder firmar los documentos.

Ejecución de la firma

Con este método firmaremos los documentos asociados a la operación de preparación de firma.

Uso del servicio

Método: POST
URL: {viafirma_fortress_url}/api/v1/signature/{executionCode}/execute

Además, en la cabecera HTTP de la petición POST debe incluirse el token de acceso (access_token) de la siguiente forma:

Authorization: Bearer {access_token}

Ejemplo:

Método: POST
URL: {viafirma_fortress_url}/api/v1/signature/f116305e7f7c44f3a29385028c5374ba/execute
Header de la petición: Authorization: Bearer 0b79bab50daca910b000d4f1a2b675d604257e42

Donde:

• viafirma_fortress_url: URL base de la implementación de Viafirma Fortress, por ejemplo https://sandbox.viafirma.com/fortress o https://fortress.viafirma.com/fortress
• executionCode: Código de ejecución que devolvió el método signature

Ejemplo:

Método: POST
URL: {viafirma_fortress_url}/api/v1/signature/f116305e7f7c44f3a29385028c5374ba/execute

Parámetros del servicio

Este servicio recibe por parámetros el código de ejecución executionCode, resultante del procedimiento de preparación de la firma, con dicho código obtendremos la información asociada a cada operación de firma.

Los parámetros que se reciben (en formato application/json) vacío:

{
}

Respuesta del servicio

La respuesta de este servicio vendrá dada (en formato application/json) de la siguiente forma:

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

Donde:

Errores del servicio

Los errores devueltos por el servicio (devueltos en formato application/json) tienen el siguiente aspecto:

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

Donde:

Posibles errores:

Obtención de documento firmado

Con este método podemos obtener un documento firmado usando un identificador de firma.

Uso del servicio

Método: GET
URL: {viafirma_fortress_url}/api/v1/signature/download/{signature_code}

Además, en la cabecera HTTP de la petición GET debe incluirse el token de acceso (access_token) de la siguiente forma:

Authorization: Bearer {access_token}

Donde:

• viafirma_fortress_url: URL base de la implementación de Viafirma Fortress, por ejemplo https://sandbox.viafirma.com/fortress o https://fortress.viafirma.com/fortress
• signature_code: Código de la firma de la que se desea obtener el documento

Ejemplo:

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

Respuesta del servicio

La respuesta de este servicio vendrá dada en formato application/octet-stream.

Errores del servicio

Los errores devueltos por el servicio (devueltos en formato application/json) tienen el siguiente aspecto:

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

Donde:

Posibles errores:

Descarga de documento firmado

Con este método podemos descargar un documento firmado usando un identificador de firma.

Uso del servicio

Método: GET
URL: {viafirma_fortress_url}/api/v1/signature/download/{signature_code}

Además, en la cabecera HTTP de la petición GET debe incluirse el token de acceso (access_token) de la siguiente forma:

Authorization: Bearer {access_token}

Donde:

• viafirma_fortress_url: URL base de la implementación de Viafirma Fortress, por ejemplo https://sandbox.viafirma.com/fortress o https://fortress.viafirma.com/fortress
• signature_code: Código de la firma de la que se desea descargar el documento

Ejemplo:

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

Respuesta del servicio

La respuesta de este servicio vendrá dada (en formato application/octet-stream)

Errores del servicio

Los errores devueltos por el servicio (devueltos en formato application/json) tienen el siguiente aspecto:

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

Donde:

Posibles errores: