API: Métodos relacionados con la firma desatendida con certificado

Última actualización: 13 noviembre 2024

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

• Autenticación del cliente
• 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 desatendida

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:

{
  "certificateCode": "b8a25e04ab864583bb5ea8d02883e832",
  "signatureConfigurations": [
    {
      "ref": "#1",
      "document": {
        "bytesB64": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQ...",
        "name": "contrato.pdf"
      },
      "signatureType": "PADES_B",
      "signatureAlgorithm": "RSA_SHA256",
      "packaging": "ENVELOPED",
      "padesConfiguration": {
        "stamper": {
          "csvPath": "http://localhost:7080/fortress/v#",
          "logoB64": "iVBORw0KGgoAAAANSUhEUgAAAWYAAABsCAYAAABZyhj...",
          "page": 1,
          "type": "QR_BARCODE128",
          "xAxis": 80,
          "yAxis": 700
        }
      }
    }
  ]
}

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 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#",
    "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,
    "timeZoneId": "America/Santo_Domingo"
  }
}

Dependiendo del type elegido, el sello tendrá unas dimensiones preestablecidas (en píxeles):

• PDF417: 300x130
• QR_BARCODE128: 600x100
• QR: 450x50
• BARCODE128: 550x70
• IMAGE: Mantiene las dimensiones de la imagen especificada en imageB64
• TEXT: 400x50

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

• En caso de firma desatendida, si el Sistema Cliente 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.

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",
  "url" : "https://sample/lorem_ipsum_dolor_sit_amet.pdf",
  "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:

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}

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
Header de la petición: Authorization: Bearer 0b79bab50daca910b000d4f1a2b675d604257e42

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.

Se debe proporcionar(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:

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: