Edatalia

firmar.online ·Tutoriales

Manual para la generación de Formularios – WebForms

··10 min de lectura

Introducción

Mediante la integración del complemento WebForm podrás cumplimentar formularios web antes de firmarlos.

WebForm es una librería que permite a los usuarios transformar datos en formato JSON en documentos HTML interactivos, es decir en formularios web, para posteriormente, convertir esos archivos HTML en documentos PDF listos para su distribución. Esta librería viene integrada en los siguientes productos de edatalia:

  • SIGNply Corporate
  • API firmar.online (para incluir un formulario en una llamada desde la API).
  • app.firmar.online Opción Plantillas, (generación y edición de formularios PDF).

Características

  1. Conversión de JSON a HTML: Importa datos en formato JSON y transforma automáticamente estos datos en páginas HTML interactivas, (formularios web).
  2. Personalización del archivo JSON: La aplicación permite al usuario añadir estilos, imágenes, separadores, así como todo tipo de inputs y bloques de tipo texto.
  3. Generación de PDF de alta calidad: Con un clic, los usuarios pueden convertir sus documentos HTML en archivos PDF listos para firmar.
  4. Firma Digital Segura: La característica de firma digital permite a los usuarios firmar ese documento PDF generado.
  5. Integración de JSON en el proceso de firma: A través de nuestros servicios API REST, se puede realizar una integración nativa.

Integración de webforms en la API

La utilización de los webforms se realiza mediante un JSON que va a indicar al proceso de firma como tiene que ser esta página HTML que se muestra al firmante. En el punto 4 de este documento, puedes consultar los campos válidos que se pueden utilizar así como su función.

En la url https://restapi.firmar.online/index.html tienes una descripción completa del servicio con los métodos de creación de sobres. A grandes rasgos, son métodos de tipo POST que envían información sobre el proceso de firma. En concreto, se puede observar un ejemplo en el método /PSC/v40/DocumentSet, agrupando la información en tres grandes apartados:

  • Información de tipo general. En el que se incluyen datos como la caducidad, el método de envío, acceso y recordatorio.
  • Información de los firmantes. Referentes a quien es la persona a la que se va enviar el documento a firmar.
  • Información sobre los documentos a firmar. En este bloque es donde se ubicaría el json que queremos envíar. Para ello se utiliza el schema Form

En el enlace:

https://documenter.getpostman.com/view/9780542/TVmHDetH#9de39ffb-40d7-4ab4-9223-39921bc29244
Está disponible una colección de postman con ejemplos de webforms para facilitar la comprensión e integración de la misma. Se encuentra agrupada en la carpeta “Formularios web”

Estructura del Formulario Según Caso de Uso

⚠️ IMPORTANTE: La estructura del formulario variará dependiendo de para qué se vaya a utilizar:

Para SIGNply Corporate

La estructura NO deberá contener ni el name ni el form, en cambio SÍ deberá contener el widget.

Ejemplo con estructura simple:

{  "widget": {    ...  },  "generalStyles": {    ...  },  "pages": [    {      "items": [        ...      ]    }  ]}

Para realizar una llamada desde la API

La estructura del formulario NO deberá contener ni el name ni el form ni el widget, puesto que ya vienen en la llamada API.

Ejemplo de llamada API con formulario webform incluido:

{
    "documentSetName": "NOMBRE DEL DOCUMENTO",
    "sendermail": "EMAIL DEL REMITENTE",   "Sendername": "NOMBRE DEL REMITENTE",
    "expirationDaysTimeout": 1,
    "recipient": {  "name": {{RecipientName_1}},   "email": {{RecipientEMail_1}},   "cardId": {{RecipientCardId_1}},   "phoneNumber": {{RecipientPhoneNumber_1}},
        "actionType": 30,         "authType": 10,

        "widget": {
            "customtext": [ {"text": "Firmado digitalmente", "fontSize": 3 },  { "text": "Fecha: ##TIMESTAMP##", "fontSize": 2 } ],
            "page": 99,   "x": 50,  "y": 10,   "width": 100, "height": 50         }
    },
    "document": {
        "name": "DOCUMENTO - {{$isoTimestamp}}",
        "formValues":  [
             {"id": "Solicitante_Nombre", "value": "VALOR POR DEFECTO" }          
            ],
"form": {

    "generalStyles": {...},
    "pages": [
    {
        "items": [
         ...
        ]       
    }    
    ]
    }
    }
}

