API: Método relacionado con la extensión de firma

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

• Autenticación del cliente
• Solicitud de extensión de firma
• Obtención del documento/s extendido/s firmado/s

En los siguientes apartados describiremos los métodos disponibles en Viafirma Fortress, asociado a las operaciones de extensión de firma:

Solicitud 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 extensión de firma

Uso del servicio

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

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: https://fortress.viafirma.com/fortress/api/v1/signature/extend
Header de la petición: Authorization: Bearer 0b79bab50daca910b000d4f1a2b675d604257e42

Parámetros del servicio

Este servicio recibe por parámetros la configuración de la extensión de firma empleada por cada documento a extender, donde se indica, entre otras cosas, el tipo de firma al que se desea extended el documento firmado, el documento a extender …

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

{
  "extendSignatureConfigurations": [
    {
      "document": {
        "bytesB64": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQ...",
        "name": "contrato.pdf"
      },
      "signatureType": "PADES_LTA",
      "signatureAlgorithm": "RSA_SHA256",
      "packaging": "ENVELOPED",
      "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 PAdES

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

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:

{
  "ref": "d8e3d98dc20e46188fd067df28048934",
  "bytesB64": "MIMBKM8GCSqGSIb3DQEHAqCDASi/MIMBKLoCAQUxDzANBglghkgBZQMEAgEFADCC1QsGCSqGSIb3DQEHAaCC1PwEgtT4JVBERi0xLjMKJcTl8uXrp..."
}

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: