Callback de respuesta automática

Última revisión: 24-enero-2024

Desde Viafirma ofrecemos varios mecanismos de respuesta automática y redireccionamiento que te contamos a continuación:

  • callbackURL
  • callbackMails
  • callbackPhones
  • callbackRedirectURL
  • callbackRedirectURLTargetWindow
  • callbackURLAuthorization
  • callbackProcessMessage
  • callbackCheckListMails

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 o X-Api-Key con uno de los siguientes formatos:

  • Basic {your_bearer_token}
  • X-Api-Key:{your_token}

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.");
    }
}

Cómo consultar por estado y realizar un reenvío

A través de la capa de servicios rest, podrás consultar el estado del proceso de callbackUrl ejecutado al llegar a un estado final el proceso de firma. Para ello, vamos a utilizar el siguiente servicio:

GET /v3/notifications/group/{groupCode}/type/CALLBACK/status/{status}

Donde se puede definir las siguientes variables:

  • groupCode: código de grupo
  • status: estado sobre el que quiere hacer la consulta (SENT, RESENT o ERROR)

En ocasiones, el proceso de callbackUrl puede establecerse en estado ERROR debido a diferentes casuísticas. Viafirma Documents no reenvía automáticamente un callbackUrl, sino que debe hacerse a través del frontal web si dispones de acceso o a través del siguiente servicio:

PUT /v3/messages/resend/callback

En el body de la petición deberá establecerse el siguiente JSON:

{
  "messageCode": "string",
  "url": "string",
  "authorization": "string"
}

Siendo los valores url y authorization opcionales

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 nosotros. Por defecto, 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"
}
  • callbackMailsBcc: Lista de correos separados por , que recibirán como copia oculta el documento firmado.
{
  "callbackMailsBcc" : "[email protected]"
}
  • callbackMailsCc: Lista de correos separados por , que recibirán como copia el documento firmado.
{
  "callbackMailsBcc" : "[email protected]"
}

Por defecto, los emails notificados en el atributo callbackMails se mandan en copia oculta. Si se desea que aparezca en el "Para", es necesario añadir la propiedad MAIL_BCC a false en la configuración del grupo.

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" : "[email protected]"
}

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)
}

CallbackPhones (mediante SMS)

Al igual que hacemos para un callbackMails, podemos hacerlo mediante SMS haciendo uso del atributo callbackPhones, en el que debes indicar el número o números de teléfono móvil a que avisaremos cuando el proceso haya finalizado. Recuerda que debes usar el prefijo de país. Por ejemplo, +34. Para avisar a varios teléfonos tendrás que separarlos por coma.

"callbackPhones" : "+34666000666"

El texto enviado en este tipo de callback se puede definir y configurar en tus plantillas o bien directamente en la llamada al API, tal y como se configuran los callbacks del tipo EMAIL.

Callback Redirect

También tienes hasta tres posibilidades de redirigir a tu usuario a una página web que nos informes mediante API:

"callbackRedirectURL" : "https://www.google.com"

De esta forma, cuando un proceso de firma web ha finalizado redirigimos al usuario a esa página, cuya URL permite incorporar queries params que te ayuden a aplicar alguna lógica de negocio una vez llegue tu usuario a la página.

CALLBACK Checklist Mails

Si en la solicitud de firma hemos configurado una aprobación, este callback nos sirve para especificar las direcciones de correo de las personas que podrán aprobar la solicitud.

Una aprobación puede ser:

  • Simple
  • Con código
  • Con una firma con certificado digital

Por otra parte, el estado sobre el que se lanza este callback es:

  • WAITING_CHECK: proceso de firma finalizado por el usuario final y pendiente de aprobación por parte de algún usuario del sistema.

Los aprobadores recibirán un correo electrónico donde podrán aprobar o rechazar directamente la solicitud.

Definir los emails en tu plantilla

Puedes especificar las direcciones de correo electrónico de las personas que deseas que aprueben la solicitud desde las opciones de una plantilla. Para ello, accede a los ajustes de la plantilla > Configuración.

Definir los emails vía API

Si prefieres indicar las direcciones de correo electrónico a través de la API, tienes 2 opciones.

Puedes especificar directamente los correos como un string:

"callbackCheckListMails" : "[email protected], [email protected], [email protected]"

O bien, si quieres que sea dinámico y asociarlo a un campo específico del formulario:

"callbackCheckListMails" : "{{emailAprobadores}}"

results matching ""

    No results matching ""