Firma automática de adjuntos

Última revisión: 19 Oct 2022

Entre los distintos elementos disponibles en la políticas de firma se encuentran los ATTACHMENTS, donde podrás solicitar a los usuarios firmantes que adjunten ficheros durante el proceso de firma.

A partir de la v3.7.41 estos adjuntos podrán configurarse para que sean firmados automáticamente, en backend, permitiendo asegurar la integridad de los mismos.

A continuación te explicamos cómo hacerlo.

Agregar attachment en la política

Para agregar adjuntos en tu política debes hacer uso del objeto attachments, al que podrás agregar una configuración de firma:

            "attachments" : [ {
                "type" : "IMAGE",
                "helpText" : "Adjunto test: IMAGE",
                "signature": {
                    "type" : "SERVER"
                }
            } ]

Donde:

  • type: (string) define el tipo de adjunto. Lo valores disponibles son: IMAGE, PDF, PDF_IMAGE, VIDEO, AUDIO.
  • helpText: (string) (opcional) ayuda contextual mostrada en la pantalla de firma.
  • signature.type: (string) valor fijo que debe indicarse "SERVER", que define el tipo de firma desatendida, y hereda toda la configuración definida en los ajustes del grupo o en su defecto en los ajustes del backend.
  • typeFormatSign: (string) (opcional) define el formato de firma. En caso de indicarse se usa formato por defecto definido en el grupo o en su defecto en el backend. Los valores admitidos dependerán del tipo de adjunto; para adjuntos del tipo PDF los formatos admitidos serán: PAdES_BASIC, PAdES_BES, PAdES_EPES, PAdES_LTV, PDF_PKCS7. Y para el resto de tipos el formato será: CADES_B.

Ejemplo:

{
"groupCode": "{{groupCode}}",
"title" :     "Proceso con adjunto CON FIRMA : test {{nameRandom}}",
"description" : "Test firma desatendida de adjuntos",
"recipients": [
    {
      "key": "signer1",
      "presential" : true
    }
  ],
 "messages" : [{
        "document" : {
            "templateType": "url",
            "templateReference": "{{pdf_url_sample}}"
        },
        "policies" : [ {
            "evidences" : [ {
                "type" : "SIGNATURE",
                "helpText" : "Firma de {{nameRandom}}",
                "positions" : [ {
                    "rectangle" : {
                    "x" : 386,
                    "y" : 591,
                    "width" : 125,
                    "height" : 90
                    },
                    "page" : 1
                } ],
                "recipientKey" : "signer1"
            }],
            "attachments" : [ {
                "type" : "IMAGE",
                "helpText" : "Adjunto test: IMAGE",
                "signature": {
                    "type" : "SERVER"
                }
            } ],
            "signatures" : [ {
                "type" : "SERVER"
            } ]
        } ]
    }]
}

Obtener datos del adjunto subido por el usuario

Una vez finalizado el proceso de firma por parte del usuario, podrás consultar el detalle del adjunto a partir el método habitual del API.

GET /api/v3/messages/{messageCode}

Este método te devuelve un JSON con todo el detalle del proceso individual de firma. Recuerda que un SET está compuesto por 1 ó N messageCode, por lo que tendrás que iterar por cada uno de ellos para poder obtener el correspondiente código del adjunto con el que podrás descargarlo o acceder a su correspondiente versión firmada.

En esta respuesta también obtendrás el detalle del objeto ATTACHMENTS actualizado, incluyendo el ID DE FIRMA (idSign):

{
  "attachments": [
                {
                    "type": "VIDEO",
                    "code": "ZL581654693486017R296P001A001",
                    "status": "RECEIVED",
                    "helpText": "Adjunto test: VIDEO",
                    "date": 1654693508110,
                    "hash": "2da8fa064df6f1c1b3188cedef38a1f7b42500812020c60a99cca8d3d09bf197",
                    "fileName": "attachment-video.webm",
                    "readOnly": false,
                    "signature": {
                        "type": "SERVER",
                        "status": "SIGNED",
                        "idSign": "QZL5-8OAA-OF3O-TC2P-E165-4693-5151-67"
                    }
                }
            ]
}

Descargar adjuntos

A partir del messageCode y del attachmentCode con este método del servicio podrás descargar el adjunto.

GET /api/v3/evidences/attachmentFile/{messageCode}/{attachmentCode}

Descargar la versión firmada del adjunto

Cuando se habilita la firma desatendida en los adjuntos hay que tener en cuenta que solo para los casos de adjuntos basados en PDF la descarga del adjunto coincidirá con la versión firmada. Por ejemplo, el usuario final subió un PDF y este método devolvería un PADES (formato PDF firmado). En el caso de VIDEOS e IMÁGENES este método devolverá el FILE original, y no el firmado.

Para descargar la firma del adjunto (formato .csig), necesitarás el ID DE FIRMA (idSign), y podrás hacerlo accediendo a la siguiente URL de descarga directa del backend:

/d/{idSign}

Al tratarse de una firma detached, necesitarás el fichero original (attachment) más la firma (.csig) para poder comprobar su validez.

Quiero probarlo

Tienes disponible una colección postman con la que podrás probar esta funcionalidad.

Postman Collection

  • Colección: Documents API - Test Sign Attachments - Ref. 29213
  • Versión: 1.0
  • Fecha: 08-jun-2022

Control de Cambios

  • Versión: 1.0 - 08-jun-2022
    • Primera versión

Requisitos

  • disponible a partir de v3.7.41
  • el proceso de firma debe incluir en sus políticas el módulo de attachments con la nueva configuración asociada a la firma

Adjuntos en el correo y subidos directamente desde el API

Tenemos la opción de añadir ficheros adjuntos directamente al hacer la solicitud y aparte podemos indicar que ese adjunto vaya en el correo de callback junto con el documento firmado.

{
  "groupCode":"string",
  "externalCode":"string",
  "callbackMails": "string",
  "notification":{
    "text":"string",
    "detail":"string"
  },
  "document":{
    "templateType":"string",
    "templateReference":"string"
  },
  "policies":[
    {
      "signatures":[
        {
          "type":"string",
          "typeFormatSign":"string"
        }
      ],
      "attachments":[
        {
          "type":"IMAGE",
          "helpText":"Adjunto test: IMAGE",
          "signature":{
            "type":"SERVER"
          },
          "fileReference":"url | uploadToken",
          "inMail":"boolean"
        }
      ]
    }
  ]
}

Donde la parte de adjuntos (attachments):

fileReference: puede ser completada con un token del servicio de subida de ficheros de documents o con la 
url de fichero. De ser indicado este parámetro, los adjuntos se añadirán a la petición en su inicialización.

inMail: Valor booleano que indicará si el adjunto se enviará o no en el mail de callback de finalización de la petición.

signature: Si se indica el objeto signature el adjunto también será firmado.

results matching ""

    No results matching ""