Para generar una plantilla en app.firmar.online

La estructura deberá tener el name y el Form, pero NO el widget.

Ejemplo con estructura simple:

{  "name": "Nombre de la Plantilla",  "Form": {    "GeneralStyles": {      ...    },    "Pages": [      {        "Items": [          ...        ]      }    ],    "DataSets": null  }}

Configuración del formulario web

Explicación de cada campo

«pages»: Define el cuerpo del formulario, separándolo por páginas.

Ejemplo:

"pages": [
  {
    "items": [
      ...
    ]
  }
]

«generalStyles»: Son los estilos por defecto que tendrá toda la página. Si queremos modificar algún elemento en concreto para ello tendremos que darle propiedades a ese elemento, con la propiedad css.
Por motivos de seguridad en la generación de formularios web, las propiedades CSS permitidas serán las siguientes:

  • height
  • maxWidth
  • minWidth
  • align
  • float
  • marginTop
  • marginBottom
  • border
  • fontFamily
  • fontSize
  • color
  • backgroundColor
  • textAlign
  • padding
  • fontWeight
  • textDecoration

“Items”: Cada elemento que contiene el formulario, en cada uno se define el tipo (“type”) y sus propiedades. 

Tipos de elementos (type)

image

Generar un elemento de tipo imagen.

Ejemplo:

{  "type": "image",  "id": "logo",  "src": "data:image/png;base64,iVBORw0KGgoAAAANSU",  "css": { "maxWidth": "50%" }}

headerText

Texto de cabecera o título.

Ejemplo:

{  "type": "headerText",  "label": "Ejemplo contrato de arrendamiento ",  "css": { "color": "#0b66a3" },  "id": "titulo_documento"}

paragraphText

Párrafo de texto normal.

Ejemplo:

{  "type": "paragraphText",  "label": "Descripción del documento.",  "id": "descripcion"}

continuousText

Texto continuo (sin salto de línea).

textField

Campo para entrada de texto.

Ejemplo:

{  "type": "textField",  "label": "Nombre completo: ",  "id": "nombre_propietario",  "css": { "minWidth": "100px" },  "editable": false,  "value": "Fermín Martín"}

emailField

Campo de entrada para email.

Ejemplo:

{  "type": "emailField",  "label": " Correo: ",  "id": "correo_propietario",  "css": { "minWidth": "100px", "marginTop": "1rem" },  "editable": false,  "value": "ejemplo@gmail.com"}

numberField

Campo de entrada para numero entero.

dateField

Campo de entrada para una fecha.

Ejemplo:

{  "type": "dateField",  "id": "incio_fecha",  "css": { "minWidth": "100px" },  "today": true,  "editable": false}

radioButton

Seleccionar entre varias opciones, definidas en la propiedad options.

Ejemplo:

{  "type": "radioButton",  "label": "¿Tiene mascotas?",  "css": { "marginTop": "1rem", "marginBottom": "1rem" },  "options": [    { "value": "Si", "text": "SI" },    { "value": "No", "text": "NO" }  ],  "id": "mascotas",  "required": true}

lineBreak

Genera un salto de línea invisible.

Ejemplo:

{  "type": "lineBreak"}

barBreak

Genera un salto de línea, marcado por una línea horizontal visible.

pageBreak

Divide páginas del pdf.

Ejemplo:

{  "type": "pageBreak"}

table

Elemento para crear tablas, va acompañado de la propiedad cells donde se le indican las filas y columnas.

Ejemplo:

{  "type": "table",  "cells": {    "th": ["Encabezado 1", "Encabezado 2", "Encabezado 3"],    "tr": [      { "td": ["Dato 1", "Dato 2", "Dato 3"] },      { "td": ["Dato 4", "Dato 5", "Dato 6"] }    ]  },  "css": { "border": "black 3px solid" }}

