Viafirma Documents

MESSAGE: configuración y uso

Revisión: 14-mayo-2019

En esta guía te explicamos todas las posibilidades configuración y uso para crear un nuevo MESSAGE (POST).

atributos básicos

{
  "groupCode": "string",
  "externalCode": "string",
  "callbackURL": "string",
  "callbackMails": "string",
  "callbackCheckListMails": "string",
  "callbackMailFilename": "string",
  "callbackAuthorization": "string"
}
PARAM TYPE DESC
groupCode string OBLIGATORIO. El grupo determinará comportamiento preconfigurado relativo factores como transferencias automáticas, hojas de estilos, permisos, etc. Es importante que el grupoCode coincida con el grupo con el que pretendes completar tu proceso de negocio. Para más información puedes consultar la documentación del producto para la gestión y configuracion de grupos.
externalCode string OPCIONAL. Recomendado si consumes nuestras APIs y quieres que indexemos el código de petición de tu propio sistema, por ejemplo tu CRM. De esta forma podrás consultar directamente por este atributo en nuestro backend o a través de APIs.
groupCode string OBLIGATORIO. El grupo determinará comportamiento preconfigurado relativo factores como transferencias automáticas, hojas de estilos, permisos, etc. Es importante que el grupoCode coincida con el grupo con el que pretendes completar tu proceso de negocio. Para más información puedes consultar la documentación del producto para la gestión y configuracion de grupos.
callbackURL string OPCIONAL. Si cuentas con un servicio al que podamos invocar por URL aquí podrás definirla. De esta forma viafirma te avisará automáticamente cuando tu proceso haya finalizado. Para más información puedes revisar la documentación sobre el uso de Callbacks.
callbackAuthorization string OPCIONAL. Si la callbackURL a la que se informa cuando el proceso finaliza requiere autenticación debes usar este atributo que se usará en la cabecera authorization. Sólo están soportadas autorizaciones BASIC; Basic [espacio en blanco] password. Ej. Basic Y3ZpbGxhcjoxMjM0NQ==.
callbackMails string OPCIONAL. Aquí podrás informar una cuenta de correo, o varias separadas por coma, a las que informaremos automáticamente cuando tu proceso haya finalizado, pudiendo incluir como anexo el documento firmado y con un mensaje y estilo personalizado. Para más información puedes revisar la documentación sobre el uso de Callbacks.
callbackCheckListMails string OPCIONAL. Si en la configuración de políticas se incluyen aprobaciones podrás informar por email a las personas que deben realizar la aprobación. Puede usar varias direcciones de email separadas por coma.
callbackMailFilename string OPCIONAL. Permite definir el nombre al documento firmado que adjuntamos en los correos remitidos tras finalizar el proceso. Por defecto el nombre del adjunto será asignado por el sistema a partir del messageCode.

Ejemplo:

{
  "groupCode": "acme_group01",
  "externalCode": "9999999999999999",
  "callbackURL": "https://acme.com/response",
  "callbackAuthorization": "Basic Y3ZpbGxhcjoxMjM0NQ==",
  "callbackMails": "jhon.doe@acme.com",
  "callbackCheckListMails": "jhon.doe@acme.com",
  "callbackMailFilename": "contract_ref_AA929.pdf"
}

objetos asociados al MESSAGE

{
  "workflow" : {},
  "notification" : {},
  "document" : {},
  "metadataList" : {},
  "policies" : {}
}
PARAM TYPE DESC
workflow object Workflow Cuando crees un nuevo proceso de firma podrás optar por varios tipo de procesos. Por defecto el flujo predefinido será APP, que consiste en enviar el documento a una app iOS o Android. Más info sobre el objeto Worklfow aquí.
notification object Notification 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. Más info sobre el objeto Notification aquí.
document object Document Con este objeto nos informarás cuál es el documento a firmar, y tendrás varias posibilidades: tu sistema genera el documento (PDF) y lo pasas por referencia (URL o Base64) o bien viafirma construye el documento (PDF) a partir de una plantilla que nos indicas por referencia. Más info sobre el objeto Document aquí.
metadataList Array[Param] Podrás gestionar tu propio mapa de metadatos con varios propósitos, como uso de variables dinámicas en la configuración de políticas y formularios, o bien para la explotación de estos datos por parte de terceros, como un CRM o el sistema de transferencias que recibe los documentos firmados por parte de viafirma.
policies Array[Policy] Con el objeto Policy podrás definir el conjunto de reglas asociadas a las evidencias y firmas electrónicas que se aplicarán sobre el Documento remitido. En el capítulo de Políticas te explicamos su uso.

GET MESSAGE

El objeto MESSAGE reunirá toda la información recopilada por el proceso de firma durante todo su ciclo de vida, por lo que su gestión resultará compleja e innecesaria. En su lugar se recomienda métodos como GET messages/status o GET messages/status/group devolviendo el estado del proceso, y que en cuyo caso, nos determinará el momento de poder descargar el documento firmado.

Si aún así se quiere explorar el objeto message al completo, podrás consumir el siguiente método:

Type Service Format Security
GET /api/v3/messages application/json OAuth 1.0

Ejemplo GET message

GET api/v3/messages/{messageCode}

Obteniendo un JSON acorde al Modelo que podrás revisar en detalle desde nuestra interfaz visual Swagger:

nota: el acceso a swagger requiere login previo en el backend con un usuario registrado y que cuente con el rol "developer", y una vez logado introducir la contraseña "public-key"; https://sandbox.viafirma.com/documents/api-docs

Info de interés

Además del estado actual del proceso, la siguiente información podrá resultarte de interés:

{
  "commentReject": "string",
  "callbackResponse": "string",
  "auditory": [
    {
      "action": "RECEIVED",
      "date": "2018-12-31T09:10:05.277Z",
      "ip": "string",
      "data": "string",
      "detail": "string",
      "geolocation": {
        "accuracy": 0,
        "latitude": 0,
        "longitude": 0,
        "locationData": "string",
        "locationInfo": "string"
      }
    }
  ]
}