Viafirma Documents

DOCUMENT: configuración y uso

Revisión: 23-enero-2019

En esta guía te explicamos todas las posibilidades para trabajar con documentos en viafirma documents.

Con este objeto nos informarás cuál es el documento a firmar, y tendrás varias posibilidades:

  • A.- tu sistema genera el documento (PDF) y lo pasas por referencia (URL o Base64).
  • B.- viafirma construye el documento (PDF) a partir de una plantilla que nos indicas por referencia.
  • C.- reutilizas un documento ya firmado por viafirma para incorporarlo en un nuevo proceso de firma.

A.- Documento basado en Plantilla

Su estructura básica es como la siguiente:

{
    "document": {
    "templateCode": "string"
  }
}
PARAM TYPE REQUIRED DESC
templateCode string True Código de la plantilla previamente configurada en el sistema. Para más información revisa la guía de uso de plantillas.

Ejemplo:

{
    "document": {
    "templateCode": "newContract_policy_v1"
  }
}

nota: recuerda que este objeto document forma parte del message que debes definir para solicitar un NUEVO PROCESO DE FIRMA.

B.- Documento Externo

Si tu sistema ya se encarga de construir el PDF que debes firmar, nos lo puedes enviar por dos mecanismos:

  • base64
  • URL

B.1.- Documento pasado por referencia en Base64

{
    "document": {
    "templateType": "string",
    "templateReference": "string",
    "policyCode" : "string"
  }
}
PARAM TYPE REQUIRED DESC
templateType string False Por defecto este atributo es opcional, y sólo tendrás que informarlo cuando el documento se envía en Base64 o se referencia en una URL, cuyo valor será respectivamente: base64,url.
templateReference string True Sólo se usa para templateType=base64 y url, en cuyo caso su valor será igual al documento codificado en base64 o URL en la que se encuentra el documento respectivamente.
policyCode string False Opcional. Podrás usar un código de plantilla que incluya una política de firma que se aplicará al documento pasado por referencia. Si no usas policyCode tendrás que definir la política de firma manualmente (ver uso de políticas).

Ejemplo:

{
    "document": {
    "templateType": "base64",
    "templateReference": "<....base64....>",
    "policyCode" : "newContract_policy_21"
  }
}

nota: recuerda que este objeto document forma parte del message que debes definir para solicitar un NUEVO PROCESO DE FIRMA.

B.2.- Documento pasado por referencia URL

{
    "document": {
    "templateType": "string",
    "templateReference": "string",
    "policyCode" : "string"
  }
}
PARAM TYPE REQUIRED DESC
templateType string True Podrás usar los siguientes valores: url,base64,pdf,docx.
templateReference string True Sólo se usa para templateType=base64 y url, en cuyo caso su valor será igual al documento codificado en base64 o URL en la que se encuentra el documento respectivamente.
policyCode string False Opcional. Podrás usar un código de plantilla que incluya una política de firma que se aplicará al documento pasado por referencia. Si no usas policyCode tendrás que definir la política de firma manualmente (ver uso de políticas).

Ejemplo:

{
    "document": {
    "templateType": "url",
    "templateReference": "https://www.viafirma.com/myContractdemo.pdf",
    "policyCode" : "newContract_policy_21"
  }
}

nota: recuerda que este objeto document forma parte del message que debes definir para solicitar un NUEVO PROCESO DE FIRMA.

C.- Documento previamente firmado por viafirma

Su estructura básica es como la siguiente:

"document": {
   "templateType" : "message",
   "templateReference" : "[messageCode asociado al documento que deseamos refirmar]",
   "policyCode" : "string"
 }
PARAM TYPE REQUIRED DESC
templateType string True para hacer uso de esta modalidad de reenvío de un documento ya firmado por viafirma debes usar como templateType el valor message.
templateReference string True messageCode asociado al documento que deseamos refirmar.
policyCode string False Opcional. Podrás usar un código de plantilla que incluya una política de firma que se aplicará al documento pasado por referencia. Si no usas policyCode tendrás que definir la política de firma manualmente (ver uso de políticas).

