Definición de los campos
Referencia técnica del array fields de un formulario de captación: tipos, propiedades, propiedad del lead de cada campo y consentimiento obligatorio.
Actualizado el . 5 min de lectura
Incluido en los planes Profesional y Avanzado. Ver precios
Esta página es la referencia técnica de fields, el array que define los campos de un formulario de captación cuando lo creas o editas por la API de formularios o lo lees de su configuración pública. Si solo quieres montar un formulario desde el panel, la guía de uso es Tipos de campo.
Propiedades de un campo
- idstringobligatorio
- Identificador único dentro del formulario. Es la clave con la que viaja su valor al enviar.
- typestringobligatorio
- Uno de los doce tipos de la tabla siguiente.
- labelstringobligatorio
- Etiqueta visible. En consent, el texto de la cláusula.
- requiredbooleanobligatorio
- Si es obligatorio. Lo comprueba el navegador; el servidor solo exige el correo y los consentimientos obligatorios.
- ordernumberobligatorio
- Posición, de menor a mayor.
- placeholderstring
- Texto de ayuda con el campo vacío. En select, el texto de la opción vacía (por defecto, «Seleccionar...»).
- leadFieldstring
- Propiedad del lead donde se guarda el valor (ver más abajo). Sin ella, el valor va a metadata del lead.
- widthnumber
- 6 ocupa media fila; cualquier otro valor, la fila entera.
- optionsarray
- Opciones de select: [{ label, value }].
- consentLinksarray
- Enlaces de un consent: [{ text, url }]. Ver «Consentimiento».
Tipos
type | En el panel | Qué es |
|---|---|---|
text | Texto | Texto de una línea. |
email | Correo electrónico | Correo principal, con validación de formato. Va a email del lead aunque no tenga leadField. |
secondaryEmail | Correo electrónico secundario | Segundo correo, con validación de formato. Va a secondaryEmail. No puede coincidir con el principal. |
phone | Teléfono | Teléfono en formato libre. |
textarea | Área de texto | Texto de varias líneas. |
select | Selector | Lista desplegable con options. |
radio | Opciones | Opción única entre varias. |
checkbox | Casilla | Casilla que envía true o false. |
hidden | Oculto | Pensado para enviar un valor fijo. |
heading | Encabezado | Título de sección; no envía nada. |
divider | Separador | Línea de separación; no envía nada. |
consent | Consentimiento | Casilla de la cláusula informativa del artículo 13 del RGPD. |
El catálogo con estos tipos lo devuelve GET /api/lead-forms/field-types/catalog.
Lo que el formulario insertado todavía no aplica
El script del formulario pinta hoy radio y hidden como un campo de texto normal, y no aplica ni validation (mínimo y máximo de caracteres, patrón) ni la visibilidad condicional (conditionalOn), aunque el panel permita guardarlos. El servidor tampoco los comprueba. Hasta que se corrija, no confíes en ellos para validar ni para ocultar datos.
Dónde acaba cada valor
Adónde va el valor de un campo
A una propiedad del lead
Con leadField
A los datos adicionales
Sin leadField
Si no llega fullName, se compone con el nombre y los apellidos, y si tampoco llegan, se usa el correo.
El panel ofrece además «Ciudad» (city) y «País» (country) como destino, pero hoy el servidor no guarda esos dos valores: si los necesitas, deja el campo sin leadField para que vaya a metadata.
Cada formulario necesita un valor de correo principal: sin él, el envío responde 400 «El campo de correo electrónico es obligatorio».
Consentimiento
Todo formulario lleva al menos un campo consent con required: true. Si al crear o editar el formulario no lo incluyes, el servidor añade uno al final con el identificador reservado art13_consent, marcado como campo de sistema (systemField: true) y no eliminable desde el editor (deletable: false).
Su cláusula se redacta con los datos de tu organización: la razón social (o el nombre comercial) y el correo general de tu configuración, y la dirección de privacidad del formulario. Si el formulario mide el origen de las visitas, añade una frase que lo anuncia. Si tu organización no tiene razón social configurada, la cláusula habla de «la entidad titular de este formulario».
Enlaces dentro de la cláusula
En label, cada marcador {0}, {1}... se sustituye por el enlace de esa posición de consentLinks. Un enlace sin url se pinta como texto, sin enlace.
{
"id": "art13_consent",
"type": "consent",
"required": true,
"order": 99,
"label": "He leído y acepto la {0} de Tu Empresa S. L., que me informa de que mis datos se tratarán con la finalidad de gestionar mi solicitud, conforme al art. 13 RGPD.",
"consentLinks": [
{ "text": "política de privacidad", "url": "https://tuempresa.com/privacidad" }
]
}Validación y justificante
El navegador no deja enviar sin marcar un consentimiento obligatorio («Debes aceptar este consentimiento»), y el servidor lo vuelve a comprobar: solo vale true o "true". Si falta, responde 400 CONSENT_REQUIRED con el fieldId.
Con un envío válido, el lead guarda un justificante (consentSnapshot):
- versionnumberobligatorio
- requiredConsentVersion del formulario (1 si no tiene).
- fieldIdstringobligatorio
- El primer consentimiento obligatorio del formulario.
- labelAcceptedstringobligatorio
- El texto de la cláusula tal como se mostró.
- linksarrayobligatorio
- Sus consentLinks en ese momento.
- acceptedAtstringobligatorio
- Fecha y hora de la aceptación (ISO 8601).
- ipAddressstringobligatorio
- IP del visitante.
- userAgentstringobligatorio
- Navegador del visitante.
- contactPointsConsentedstring[]obligatorio
- Los correos que cubre (principal y, si lo hay, secundario).
- consentsAcceptedarrayobligatorio
- Todas las casillas de consentimiento marcadas, obligatorias u opcionales: { fieldId, label, required, accepted }.
Una casilla checkbox no es un consentimiento: no cuenta para la obligación del artículo 13 ni entra en el justificante. Para una casilla opcional que sí quede registrada (por ejemplo, aceptar comunicaciones comerciales), usa otro consent con required: false.
Ejemplo
[
{ "id": "field_nombre", "type": "text", "label": "Nombre", "required": true, "order": 1, "leadField": "firstName", "width": 6 },
{ "id": "field_apellidos", "type": "text", "label": "Apellidos", "required": true, "order": 2, "leadField": "lastName", "width": 6 },
{ "id": "field_email", "type": "email", "label": "Correo electrónico", "required": true, "order": 3, "leadField": "email" },
{
"id": "field_interes", "type": "select", "label": "Servicio de interés", "required": false, "order": 4,
"options": [
{ "label": "Consultoría", "value": "consultoria" },
{ "label": "Desarrollo web", "value": "desarrollo-web" }
]
},
{
"id": "art13_consent", "type": "consent", "required": true, "order": 5,
"label": "He leído y acepto la {0}, que me informa del tratamiento de mis datos conforme al art. 13 RGPD.",
"consentLinks": [{ "text": "política de privacidad", "url": "https://tuempresa.com/privacidad" }]
}
]El campo field_interes no tiene leadField, así que su valor llega al lead en metadata.field_interes.
Siguiente paso
Da forma al formulario con el objeto styling y publícalo con la API de formularios.
Ponlo en práctica
Lo encontrarás en Formularios de captación. Para abrirlo, entra con tu cuenta de UTILIA OS.