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:
{
"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:
viafirma_fortress_url
: URL base de la implementación de Viafirma Fortress, por ejemplo https://sandbox.viafirma.com/fortress o https://fortress.viafirma.com/fortressexecutionCode
: 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:
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:
viafirma_fortress_url
: URL base de la implementación de Viafirma Fortress, por ejemplo https://sandbox.viafirma.com/fortress o https://fortress.viafirma.com/fortresssignature_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:
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:
viafirma_fortress_url
: URL base de la implementación de Viafirma Fortress, por ejemplo https://sandbox.viafirma.com/fortress o https://fortress.viafirma.com/fortresssignature_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:
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 ""