POST /v1/fields

POST/v1/fields

Para desarrolladores

Descripción

Crea un campo del catálogo de la instancia, reutilizable por cualquier formulario.

Existe para poblar un catálogo sin cargarlo a mano: un cliente que llega desde otra plataforma trae sus campos definidos, y recrearlos de a uno en el panel es lento y propenso a errores de tipeo en las llaves.

Editar, desactivar y eliminar un campo se hacen desde el panel. Esta API solo crea.

Autenticación

Authorizationbearer tokenheaderobligatorio

API key con scope field:write. Formato: Bearer FD.<key_id>.<token>.

X-Instance-Slugstringheaderobligatorio

Request

Body:

{
  "name": "Cómo nos conociste",
  "field_key": "FUENTE",
  "type": "select",
  "config": {
    "options": [
      { "value": "GOOGLE", "label": "Búsqueda en Google" },
      { "value": "RECOMENDACION", "label": "Recomendación de un colega" }
    ]
  }
}

namestringobligatorio

Nombre visible del campo. Máx. 255 caracteres.

field_keystringobligatorio

Clave canónica del campo. Solo MAYÚSCULAS, números y guion bajo, máx. 64 caracteres. Inmutable, y queda reservada para siempre aunque el campo se elimine.

typestringobligatorio

text, textarea, email, phone, number, date, select, multiselect, boolean, url o address.

configobject

Validadores del tipo. Ver Opciones de selección.

Opciones de selección

Un campo select o multiselect declara sus opciones en config.options. Cada opción es un par:

{ "value": "GOOGLE", "label": "Búsqueda en Google" }

• value es lo que queda guardado en cada respuesta y lo que se lee en el archivo exportado. Admite solo MAYÚSCULAS, números y guion bajo, máx. 32 caracteres. Conviene que sea corto y reconocible: viaja entero dentro de cada respuesta.
• label es lo que lee quien completa el formulario. Puede cambiarse cuando haga falta.

Declararlos por separado es lo que permite corregir el texto visible sin alterar lo que guardaron las respuestas anteriores. Dos opciones no pueden declarar el mismo value.

Response

201 Created, con la cabecera Location apuntando al campo creado y su representación en el cuerpo:

Errores

Código	code	Cuándo
403	forbidden	La API key no tiene el scope field:write, o la IP no está en la lista permitida.
409	field_key_already_exists	Ya existe un campo activo con ese field_key.
409	field_key_reserved	Ese field_key perteneció a un campo eliminado y no puede reutilizarse.
422	validation_error	El cuerpo no cumple el contrato. errors[] indica el campo y el motivo.

El catálogo completo está en Errores.

Request

curl -X POST "https://cl2api.fidelizador.com/v1/fields" \
-H "Authorization: Bearer FD.<key_id>.<token>" \
-H "X-Instance-Slug: <slug>" \
-H "Content-Type: application/json" \
-d '{
  "name": "Cómo nos conociste",
  "field_key": "FUENTE",
  "type": "select",
  "config": {
    "options": [
      {
        "value": "GOOGLE",
        "label": "Búsqueda en Google"
      },
      {
        "value": "RECOMENDACION",
        "label": "Recomendación de un colega"
      }
    ]
  }
}'

Response

{
"id": 7,
"name": "Cómo nos conociste",
"field_key": "FUENTE",
"type": "select",
"is_system": false,
"is_active": true,
"config": {
  "options": [
    {
      "value": "GOOGLE",
      "label": "Búsqueda en Google"
    },
    {
      "value": "RECOMENDACION",
      "label": "Recomendación de un colega"
    }
  ]
},
"created_at": "2026-09-15T03:54:00Z",
"updated_at": "2026-09-15T03:54:00Z"
}