Using forms from API

Latest update: November 13th, 2020

If your signing process has a form and you need part of the form to be completed by the end user, and the other part to be completed by you via API, you must use the attribute "formDisabled" : true.

With this attribute set to true the end user will ONLY be able to complete those fields of the form that are empty.

• formDisabled: true = This attribute true allows the end user to fill in ONLY those fields of the form that are empty.
• formDisabled: false = the end user will be able to complete the fields that are empty and also edit those that are already informed from the API.

This attribute must always be used alongside the attribute formRequired: true, which is used to display the form as a step prior to signature.

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

Bear in mind:

• The form CANNOT be designed from the API
• the form has to be pre-designed in your template,
• the form items can be referenced in two ways: as an array of items inside the "document" object or as an array of metadata in the message properties.
• it is not required to include all the items of the form in the array , you can include only the items to which you wish to add a value, those that you include will be added to the form according to your template design but without value, unless in the form design you have configured for those items a default value.

Example of use

The following example leaves the SIGNER_01_MAIL and SIGNER_02_MAIL fields empty, and these are the only ones that the end user will be able to fill in. The others will be disabled.

{
  "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" : ""
  }]
}

By setting formDisabled : false, the user will be able to fill in the gaps and even edit the fields that were already filled in.

This example will only allow the user to fill in those blanks that were not reported with a value from the API:

In this video we show you how to use it:

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

Using forms from API in sets

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"
    }
  }]
}