Variantes del origen del documento

Última revisión: 14 Noviembre 2024

A efectos de facilitar las pruebas, en todos los casos de uso descritos en los capítulos anteriores se ha utilizado la opción donde Viafirma es quien genera el PDF a partir de una plantilla previamente definida. El Documento que será enviado al firmante podrá ser construido de varias formas:

• 01 - Documento previamente subido al sistema (recomendado)
• 02 - Documento publicado en una URL
• 03 - Documento generado a partir de una plantilla
• 04 - Documento previamente firmado en Viafirma

Para la construicción de un adjunto se podrá realizar con los puntos 1 y 2. El único cambio a tener en cuenta a la hora de definir el servicio afecta al objeto document o attachments:

01 - PDF previamente subido

Este mecanismo necesita de dos pasos previos a la creación de la solcitud:

• solicitar link
• subida del documento al link obtenido
• crear solicitud de firma

Paso 1 de 3: solicitar LINK para el upload

Para subir un documento o un adjunto, necesitamos pedir vía API un link al que subir el documento.

GET {{endpoint}}/uploads/link/pdf

Response:

{
    "link": "string",
    "token": "string",
    "expires": 999999999
}

donde:

• link: URL securizada que debes usar para la subida del documento.
• token: identificador único asociado a cada documento que desees firmar.
• expires: caducidad del link expresada en milliseconds. En un entorno de producción la caducidad por defecto es de 3h pero podrá ser modificado.

Paso 2 de 3: upload del documento

Subimos el fichero con un PUT al link obtenido en la respuesta anterior.

PUT link

Ejemplo:

PUT https://bucket/24399snasbx/uploads/1715072084149_bc...cffb1

IMPORTANTE: asegúrate que tu método PUT no tenga activada la securización del servicio REST. El servicio al que será subido el documento ya se ocupa de verificar la firma incluida en el link generado.

Ejemplo de uso desde Postman:

Paso 3 de 3: solicitud de firma

En tu llamada habitual al servicio SET para crear nuevas solicitudes de firma debes utilizar el token obtenido. Si en tu política incluyes N documentos o N adjuntos, tendrás que asociarle a cada uno de ellos el token obtenido en su correspondiente upload.

"document" : {
  "templateType" : "string",
  "templateReference" : "string"
}

"attachments": [ 
  {
    "type": "string",
    "fileReference": "string",
    "recipientKey" : "string"
  }
]

donde:

• templateType: debes indicar uploaded
• templateReference: debes indicar el token asociado al documento subido anteriormente.
• type: debes indicar el tipo de adjunto. Lo valores disponibles son: IMAGE, PDF, PDF_IMAGE, VIDEO, AUDIO.
• fileReference: debes indicar el token asociado al archivo subido anteriormente.

Ejemplo:

"document" : {
  "templateType" : "uploaded",
  "templateReference" : "eyJ0eXAiOiJKV1QiLCJhbiBpcmVzIjoiMTcxNTA4NTEyMTU4M[...]XTYUQ",
}

"attachments": [
  {
    "type": "PDF",
    "fileReference": "eyJ0eXAiOiJKV1QiLCJhbiBpcmVzIjoiMTcxNTA4NTEyMTU4M[...]XTYUQ",
  }
]

Ejemplo de un payload completo para solictar un nuevo SET:

{
"groupCode": "myGroupDemo-AA002",
"recipients": [
    {
      "key": "signer01",
      "name" : "John Doe"
      "presential" : true
    }
  ], 
 "messages" : [{
        "document" : {
            "templateType": "uploaded",
            "templateReference": "eyJ0eXAiOiJKV1QiLCJhbiBpcmVzIjoiMTcxNTA4NTEyMTU4M[...]XTYUQ"
        },
        "policies" : [ {
            "signatures" : [ {
                "type" : "CLIENT",
                "recipientKey" : "signer01"
            } ],
            "attachments" : [ {
                "type" : "PDF",
                "helpText": "Attachment01",
                "fileReference" : "eyJ0eXAiOiJKV1QiLCJhbiBpcmVzIjoiMTcxNTA4NTEyMTU4M[...]XTYUQ",
                "recipientKey" : "signer01"
            } ]
        } ]
    }]
}

Ejemplo de un payload completo para solictar un nuevo SET con 2 documentos, cada uno con 1 adjunto

{
"groupCode": "myGroupDemo-AA002",
"recipients": [
    {
      "key": "signer01",
      "name" : "John Doe"
      "presential" : true
    }
  ], 
 "messages" : [{
        "document" : {
            "templateType": "uploaded",
            "templateReference": "eyJ0eXAiOiJKV1QiLCJhbiBpcmVzIjoiMTcxNTA4NTEyMTU4M[...]XTYUQ"
        },
        "policies" : [ {
            "signatures" : [ {
                "type" : "CLIENT",
                "recipientKey" : "signer01"
            } ],
            "attachments" : [ {
                "type" : "PDF",
                "helpText": "Attachment01",
                "fileReference" : "eyJ0eXAiOiJKV1QiLCJhbiBpcmVzIjoiMTcxNTA4NTEyMTU4M[...]XTYUQ",
                "recipientKey" : "signer01"
            } ]
        } ]
    },{
        "document" : {
            "templateType": "uploaded",
            "templateReference": "mVzIjoiMTcxNTA4NTEyMeyJ0eXAiOiJKV1QiLCJhbiBpcTU4M[...]XTYUQ"
        },
        "policies" : [ {
            "signatures" : [ {
                "type" : "CLIENT",
                "recipientKey" : "signer01"
            } ],
            "attachments" : [ {
                "type" : "PDF",
                "helpText": "Attachment02",
                "fileReference" : "eyJ0eXAiOiJKV1QiLCJhbiBpcmVzIjoiMTcxNTA4NTEyMTU4M[...]XTYUQ",
                "recipientKey" : "signer01"
            } ]
        } ]
    }]
}

02 - PDF publicado en URL

El integrador publica el PDF en una URL en la que Viafirma lo recuperará para su procesamiento, en cuyo caso la configuración del objeto document debe definirse de la siguiente manera:

"document" : {
  "templateType" : "url",
  "templateReference" : "<here_your_url"
}

Para la configuración del objeto attachments debe definirse de la siguiente manera:

"attachments" : [{
  "type" : "PDF",
  "fileReference" : "<here_your_url>"
} ]

donde:

• type: debes indicar el tipo de adjunto. Lo valores disponibles son: IMAGE, PDF, PDF_IMAGE, VIDEO, AUDIO.
• fileReference: debes indicar la url donde se encuentra el fichero (El tipo del fichero debe coincidir con el type indicado).

Para agilizar tus pruebas aquí te dejamos un PDF disponible en una URL pública:

https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf

03 - PDF basado en plantilla

El integrador indica el código de la plantilla que se usará para construir el documento. Esta plantilla debe existir previamente en Viafirma.

"document" : {
  "templateType" : "pdf",
  "templateCode" : "your_template_code"
}

04 - PDF previamente firmado en Viafirma

El integrador puede hacer referencia a un proceso de firma de Viafirma, usando el PDF firmado en dicho proceso para volver a ser enviado y firmado.

"document" : {
  "templateType" : "message",
  "templateReference" : "<your_messageCode>"
}

En la colección postman que puedes descargar para probar el API de viafirma tienes un set de pruebas con estas modalidades llamado "Variantes del origen del PDF".