Viafirma Documents

NOTIFICATION: configuración y uso

Revisión: 23-enero-2019

En esta guía te explicamos todas las posibilidades para configurar y usar las notificaciones en viafirma documents. Las notificaciones te servirán para los procesos de firma APP y WEB, ayundándote de notificaciones PUSH, Email y SMS para hacer llegar a tus usuarios los documentos que deben ser firmados.

Su estructura básica es como la siguiente:

"notification": {
  "validateCode": "string",
  "text": "string",
  "detail": "string",
  "notificationType": "string",
  "retryTime": 0,
  "sharedLink": {},
  "customization": {},
  "metadata": [],
  "devices": []
}
PARAM TYPE REQUIRED DESC
validateCode string False Podrás proteger la lectura del documento con un código de validación definido en la solicitud del proceso. Esta protección es útil cuando se hacen uso de dispositivos móviles que están expuestos al público.
text string True Título de la notificación push enviada al dispositivo móvil. También se usa para el título del elemento de la bandeja de nuevos documentos recibidos.
detail string True Título de la notificación push enviada al dispositivo móvil. También se usa para la descripción del elemento de la bandeja de nuevos documentos recibidos.
notificationType string True Podrás usar los siguientes valores: PUSH_IOS,PUSH_ANDROID,MAIL,SMS y MAIL_SMS.
retryTime number False Número de días en los que se enviará la notificación de forma automática hasta que el documento finalice o expire.

Sharedlink

Se usa para procesos de firma WEB y PRESENTIAL.

  "sharedLink": {
    "appCode": "string",
    "email": "string",
    "subject": "string",
    "phone": "string"
  }
PARAM TYPE REQUIRED DESC
appCode string False En procesos de firma WEB es opcional, y si se usa indica el código de la app de viafirma que se abrirá por protocolo, desde la página de firma web, para que el usuario complete el proceso. En caso de procesos de firma con Wacom, este valor indicará el nombre de la app encargada de recoger la firma desde el dispositivo externo de Wacom.
email string False Sólo se usa en procesos de firma WEB con notificationType=MAIL y notificationType=MAIL_SMS para informar la cuenta de email a la que se enviará la notificación.
subject string False Sólo se usa en procesos de firma WEB con notificationType=MAIL y notificationType=MAIL_SMS para informar el asunto del email. No es necesario informar este atributo en caso de usarse customization.requestMailSubject
phone string False Sólo se usa para procesos de firma WEB con notificationType=SMS y notificationType=MAIL_SMS para notificar vía SMS al destinatario. Se debe usar con prefijo de país, por ejemplo +34600600600

Customization

Se usa para procesos de firma WEB y PRESENTIAL.

    "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",
    "callbackMailReminderBody": "string",
    "callbackMailReminderSubject": "string",
    "successMessage": "string"
  }
