Firma automática de adjuntos

Última revisión: 31 Mayo 2024

En la sección Subida de ficheros adjuntos a solicitudes te explicamos cómo inluir adjuntos en tus SETS, y en esta sección te explicamos cómo podrás agregarle configuración adicional para 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",
    "recipientKey" : "signer01",
    "helpText" : "Adjunta la foto de la recepción de la mercancía",
    "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 de un SET con adjuntos firmables:

{
"groupCode": "myTestGroup_822",
"recipients": [
    {
      "key": "signer1",
      "name" : "John Doe",
      "mail" : "[email protected]"
    }
  ],
 "messages" : [{
        "document" : {
            "templateType": "uploaded",
            "templateReference": "hbiBpcmeyJ0eXAiOiJKV1QiLCJVzIjoiMTcxNTA4NTEyMTU4M[...]iMTcxN"
        },
        "policies" : [ {
            "evidences" : [ {
                "type" : "SIGNATURE",
                "recipientKey" : "signer1",
                "helpText" : "Firma de John Doe",
                "positions" : [ {
                    "rectangle" : {
                    "x" : 386,
                    "y" : 591,
                    "width" : 125,
                    "height" : 90
                    },
                    "page" : 1
                } ]
            }],
            "attachments" : [ {
                "type" : "IMAGE",
                "recipientKey" : "signer1",
                "helpText" : "Adjunta la foto de la recepción de la mercancía",
                "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