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".
Hacemos POST del servicio MESSAGE, enviando nuestro PDF y el identificador de políticas de firma que deseemos.
https://sandbox.viafirma.com/documents/api/v3/messages
Resuesta esperada:
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]"
}
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.
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.
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:
https://sandbox.viafirma.com/documents/api/v3/messages/{messageCode}
Resuesta esperada:
del objeto MESSAGE obtenido, nos interesan dos datos: link de firma y estado, y los obtendremos en los valores de los siguientes atributos:
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.
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:
https://sandbox.viafirma.com/documents/api/v3/documents/download/signed/{messageCode}
Resuesta esperada:
{
"link": "temporal link for downloading",
"md5": "signed-file hash",
"fileName": "filename",
"expires": "timestamp in miliseconds format"
}