Ejemplo:

"document": {
   "templateType" : "message",
   "templateReference" : "1548281612786R307",
   "policyCode" : "newContract_policy_21"
 }

nota: recuerda que este objeto document forma parte del message que debes definir para solicitar un NUEVO PROCESO DE FIRMA.

Opciones Extendidas

A continuación te mostramos todas las posibilidades de uso, configuración y tratamiento del documento.

"document": {
  "templateCode": "string",
  "templateReference": "string",
  "templateType": "url",
  "formRequired": false,
  "formDisabled": false,
  "items": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "pdfaCompliant": true,
  "font": {
    "name": "string",
    "size": 0
  },
  "policyCode": "string",
  "password": "string",
  "readRequired": false,
  "allowResend": false,
  "deleteSignedDocuments": false,
  "watermarkText": "string"
}
PARAM TYPE REQUIRED DESC
templateCode string False Código de la plantilla previamente configurada en el sistema. Para más información revisa la guía de uso de plantillas.
templateReference string False Sólo se usa para templateType=base64 y url, en cuyo caso su valor será igual al documento codificado en base64 o URL en la que se encuentra el documento respectivamente.
templateType string Fasle Sólo necesario para documentos externos, usado con valores: base64,url.
formRequired boolean False Muestra formulario antes de visualizar el documento. El formulario podrá contener datos necesarios para completar la generación del PDF. Si usas esta opción necesitarás que la plantilla usada templateCodetenga asociado un diseño de formulario.
formDisabled boolean False True para que el usuario NO pueda modificar los datos del formulario que ya vengan informados, sólo podrá completar los que vengan vacíos. Por defecto vale false, es decir, si usas formulario el usuario siempre podrá modificar los datos que ya vengan informados en él.
items list False Podrás settear los valores del formulario haciendo uso de una lista de valores key / value.
pdfaCompliant boolean False Si necesitas que el PDF firmado sea PDF/A Compliant debes activar este atributo y acompañarlo de la fuente utilizada para que podamos incorporarla, para ello debes usar el atributo font.
font boolean False Sólo necesario si activas pdfaCompliant, y deberás informar el nombre de la fuente name y su tamaño size.
policyCode string False Deberá ser igual a un código de plantilla previamente configurada en el sistema y que al menos debe tener configurada una política de firma. Este atributo será útil cuando uses documentos externos, pasados por referencia (base64 o URL), y quieres aplicarle una política previamente diseñada.
password string False Sólo necesario para PDF protegidos con contraseñas.
readRequired boolean False En caso de activarlo el usuario no podrá acceder al panel de acciones hasta que avance todas las páginas del documento.
allowResend boolean False Si activas esta propiedad el proceso de firma puede completarse iniciarse por un usuario y completarse por otro distinto, respetando los valores introducidos en formularios, políticas y evidencias.
deleteSignedDocuments boolean False Si activas esta propiedad el documento se eliminará del sistema de custodia una vez finalizado el proceso.Debes tener precaución al usar esta propiedad y asegurarte que el proceso cuente con alguna configuración de transferencia o callBack automático.
watermarkText string False Puedes indicar la marca de agua deseada en la previsualización documento que debe ser firmado. Por defecto se usa la marca de agua con el texto Preview.

Ejemplo:

"document": {
  "templateCode": "newContract_policy_v1",
  "formRequired": true,
  "formDisabled": true,
  "items": [
    {
      "key": "name",
      "value": "John Doe"
    }
  ],
  "pdfaCompliant": true,
  "font": {
    "name": "Arial",
    "size": 11
  },
  "password": "12345",
  "readRequired": true,
  "allowResend": true,
  "deleteSignedDocuments": false,
  "watermarkText": "Borrador"
}

nota: recuerda que este objeto document forma parte del message que debes definir para solicitar un NUEVO PROCESO DE FIRMA.