Callback de respuesta automática

Última revisión: 07-Junio-2022

Viafirma ofrece varios mecanismos de respuesta automática para los SETS que te contamos a continuación.

  • callbackURL
  • callbackURLAuthorization
  • callbackMails
  • callbackRedirectURL
  • callbackRedirectURLTargetWindow

CALLBACK URL

A la hora de crear un nuevo set, 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.

Por defecto, el POST se hace con un parámetro en la request llamado set, y que contiene en formato string el JSON que representa al objeto devuelto por el servicio GET /v3/summary/{setCode}. Se puede indicar un nuevo tipo de llamada indicando el parámetro callbackType en el json del set con valor JSON, en este caso el json del set va en el cuerpo de la petición en lugar de en el párametro.

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

  • RESPONSED: solicitud de firma finalizada.
  • REJECTED: solicitud de firma rechazada (por el usuario final o por un administrador).
  • ERROR: solicitud de firma no finalizada por algún error que se detalla junto al estado.
  • EXPIRED: solicitud de firma caducada.

Aparte de avisar en los estados finales, avisará cada vez que finalice alguno de los firmantes.

Uso del Callback URL

A través del API podrás informar la URL de respuesta en el atributo set.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 set.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",
  "callbackURL" : "https://sandbox.viafirma.com/documents/api/v3/set/mock/callbackForm",
  "callbackAuthorization" : "Basic Y3ZpbGxhcjoxMjM0NQ==",
  "callbackType": "JSON",
  "recipients": [
    {
      "key": "recipientKey",
      "mail": "[email protected]",
      "name": "XXX"
    }
  ],
  "customization": {
    "requestMailSubject": "Sample Landing Page for signing new contracts",
    "requestMailBody": "Sample Landing Page for signing new contracts"
  },
  "messages" : [{
    "notification" : {
      "text" : "Título del horario",
      "detail" : "Descripción del horario"
    },
    "document" : {
      "templateCode" : "myTemplateCode"
    }
  }]
}

Nota: a partir de la v3.7.41 puedes hacer uso de los siguientes servicios MOCK para simular un callbackURL con respuesta 200 OK durante tus pruebas:

Callback por defecto:
https://sandbox.viafirma.com/documents/api/v3/set/mock/callbackForm

Para "callbackType": "JSON" puedes usar este servicio mock:
https://sandbox.viafirma.com/documents/api/v3/set/mock/callbackJSON

El JSON que enviamos a la URL indicada en callbackURL tendrá la siguiente estructura:

{
  "code": "string",
  "title": "string",
  "description": "string",
  "status": "string",
  "links": [
    {
      "key": "string",
      "messageCode": "string",
      "link": "string",
      "token": "string",
      "status": "string",
      "phone": "string",
      "mail": "string",
      "name": "string",
      "userCode": "string"
    }
  ],
  "externalCode": "string",
  "externalStatus": "string",
  "groupCode": "string",
  "commentReject": "string",
  "creationDate": "2023-09-07T09:22:54.675Z",
  "updateDate": "2023-09-07T09:22:54.675Z",
  "expirationDate": "2023-09-07T09:22:54.675Z",
  "userName": "string",
  "groupTitle": "string",
  "messages": [
    {
      ....
    }
  ]
}

donde es importante aclarar los diferentes estados que se reciben en el JSON:

Estado del SET puede ser (setStatus):

  • RESPONSED: solicitud de firma finalizada correctamente.
  • REJECTED: solicitud de firma rechazada (por el usuario final o por un administrador).
  • ERROR: solicitud de firma no finalizada por algún error que se detalla junto al estado.
  • EXPIRED: solicitud de firma caducada.
  • RECEIVED: solicitud de firma recibida en espera de ser finalizada.

Estado de cada uno de los firmantes que se reciben en el objeto "links" puede ser (recipientStatus):

  • WAITING: El firmante está a la espera de recibir notificación (no es su turno).
  • PENDING: El firmante está pendiente de firmar
  • RECEIVED: El firmante ha finalizado su parte.

Estado de los documentos a nivel individual puede ser (messageStatus):

  • RESPONSED: documento finalizado correctamente.
  • REJECTED: documento rechazado (por el usuario final o por un administrador).
  • ERROR: documento no finalizado por algún error que se detalla junto al estado.
  • EXPIRED: documento caducado.
  • WAITING: documento en espera de ser finalizado.
  • WAITING_CLIENT_SIGNATURE: documento en espera de ser firmado por el usuario.
  • WAITING_CHECK: documento en espera de aprobación

