Uso de formularios desde API

Última revisión: 04 Febrero 2022

Si tu proceso de firma cuenta con un formulario y necesitas que parte de dicho formulario sea completada por el usuario final, y la otra parte la completas tú desde API, debes hacer uso del atributo "formDisabled" : true.

Con este atributo a true el usuario final SOLO podrá completar aquellos campos del formulario que estén vacío.

• formDisabled: true = el usuario final solo podrá completar los campos de formulario que estén vacíos
• formDisabled: false = el usuario final podrá completar los campos de formulario que estén vacíos y además podrá editar los que ya vengan informados desde el API

Este atributo siempre debe usarse junto al atributo formRequired: true, que sirve para mostrar el formulario como paso previo a la firma.

"document" : {
    "formRequired" : true,
    "formDisabled" : true
 }

También debes saber:

• el formulario NO se puede diseñar desde API
• el formulario deber haber sido diseñado previametne en tu plantilla,
• los ítems del formulario los puedes referencias de dos formas: como un array de ítems dentro del objeto "document" o bien como un array de metadata en las propiedades del message.
• no es necesario incluir en el array todos los ítems del formulario, puedes incluir solo los ítems a los que quieras agregarle un valor, los que nos incluyas se pintarán en el formulario acorde al diseño que hayas hecho desde tu plantilla pero sin valor, a menos que en el diseño del formulario hayas configurado para dichos ítems un valor por defecto.

Ejemplo de uso

En el siguiente ejemplo se dejan vacío los campos SIGNER_01_MAIL y SIGNER_02_MAIL, y serán los únicos que el usuario final podrá completar. Los otros los verá deshabilitados.

{
  "groupCode" : "viafirma",
  "externalCode" : "testExternal_00",
  "workflow" : {
    "type" : "WEB"
  },
  "notification" : {
    "text" : "TEST Firma web con formulario mixto",
    "detail" : "el usuario solo completa los campos vacíos"
  },
  "document" : {
    "templateCode" : "test_form_mixto",
    "readRequired" : false,
    "watermarkText" : "Borrador",
    "formRequired" : true,
    "formDisabled" : true
  },
  "metadataList" : [{
    "key" : "SIGNER_01_NAME",
    "value" : "John Doe"
  },{
    "key" : "SIGNER_01_MAIL",
    "value" : ""
  },{
    "key" : "SIGNER_02_NAME",
    "value" : "Sara Conor"
  },{
    "key" : "SIGNER_02_MAIL",
    "value" : ""
  }]
}

Poniendo "formDisabled" : false, el usuario podrá completar los vacíos e incluso podrá editar los campos que ya vinieran informados.

En este ejemplo el usuario solo podrá completar los campos que no fueron informados con valor desde el API:

En este vídeo te mostramos cómo usarlo:

https://drive.google.com/file/d/1CoB3Sl7izxmbNvLrTIpKd0rIMY8C8rGa/view?usp=sharing

Uso de formularios en los SETS de documentos desde el API

En los documentos con más de un firmante que tienen un formulario asociado, este formulario debe asignarse a uno de los firmante mediantes el atributo formRecipientKey.

Es importante indicar que en las solicitudes, los firmantes deben tener un orden y el firmante asociado al formulario debe ser el primero en el orden.

{
  "groupCode" : "<here_your_groupCode>",
  "title" :     "<here_your_title>",
  "description" : "<here_your_description>",
  "recipients": [
    {
      "key": "signer01",
      "phone": "<here_signer01_mobile_with_prefix>",
      "mail": "<here_signer01_email>",
      "name": "<here_signer01_name>",
      "order": "1",
      "id": "<here_signer01_id>"
    },{
      "key": "signer02",
      "phone": "<here_signer01_mobile_with_prefix>",
      "mail": "<here_signer02_email>",
      "name": "<here_signer02_name>",
      "order": "2",
      "id": "<here_signer02_id>"
    }
  ],
  "customization": {
    "requestMailSubject": "Contrato listo para firmar",
    "requestMailBody": "Hola {{recipient.name}}. <br /><br />Ya puedes revisar y firmar el contrato. Haz click en el siguiente enlace y sigue las instrucciones.",
    "requestSmsBody": "En el siguiente link puedes revisar y firmar el contrato"
  },
  "messages" : [{
      "document" : {
      "templateCode" : "<templateCode_1>",
      "formRequired" : true,
      "formRecipientKey": "signer01"
    }
  }]
}