Viafirma Documents

Callback de respuesta automática

Última revisión: 02-abril-2019

Viafirma documents ofrece dos mecanismos de respuesta automática: callbackURL y callbackMails.

CALLBACK URL

A la hora de crear un nuevo message, se puede hacer uso del atributo callbackUrl, que permitirá que el proceso haga una llamada POST a la URL informada en dicho atributo cuando llegue a uno de los distintos estados posibles en los que se lanza la respuesta automática.

El POST se hace con un parámetro en la request llamado message, y que contiene en formato string el JSON que representa al objeto devuelto por el servicio GET /v3/messages/{messageCode}.

Los estados posibles sobre los que se lanza el callback son los siguientes:

  • RESPONSED: proceso de firma finalizado.
  • REJECTED: proceso de firma rechazado (por el usuario final o por un administrador).
  • WAITING_CHECK: proceso de firma finalizado por el usuario final y pendiente de aprobación por parte de algún usuario del sistema.
  • ERROR: proceso de firma no finalizado por algún error que se detalla junto al estado.
  • EXPIRED: proceso de firma caducado.

Uso del Callback URL

A través del API podrás informar la URL de respuesta en el atributo message.callbackURL de tu proceso de firma, y si la URL a la que haremos POST está securizada, podrás definir las credenciales haciendo uso del atributo message.callbackAuthorization, que incluiremos en la cabecera de nuestra request, indicando la seguridad BASIC con el siguiente formato:

Basic Y3ZpbGxhcjoxMjM0NQ==

Ejemplo Callback URL

{
  "groupCode" : "myGroupCode",
  "workflow" : {
    "type" : "PRESENTIAL"
  },
  "notification" : {
    "text" : "Sample Landing Page for signing new contracts",
    "detail" : "New Service 001-A"
  },
  "metadataList" : [
    {
      "key" : "myMetadata_01",
      "value" : "myValue_01"
    }
  ],
  "document" : {
    "templateCode" : "myTemplateCode",
    "formRequired" : true,
    "formDisabled" : true
  },
  "callbackURL" : "https://mysystem.com/responseSigned/",
  "callbackAuthorization" : "Basic Y3ZpbGxhcjoxMjM0NQ=="
}

Cómo procesar una respuesta

Al tratarse de un POST a una dirección HTTP, la información contenida en la request podrá procesarse de distintas formas. Por ejemplo, si la URL informada corresponde a un servicio REST, el servicio podrá procesar el string "message" incluido en la request.

Otro ejemplo podría ser que la URL informada corresponda a una URL gestionada por un filter o servlet de java, pudiendo implementar una clase java que procese el parámetro message incluido en la request. A continuación un ejemplo de servlet en java:

Ejemplo:

private void doService(HttpServletRequest req, HttpServletResponse resp) {
    if(req.getParameter("message")!=null){
        try {
            String json = req.getParameter("message");
            //check message status or download document
        } catch (Exception e) {
            log.log(Level.SEVERE,"Error parsing message JSON.",e);
        }
    }else{
        log.log(Level.WARNING,"Empty request received.");
    }
}

CALLBACK MAIL

A la hora de crear un nuevo message, se puede hacer uso del atributo callbackMails, que te permitirá incluir una o varias direcciones de email separadas por coma a las que notificaremos cuando el ciclo de vida del proceso alcance alguno estados posibles en los que se lanza la notificación automática.

Los estados posibles sobre los que se lanza el callback son los siguientes:

  • RESPONSED: proceso de firma finalizado.
  • REJECTED: proceso de firma rechazado (por el usuario final o por un administrador).
  • WAITING_CHECK: proceso de firma finalizado por el usuario final y pendiente de aprobación por parte de algún usuario del sistema.
  • ERROR: proceso de firma no finalizado por algún error que se detalla junto al estado.
  • EXPIRED: proceso de firma caducado.

A diferencia del callbackUrl, los estados asociados a las notificaciones son configurables. Es decir, por defecto podemos notificar a través de email en cada uno de los estados previstos, pero el administrador de un grupo de trabajo podrá decidir qué estados son susceptibles de lanzar notificaciones vía email.

Para ello, el administrador del grupo sólo tendrá que acceder a la configuración específica del grupo y seleccionar los estados deseados.

Otras opciones para el CALLBACK MAIL