dropDownField

Genera un elemento de tipo select o dropdown, donde se le añade un dataSet para obtener la lista de valores.

Propiedades de los elementos

label

El texto que recibe ese elemento.

Ejemplo:

"label": "Selecciona una de las opciones:"

id

El identificador que recibe ese elemento.

Ejemplo:

"id": "nombre_propietario"

value

El valor que quiera tener por defecto el elemento “input”.

Ejemplo:

"value": "Fermín Martín"

editable

Booleano para elegir si un elemento “input” es editable o no. (true o false), por defecto su valor es true.

Ejemplo:

"editable": false

required

Booleano para elegir si un elemento “input” es obligatorio o no para poder crear el pdf. (true o false), por defecto su valor es false.

Ejemplo:

{  "type": "textField",  "label": "Nombre completo: ",  "id": "nombre_inquilino",  "css": { "minWidth": "100px" },  "required": true}

visible

Booleano para elegir si un elemento “input” es visible o no. (true o false), por defecto su valor es true.

Ejemplo:

{  "type": "radioButton",  "label": "Tamaño mascota:",  "css": { "marginTop": "1rem", "marginBottom": "1rem" },  "options": [    { "value": "Peq", "text": "Pequeño" },    { "value": "MeGr", "text": "Mediano/grande" }  ],  "id": "tamaño_mascota",  "visible": false,  "required": true}

src

Indica ubicación de un documento externo, en este caso se debe añadir a una imagen en formato b64.

Ejemplo:

"src": "data:image/png;base64,iVBORw0KGgoAAAANSU"

css

Propiedad que da estilo a los elementos. Por motivos de seguridad, las propiedades CSS permitidas serán las siguientes:

  • height
  • maxWidth
  • minWidth
  • align
  • float
  • marginTop
  • marginBottom
  • border
  • fontFamily
  • fontSize
  • color
  • backgroundColor
  • textAlign
  • padding
  • fontWeight
  • textDecoration

Ejemplo:

"css": { "fontFamily": "Arial", "fontSize": "16px" }

Ejemplo con múltiples propiedades:

"css": { "color": "#0b66a3", "marginTop": "3rem" }

options

Si el elemento es de tipo radioButton, dentro de esta propiedad se añadirán las opciones que queremos que salgan como radio button y su respectivo texto (“value”).

Ejemplo:

"options": [  { "value": "Opción1", "checked": "checked" },  { "value": "Opción2" },  { "value": "Opción3" }]

La propiedad de “checked” sirve para seleccionar una de las opciones por defecto.

Ejemplo real:

"options": [  { "value": "Si", "text": "SI" },  { "value": "No", "text": "NO" }]

verticalOptions

Esta propiedad es un booleano (true o false) que se usa para poner las opciones de radioButton en vertical, por defecto su valor es false.

actions

Esta propiedad se utiliza para desbloquear nuevos campos de texto que en un principio estaban ocultos. Por ejemplo si queremos que un texto aparezca solo si seleccionamos una de las opciones de un radio button previamente.

Ejemplo:

{  "type": "radioButton",  "label": "¿Tiene mascotas?",  "css": { "marginTop": "1rem", "marginBottom": "1rem" },  "options": [    { "value": "Si", "text": "SI" },    { "value": "No", "text": "NO" }  ],  "id": "mascotas",  "actions": [    { "relatedid": "tamaño_mascota", "value": "Si", "visible": true },    { "relatedid": "tamaño_mascota", "value": "No", "visible": false }  ],  "required": true}

Esta propiedad se le añade al input que debemos hacer clic para que se desglose el input oculto, asociándolo con el id de ese respectivo input y con el valor que debemos de clicar para que se realice la acción.

El valor de relatedId puede ser un único string o un array de string, por si queremos realizar la misma acción sobre múltiples ids.

En este ejemplo, tenemos un radio button asociado a otro radio button con el id : “tamaño_mascota” y el valor “SI”. En caso de que en el primer radio seleccionemos la opción “SI”, el radio button con el id “tamaño_mascota” se pondrá en visible. Además se le añadirán las opciones que pongamos, por ejemplo, required: true y visible: true hará que el elemento a mostrar venga con esos atributos.

