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:
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 |
document/bytesB64 | string | Documento a firmar, codificado en Base64 |
signatureType | string | Tipo de firma. Valores disponibles: - CADES_T - CADES_LT - CADES_LTA - PADES_T - PADES_LT - PADES_LTA - XADES_T - XADES_LT - XADES_LTA |
signatureAlgorithm | string | Algoritmo que se usará para cifrar la firma. Valores disponibles: - RSA_SHA1 - RSA_SHA224 - RSA_SHA256 - RSA_SHA384 - RSA_SHA512 |
packaging | string | Envoltura de la firma. Valores disponibles: - ENVELOPED - ENVELOPING - DETACHED |
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
}
}
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/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 | 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 |
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:
{
"ref": "d8e3d98dc20e46188fd067df28048934",
"bytesB64": "MIMBKM8GCSqGSIb3DQEHAqCDASi/MIMBKLoCAQUxDzANBglghkgBZQMEAgEFADCC1QsGCSqGSIb3DQEHAaCC1PwEgtT4JVBERi0xLjMKJcTl8uXrp..."
}
Donde:
Parámetro | Tipo | Descripción |
---|---|---|
ref | string | referencia de la extensión |
bytesB64 | string | Base 64 del documento extendido |
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) |
results matching ""
No results matching ""