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:

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 ""