PARAM TYPE REQUIRED DESC
mailFrom string False Si se define en la plantilla NO es necesario informarlo en la solicitud del proceso. Se usa para definir el remitente del email.
smsFrom string False Si se define en la plantilla NO es necesario informarlo en la solicitud del proceso. Se usa para definir el remitente del SMS (máximo 10 caracteres).
requestMailSubject string False Si se define en la plantilla NO es necesario informarlo en la solicitud del proceso. Se usa para el subject del correo de notificación para Nueva solicitud de firma.
requestSmsBody string False Si se define en la plantilla NO es necesario informarlo en la solicitud del proceso. Se usa para el contenido del SMS previo al shortURL, por ejemplo, Haga click en el siguiente link para firmar su nuevo contrato.
callbackMailSuccessSubject string False Si se define en la plantilla NO es necesario informarlo en la solicitud del proceso. Se usa para definir el asunto del email remitido cuando el proceso ha finalizado correctamente.
callbackMailSuccessBody string False Si se define en la plantilla NO es necesario informarlo en la solicitud del proceso. Se usa para definir el cuerpo del email remitido cuando el proceso ha finalizado correctamente.
callbackMailExpiredSubject string False Si se define en la plantilla NO es necesario informarlo en la solicitud del proceso. Se usa para definir el asunto del email remitido cuando el proceso ha caducado.
callbackMailExpiredBody string False Si se define en la plantilla NO es necesario informarlo en la solicitud del proceso. Se usa para definir el cuerpo del email remitido cuando el proceso ha caducado
callbackMailWaitingCheckSubject string False Si se define en la plantilla NO es necesario informarlo en la solicitud del proceso. Se usa para definir el asunto del email remitido cuando el proceso está en espera de una aprobación manual.
callbackMailWaitingCheckBody string False Si se define en la plantilla NO es necesario informarlo en la solicitud del proceso. Se usa para definir el cuerpo del email remitido cuando el proceso está en espera de una aprobación manual.
callbackMailRejectedSubject string False Si se define en la plantilla NO es necesario informarlo en la solicitud del proceso. Se usa para definir el asunto del email remitido cuando el proceso ha sido rechazado por el usuario.
callbackMailRejectedBody string False Si se define en la plantilla NO es necesario informarlo en la solicitud del proceso. Se usa para definir el cuerpo del email remitido cuando el proceso ha sido rechazado por el usuario.
callbackMailErrorSubject string False Si se define en la plantilla NO es necesario informarlo en la solicitud del proceso. Se usa para definir el asunto del email remitido cuando se ha producido un error en el proceso.
callbackMailErrorBody string False Si se define en la plantilla NO es necesario informarlo en la solicitud del proceso. Se usa para definir el cuerpo del email remitido cuando se ha producido un error en el proceso.
callbackMailReminderSubject string False Si se define en la plantilla NO es necesario informarlo en la solicitud del proceso. Se usa para definir el asunto del email remitido como recordatorio de documento pendiente de firma.
callbackMailReminderBody string False Si se define en la plantilla NO es necesario informarlo en la solicitud del proceso. Se usa para definir el cuerpo del email remitido como recordatorio de documento pendiente de firma
successMessage string False Si se define en la plantilla NO es necesario informarlo en la solicitud del proceso. Se usa para definir el mensaje que se mostrará en pantalla cuando el usuario finalice con la firma. Sólo aplica en procesos de firma WEB. En caso de no usar este atributo se mostrará un mensaje estándar definido en las hojas de estilos asociadas al grupo propietario del proceso.

Metadata

Podrás enviar en tu solicitud una lista de metadatas para usarlas en políticas de firma cuando éstas han sido configuradas con variables dinámicas. También podrás usar metadata que necesitarás en un futuro para explotar los datos del proceso asociado a la firma aunque esta metadata no se use en ningún elemento de configuración: documento, formulario, notificaciones o políticas.

"metadata": [
    {
      "key": "string",
      "value": "string"
    }
  ]

Devices

Sólo para procesos de firma tipo APP debes informar a qué dispositivo/usuario se enviará el documento.

"devices": [
    {
      "appCode": "string",
      "code": "string",
      "userCode": "string"
    }
  ]
PARAM TYPE REQUIRED DESC
devices.appCode string True Identificador de la app a la que se enviará el proceso de firma. El identificador de la app se configura en el Panel de Control > Aplicaciones. Por ejemplo: com.viafirma.documents. Dado que viafirma permite apps custom para distribución privada, este valor podrá tomar tantos valores como apps estén dadas de alta en el sistema, por ejemplo com.viafirma.documents.acme.
devices.code string True Identificador del dispositivo al que se desea enviar el proceso de firma. Dado que el sistema permite permite hacer uso de distintos dispositivos por un mismo usuario de forma concurrente, el código de dispositivo podrá ser igual al código de usuario o distinto en función de la configuración habilitada. En concreto: si se permiten sesiones concurrentes, el devices.appCode y el devices.userCode podrán ser distintos; por ejemplo: appCode = ipad03 y userCode = jhon.doe@acme.com. En caso no estar permitidas las sesiones concurrentes, ambos atributos siempre serán iguales. Es decir, devices.appCode siempre será igual al devices.userCode. Para obtener la lista de dispositivos de un usuario podrás usar el servicio GET /v3/devices/user/{userCode}.
devices.userCode string True Identificador del usuario, por ejemplo jhon.doe@acme.com