Por defecto, el elemento asociado deberá tener la propiedad “visible”: false.

today

Booleano para elegir si un elemento “input” de tipo “date” tiene seleccionada por defecto la fecha de hoy, (true o false), su valor predeterminado es false.

Ejemplo:

{  "type": "dateField",  "id": "incio_fecha",  "css": { "minWidth": "100px" },  "today": true,  "editable": false}

pattern

Patrón para validar el formato de un input, como un dni, cp…

No valida el contenido, en el dni/nie no se valida la letra, solo que el formato sea correcto.

Puedes encontrarlos ya creados buscando en internet o crearlos tú mismo.

Ejemplo patrón de DNI/NIE:

"pattern": "[a-zA-Z0-9]+"

"pattern": "^(?:[0-9]{8}[a-zA-Z]|[XYZ][0-9]{7}[a-zA-Z])$"

Ejemplo patrón de CP:

"pattern": "[0-9]{3}-[0-9]{2}-[0-9]{3}"

rules

Este atributo sirve para hacer validaciones más complejas a un elemento de tipo input. En él se indica que validación se le quiere hacer indicando el nombre específico de esa validación y automáticamente la adquiere.

Ejemplo:

{  "type": "textField",  "label": " DNI/NIE: ",  "id": "dni_inquilino",  "css": { "minWidth": "100px" },  "rules": "NIFNIE"}

Valida un NIF/NIE de manera que sea correcto.

getValuesOf

Este atributo se utiliza para coger el valor de otro elemento input asociados por su ID de forma dinámica, si el valor de elemento input cambia, también lo hace este.

Ejemplo de uso: Supongamos que contamos con un campo de entrada (input) identificado como «edad» y deseamos que esta información se refleje en varios elementos distintos. Para lograr esto, simplemente agregamos el atributo getValuesOf:»edad» a dichos elementos, estableciendo así una conexión entre el identificador «edad» y cada uno de estos elementos.

Ejemplo:

{  "type": "headerText",  "getValuesOf": "edad"}

Este headerText coge el valor del input con id “edad”.

cells

Propiedad obligatoria si usamos el elemento “table”, con ella indicamos las filas y columnas que tendrá nuestra tabla.

  • th: Son los titulares o encabezados de las columnas, irán resaltados en negrita.
  • tr: Son las filas de la tabla dentro tiene los td que son las celdas que quieras que tenga cada fila.

Ejemplo:

{  "type": "table",  "cells": {    "th": ["Encabezado 1", "Encabezado 2", "Encabezado 3"],    "tr": [      { "td": ["Dato 1", "Dato 2", "Dato 3"] },      { "td": ["Dato 4", "Dato 5", "Dato 6"] }    ]  },  "css": { "border": "black 3px solid" }}

dataSet

Este atributo indica a qué lista de datos quieres hacer referencia para obtenerlos. Se utiliza con el elemento dropDownField.

Por ejemplo dataSet: “divisas”. El componente dropDownField se rellenará con los valores de divisas.

Este dataSet recogerá los datos de nuestros dataSets indicados fuera de la estructura del formulario, a la altura de generalStyles y tendrá esta estructura.

Ejemplo:

"dataSets": [  {    "key": "provincias",    "values": [      { "value": "001", "text": "Bizkaika" },      { "value": "002", "text": "Madrid" },      { "value": "003", "text": "Granada" }    ]  }]

search

Esta propiedad booleana se le añade al componente dropDownField si quieres que tenga un buscador incorporado.

checked

Propiedad que sirve para indicar a un dropDownField que dato va a estar seleccionado por defecto.

Por ejemplo en provincias, del ejemplo de arriba, si escribimos checked:“001”, cogerá por defecto el valor Bizkaia.

¿Sigues con dudas?

Si este artículo no resuelve tu caso, hablamos.

Soporte técnico, dudas comerciales y demos. Te respondemos el mismo día laborable.

Hablar con un experto