El uso del callbackMails permite además el uso de un atributo opcional con la siguiente funcionalidad:

  • callbackMailFilename: por defecto te adjuntaremos en el correo el documento firmado, pero el nombre del documento (pdf) lo elegimos noostros, y siempre usamos el código del proceso. Si quisieras normalizar el nombre del adjunto podrás hacer uso del este atributo para definir el nombre que desees.
{
  "callbackMailFilename" : "mycompany_contract.pdf"
}

Configuración aspecto y contenido del CALLBACK MAIL

Podrás personalizar el aspecto de tus correos así como su contenido, haciendo uso de dos elementos de configuración:

  • Configuración de estilos: email-template.html

El administrador de un grupo de trabajo podrá subir una plantilla de correo que le permitirá definir un estilo personalizado para todas las comunicaciones realizadas por correo electrónico desde Viafirma. No sólo las notificaciones asociadas a un callbackMails, sino a cualquier notificación, por ejemplo, las remitidas a usuarios avisándoles de un nuevo documento pendiente de firma.

Para editar esta plantilla el administrador del grupo podrá acceder a la gestión de estilos:

  • Configuración de contenidos:

Los contenidos de los correos pueden ser personalizados, y podrás hacer uso de contenido dinámico, ayudándote de variables que estén incluidas en tus procesos de firma, por ejemplo, campos de formulario, aportando con ello la personalización adecuada en la comunicación con tus usuarios.

Para todos los posibles estados asociados a notificaciones podrás configurar Asunto y Cuerpo, y podrás hacerlo mediante configuración visual de tu plantilla y mediante configuración vía API.

Configuración notificaciones en tu plantilla

El propietario de la plantilla podrá acceder a su configuración y elegir la opción Notificaciones, donde podrá definir el contenido deseado para cada uno de los estados posibles.

Configuración notificaciones vía API

También puedes definir el contenido de las notificaciones de forma explícita en cada proceso, vía API, haciendo uso del objeto message.customization:

"customization": {
      "mailFrom": "string",
      "smsFrom": "string",
      "requestMailSubject": "string",
      "requestMailBody": "string",
      "requestSmsBody": "string",
      "callbackMailSuccessSubject": "string",
      "callbackMailSuccessBody": "string",
      "callbackMailExpiredSubject": "string",
      "callbackMailExpiredBody": "string",
      "callbackMailWaitingCheckSubject": "string",
      "callbackMailWaitingCheckBody": "string",
      "callbackMailRejectedSubject": "string",
      "callbackMailRejectedBody": "string",
      "callbackMailErrorSubject": "string",
      "callbackMailErrorBody": "string",
      "callbackSmsReminderBody": "string",
      "callbackMailReminderBody": "string",
      "callbackMailReminderSubject": "string",
      "successMessage": "string"
    }

Ejemplo:

{
  "groupCode" : "myGroupCode",
  "workflow" : {
    "type" : "PRESENTIAL"
  },
  "notification" : {
    "text" : "Sample Landing Page for signing new contracts",
    "detail" : "New Service 001-A"
  },
  "customization": {
        "mailFrom": "string",
        "requestMailSubject": "My Company: new contract for signing",
        "requestMailBody": "Dear Customer y&nbsp;<span style=\"font-size: 10pt;\">Follow the link for signing your...:&nbsp;</span>",
  },
  "metadataList" : [
    {
      "key" : "myMetadata_01",
      "value" : "myValue_01"
    }
  ],
  "document" : {
    "templateCode" : "myTemplateCode",
    "formRequired" : true,
    "formDisabled" : true
  },
  "callbackMails" : "sales@mycompany.com"
}

Ajustes y automatizaciones del CALLBACK MAIL

A nivel de plantilla podrás ajustar la configuración de las notificaciones, para ello el propietario de la plantilla podrá acceder a su configuración y elegir la opción Configuración.

En esta sección podrá definir distintas opciones que te ayudarán a automatizar notificaciones tal y como te explicamos a continuación:

Reenvío manual del CALLBACK

Podrás reenviar el callback asociado a tu proceso, tanto si se trata de un callbackURL como si se trata de un callbackMails, y podrás hacerlo de dos formas:

desde el detalle del proceso

Accediendo al panel de gestión de Viafirma Documents, y localizando tu proceso, podrás encontrar el detalle de las notificaciones realizadas, pudiendo acceder al detalle individual de cada una de ellas. Al hacerlo encontrarás la opción para el reenvío, permitiéndote incluso modificar algún dato antes del reintento.

a través de API

Tienes disponible el siguiente método PUT que te permitirá reintentar el callbackURL de tu proceso.

PUT /v3/messages/resend/callback
CallbackUrl {
messageCode (string),
url (string, optional),
authorization (string, optional)
}