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:

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:

{
  "signatureConfigurations": [
    {
      "ref": "#1",
      "document": {
        "bytesB64": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQ...",
        "name": "contrato.pdf"
      },
      "signatureType": "PADES_B",
      "signatureAlgorithm": "RSA_SHA256",
      "packaging": "ENVELOPED",
      "reason": " test PAdES signature ",
      "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:

Parámetro Tipo Descripción
userCode string Usuario que debe de realizar la firma, si el sistema cliente no informa dicho valor, Viafirma Fortress solicitará el usuario a emplear en el proceso de autenticación y autorización de la solicitud de firma
certificateCode string Código de certificado a emplear en la firma, si el sistema cliente no informa dicho valor, Viafirma Fortress solicitará el certificado a emplear en el proceso de firma tras de autenticar al usuario
certificatePassword string Contiene la password del certificado, este campo solamente está permitido para la firma desatendida.
multifactorAuth boolean Si se indica true, fuerza al empleo de 2 factores de autenticación.
async string Si se establece con el valor true la llamada al servicio de ejecución de firma se realiza de forma asíncrona.
callbackUrl string 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.
certificateFilter string Atributos por el que filtrar el certificado. Introduces que filtros quieres que cumpla el certificado para ser usado.
signatureConfigurations/document/name string Nombre del documento a firmar
signatureConfigurations/document/bytesB64 string Documento a firmar, codificado en Base64
signatureConfigurations/document/url string URL del documento a firmar
signatureConfigurations/signatureType string Tipo de firma. Valores disponibles:
- CADES_B
- CADES_T
- CADES_LT
- CADES_LTA
- PADES_B
- PADES_T
- PADES_LT
- PADES_LTA
- XADES_B
- XADES_T
- XADES_LT
- XADES_LTA
- PKCS1
signatureConfigurations/signatureAlgorithm string Algoritmo que se usará para cifrar la firma. Valores disponibles:
- RSA_SHA1
- RSA_SHA224
- RSA_SHA256
- RSA_SHA384
- RSA_SHA512
signatureConfigurations/packaging string Envoltura de la firma. Valores disponibles:
- ENVELOPED
- ENVELOPING
- DETACHED
signatureConfigurations/reason string OPCIONAL, motivo de la firma
signatureConfigurations/location string OPCIONAL, localización de la firma
signatureConfigurations/ref string Si se informa se devolverá el mismo valor en el resultado de la firma.

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.

Parámetro Tipo Descripción
oid List - String Lista de OID que necesita tener el certificado para ser válido
issuer.C Single list - String (Solo se permite uno, a partir de la versión 6.2.5 de Viafirma Fortress, se elimina esta restricción) CountryName -> ES
issuer.OU Single list - String (Solo se permite uno, a partir de la versión 6.2.5 de Viafirma Fortress, se elimina esta restricción) OrganizationalUnit -> Ceres
issuer.CN Single list - String (Solo se permite uno, a partir de la versión 6.2.5 de Viafirma Fortress, se eliminasesta restricción) CommonName -> AC FNMT Usuarios
issuer.O Single list - String (Solo se permite uno, a partir de la versión 6.2.5 de Viafirma Fortress, se elimina esta restricción) Organization -> FNMT-RCM
subject.SURNAME Single list - String (Solo se permite uno, a partir de la versión 6.2.5 de Viafirma Fortress, se elimina esta restricción) APELLIDOS -> ZAMORANO DE EJEMPLO
subject.C Single list - String (Solo se permite uno, a partir de la versión 6.2.5 de Viafirma Fortress, se elimina esta restricción) CountryName -> ES
subject.SERIALNUMBER Single list - String (Solo se permite uno, a partir de la versión 6.2.5 de Viafirma Fortress, se elimina esta restricción) Numero de serie -> 71121212M
subject.CN Single list - String (Solo se permite uno, a partir de la versión 6.2.5 de Viafirma Fortress, se elimina esta restricción) CommonName -> ZAMORANO DE EJEMPLO JOSE LUIS - 71121212M
subject.GIVENNAME Single list - String (Solo se permite uno, a partir de la versión 6.2.5 de Viafirma Fortress, se elimina esta restriccióno) Nombre -> JOSE LUIS

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"
  }
}
Parámetro Tipo Descripción
stamper/csvPath string URL de verificación de la firma
stamper/xAxis int Posición (en el eje X) del sello de firma
stamper/yAxis int Posición (en el eje Y) del sello de firma
stamper/width int Opcional. Ancho del sello de firma
stamper/height int Opcional. Alto del sello de firma
stamper/imageB64 string Imagen de fondo del sello de firma codificado en Base64
stamper/imageUrl string URL de la imagen de fondo del sello de firma
stamper/logoB64 string Opcional. Logo del sello de firma (se pintará en la parte inferior derecha del sello)
stamper/page int Página donde se pintará el sello. Se puede usar el valor -1 para indicar la última página o el valor 0 para pintar el sello en todas las páginas del documento
stamper/rotation string Rotación del sello. Si se informa, el sello rotará los grados indicados. Valores posibles:
- ROTATE_90
- ROTATE_270
stamper/textLine1 string Primera linea textual a pintar en el contenido del sello de firma
stamper/textLine2 string Segunda linea textual a pintar en el contenido del sello de firma
stamper/textLine3 string Tercera linea textual a pintar en el contenido del sello de firma
stamper/type string Tipo de sello. Valores disponibles:
- PDF417
- QR_BARCODE128
- QR
- BARCODE128
- IMAGE
- TEXT
- QR_NO_TEXT
- QR_SCALED
- CUSTOM_TEXT
- QR_REDUCED
- CSV
- CSV_QR
- IMAGE_TEXT
- DEFAULT
stamper/timeZoneId string String que se corresponderá con la lista estándar de zonas horarias.

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:

Parámetro Tipo Descripción
signedInfoCanonicalizationMethod string Método de canonización del nodo signedInfo
signedPropertiesCanonicalizationMethod string Método de canonización del nodo signedProperties
xPathLocationString string Selector del nodo bajo el que se insertará la firma, en formato XPath:
Nodos sin namespace
Por ejemplo <factura> podríamos emplear:
"xPathLocationString": "//factura"
Referencia:
- https://www.w3schools.com/xml/xpath_syntax.asp
Nodos con namespace
por ejemplo: <T:TicketBai xmlns:T="urn:ticketbai:emision"> , podríamos emplear:
"xPathLocationString": "/*[\"TicketBai\"=local-name()]/Sujetos/Emisor" para seleccionar el nodo Emisor
Referencia:
- https://www.ibm.com/support/pages/how-use-xpath-namespaces-rit
claimedSignerRoles array Roles del firmante
transformAlgorithms array Algoritmos de transformación para los nodos. Posibles valores:
- "http://www.w3.org/TR/2001/REC-xml-c14n-20010315"
- "http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments"
- "http://www.w3.org/2001/10/xml-exc-c14n#"
- "http://www.w3.org/2001/10/xml-exc-c14n#WithComments"
- "http://www.w3.org/2006/12/xml-c14n11"
- "http://www.w3.org/2006/12/xml-c14n11#WithComments"
- "http://santuario.apache.org/c14n/physical"
dssReferenceUri string Identificador del nodo a firmar

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"
}
Parámetro Tipo Descripción
type string Tipo de TSA. Si requiere autenticación con usuario y password, usaremos el valor USER, si requiere autenticación con certificado CERTIFICATE, si requiere autenticación con certificado por TSL CERTIFICATE_TLS, si no, el valor URL
user string Usuario para la autenticación en la TSA (solo para type con valor USER)
password string Contraseña para la autenticación en la TSA (para los type con valor USER o CERTIFICATE_TLS)
url string URL de de la TSA
certificateCode string Código del certificado para la autenticación en la TSA (para los type con valor CERTIFICATE o CERTIFICATE_TLS)

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"
}
Parámetro Tipo Descripción
id string Identificador de la política
description string Descripción de la política
digestAlgorithm string Algoritmo de cifrado. Posibles valores:
- SHA1
- SHA224
- SHA256
- SHA384
- SHA512
- RIPEMD160
- MD2
- MD5
digestValueB64 string Valor (codificado en Base64)
contentHintsDescription string Descripción de la ayuda
contentHintsType string Tipo de ayuda

