Firmar con WACOM: paso a paso

En esta guía se explicará el paso a paso para la integración de un sistema de terceros, por ejemplo un CRM, con viafirma documents y con un caso de uso "Firmar desde Wacom".

Secuencia de trabajo

Secuencia 1: solicitamos servicio de firma

Hacemos POST del servicio MESSAGE, enviando nuestro PDF y el identificador de políticas de firma que deseemos.

Servicio: https://sandbox.viafirma.com/documents/api/v3/messages
Método: POST
Seguridad: OAuth v1.0

Resuesta esperada:

Código de respuesta: 200
Body de la respuesta: {messageCode}

Ejemplo JSON para el POST:

{
  "groupCode" : "myGroupCode",
  "workflow" : {
    "code" : "EX006"
  },
  "notification" : {
    "text" : "card title printed on signature request",
    "detail" : "card detail printed on signature request",
    "sharedLink" : {
      "appCode" : "com.viafirma.documents"
    }
  },
  "document" : {
    "policyCode" : "myPolicy_id",
    "templateType" : "base64",
    "templateReference" : "****HERE YOUR PDF IN BASE64 FORMAT*****"
  },
  "callbackMails" : "[email protected],[email protected],[email protected]"
}

descripción de atributos

groupCode: es opcional, y al indicarlo permitirá que cualquier usuario que pertenezca al grupo indicado podrá hacer seguimiento de la solicitud. Además nos permitirá asignar un diseño a la página de firma; para ello, habrá que crear un estilo llamado igual al grupo; los estilos se gestionan en el backend de viafirma documents, debiendo contar con permisos de administrador.
workflow.code: para la firma con WACOM usaremmos el código "EX006".
notification.text: es opcional, y se usa para indicar un título a la solicitud de firma.
notification.detail: es opcional, y se usa para la descripción extendida a la solicitud de firma.
notification.sharedLink.appCode: aquí indicaremos el identificador de la app que se usará para la firma; podrá ser personalizada para cada cliente, pero por defecto se debe usar la aplicación escritorio de viafirma documents, con soporte a wacom. Para ello, indicar el valor "com.viafirma.documents".

document.policyCode: aquí indicaremos el identificador de la política de firma que se aplicará al PDF remitido. Las políticas se diseñan y gestionan en el backend de viafirma documents. En caso de no contar con políticas gestionadas por viafirma, consultar en la documentación cómo incluirlas manualmente en el POST del servicio.
document.templateType: se permiten hasta tres valores: "base64", "template" y "url"; si el PDF es generado por un sistema externo, por ejemplo un CRM, indicaremos "base64"; si el PDF estuviera disponible en un URL como un recurso directo (URI), entonces usaremos el tipo "URL"; en caso de gestionar las plantillas, en formatos "docx, odt o pdf", desde el propio backend de viafirma documents, con la ayuda del diseñador de plantillas de viafirma, entonces usaremos el valor "template".
document.templateReference: dependiendo del templateType usado, la referencia esperada para cada caso será distintas: un base64, una URL en formato http o https o bien el código de la plantilla gestionada en el propio backend de viafirma.
callbackMail: es opcional, y podremos indicar una o varias cuentas de email a las que se enviará el documento firmado una vez finalzada la operación.
callbackResponse: es opcional, y podremos indicar una URL a la que se hará POST de forma automática, enviando un objeto MESSAGE con toda la información necesaria para cualquier integrador que desee automatizar acciones de negocio.

Secuencia 2: montar página de firma

A partir del messageCode obtenido tras hacer el POST con la solicitud de firma vamos a realizar un GET para obtener la siguiente información:

Servicio: https://sandbox.viafirma.com/documents/api/v3/messages/{messageCode}
Método: GET
Seguridad: OAuth v1.0

Resuesta esperada:

Código de respuesta: 200
Body de la respuesta: objeto MESSAGE (en formato JSON)

del objeto MESSAGE obtenido, nos interesan dos datos: link de firma y estado, y los obtendremos en los valores de los siguientes atributos:

notification.sharedLink.link
workflow.current

Con el valor del link autogenerado por viafirma, se montará una vista web, con un permalink único, y que incluirá todos los componentes de firma necesarios según se hayan definidos en la política de firma.

En nuestro caso, el usuario verá un enlace para abrir o descargar e instalar por primera vez la app de escritorio que interacturará con el pad de firma WACOM.

Una vez se haya procedido a la firma del documento, y en caso de que se haya definido en el POST del servicio una URL para hacer callback e informar de la finalización del proceso, el estado pasará a ser "RESPONSED", estado que ya permitirá consumir el servicio que nos devolverá el documento firmado.

Secuencia 3: obtener el documento firmado

En caso de no haber definido una URL de respuesta automática, se deberá consultar el estado del mensaje hasta comprobar que su estado ya es "RESPONSED" para poder consumir el siguiente servicio:

Servicio: https://sandbox.viafirma.com/documents/api/v3/documents/download/signed/{messageCode}
Método: GET
Seguridad: OAuth v1.0

Resuesta esperada:

Código de respuesta: 200
Body de la respuesta: objeto DOWNLOAD (en formato JSON), donde dispondremos de la siguiente información:

{
  "link": "temporal link for downloading",
  "md5": "signed-file hash",
  "fileName": "filename",
  "expires": "timestamp in miliseconds format"
}