Cómo procesar una respuesta

Habrá varios tipos de procesamiento de respuestas en función del tipo de callback que se haya indicado en la solicitud.

Tipo por defecto (No se indica el atributo callbackType)

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 "set" 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 set incluido en la request. A continuación un ejemplo de servlet en java:

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

callbackType indicado con valor 'JSON'

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 incluido en el body de 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 body de la request. A continuación un ejemplo de servlet en java:

Ejemplo:
private void doService(HttpServletRequest req, HttpServletResponse resp) {
        try {
            String json  = IOUtils.toString(req.getReader());
            //check set status or download documents
        } catch (Exception e) {
            log.log(Level.SEVERE,"Error parsing message JSON.",e);
        }
}

Enviar una notificación de callback asociada a un SET

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

PUT /v3/set/resend/callback

SetCallbackUrl {
  setCode (string),
  url (string, optional),
  authorization (string, optional)
}

CALLBACK MAIL

El comportamiento por defecto en los sets es que se envía una notificación automáticamente a cada uno de los firmantes definidos en la solicitud salvo que se indique el atributo callbackType a NONE. Los valores permitidos para callbackType son MAIL, SMS, MAIL_SMS y NONE. A la hora de crear un nuevo set, también se puede hacer uso del atributo callbackMails, que te permitirá incluir una o varias direcciones de email distintas a las informadas en la definición de firmantes 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).
  • ERROR: proceso de firma no finalizado por algún error que se detalla junto al estado.
  • EXPIRED: proceso de firma caducado.
Ejemplo:
{
  "groupCode" : "myGroupCode",
  "callbackURL" : "https://mysystem.com/responseSigned/",
  "callbackAuthorization" : "Basic Y3ZpbGxhcjoxMjM0NQ==",
  "callbackMails": "[email protected]",
  "callbackType": "JSON",
  "recipients": [
    {
      "key": "recipientKey",
      "mail": "[email protected]",
      "name": "XXX",
      "callbackType": "NONE"
    }
  ],
  "customization": {
    "requestMailSubject": "Sample Landing Page for signing new contracts",
    "requestMailBody": "Sample Landing Page for signing new contracts"
  },
  "messages" : [{
    "notification" : {
      "text" : "Título del horario",
      "detail" : "Descripción del horario"
    },
    "document" : {
      "templateCode" : "myTemplateCode"
    }
  }]
}

Personalización del callback basado en MAIL

Cuando configures callbacks basados en MAIL o SMS se enviarán textos por defecto configurados en el backend de Viafirma. Si necesitas personalizar estos contenidos podrás hacerlo directamente en el payload de tu request.

Para ello debes incluir el objeto "customization" con las propiedades asociadas a este tipo de callback, tal y como te mostramos a continuación:

"customization": {
      "callbackMailSuccessSubject": "string",
      "callbackMailSuccessBody": "string",
      "callbackMailExpiredSubject": "string",
      "callbackMailExpiredBody": "string",
      "callbackMailWaitingCheckSubject": "string",
      "callbackMailWaitingCheckBody": "string",
      "callbackMailRejectedSubject": "string",
      "callbackMailRejectedBody": "string",
      "callbackMailErrorSubject": "string",
      "callbackMailErrorBody": "string",
      "callbackMailReminderBody": "string",
      "callbackMailReminderSubject": "string"
    }

Ejemplo:

{
  "groupCode" : "myGroupCode",
  "callbackURL" : "https://sandbox.viafirma.com/documents/api/v3/set/mock/callbackForm",
  "callbackMails": "[email protected]",
  "recipients": [
    {
      "key": "recipientKey",
      "mail": "[email protected]",
      "callbackType": "MAIL"
    }
  ],
  "customization": {
    "callbackMailSuccessSubject": "Contrato firmado",
    "callbackMailSuccessBody": "En el siguiente link puedes revisar y descargar tu contrato firmado.",
  },
  "messages" : [{
    "document" : {
      "templateCode" : "myTemplateCode"
    }
  }]
}

Callback Redirect

También tienes dos 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.

results matching ""

    No results matching ""