Respuesta del servicio

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

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

Donde:

Parámetro Tipo Descripción
authCode string Código de autorización
exeCode string Código de ejecución

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:

Parámetro Tipo Descripción
error string Código del error
error_description string Descripción del error

Posibles errores:

Código de error Error
invalid_request Petición incorrecta. Alguno de los parámetros de entrada no es correcto. (HTTP Status: 400)
invalid_token El access_token utilizado no es correcto (HTTP Status: 401)
user_not_found El usuario no es correcto o no está activo (HTTP Status: 404)

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:

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:

Parámetro Tipo Descripción
bytesB64 string Documento firmado, codificado en Base64. Si se especifica el formato de firma asíncrona el resultado no incluye el documento firmado. Será necesario invocar al servicio de descarga del documento usando el signatureCode obtenido.
signatureCode string Identificador de firma
mimeType string MIME type del documento firmado
ref string Se devuelve el mismo valor si fue informado en la solicitud de firma

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:

Parámetro Tipo Descripción
error string Código del error
error_description string Descripción del error

Posibles errores:

Código de error Error
invalid_request Petición incorrecta. Alguno de los parámetros de entrada no es correcto. (HTTP Status: 400)
invalid_token El access_token utilizado no es correcto (HTTP Status: 401)
not_authorized_signature El usuario no ha sido autenticado en los factores de autenticación (HTTP Status: 401)
user_not_found El usuario no es correcto o no está activo (HTTP Status: 404)
certificate_not_found El certificado con el que se desea firmar no es correcto o no está activo (HTTP Status: 404)
signature_error Error durante la firma (HTTP Status: 500)

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:

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:

Parámetro Tipo Descripción
error string Código del error
error_description string Descripción del error

Posibles errores:

Código de error Error
document_not_found No se ha encontrado ningún documento para el ID de firma provisto (HTTP Status: 404)

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:

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:

Parámetro Tipo Descripción
error string Código del error
error_description string Descripción del error

Posibles errores:

Código de error Error
document_not_found No se ha encontrado ningún documento para el ID de firma provisto (HTTP Status: 404)

results matching ""

    No results matching ""