Campos Personalizados

Campos personalizados

Keirost permite extender cualquier tabla del sistema con campos adicionales definidos por el usuario. Esta funcionalidad esta disponible tanto desde la UI como via API.

Tablas soportadas

Los campos personalizados se pueden anadir a cualquier tabla del sistema:

Tabla	Descripción
Item	Artículos/productos
BusinessPartner	Socios de negocio (clientes/proveedores)
SalesInvoice	Facturas de venta
PurchaseInvoice	Facturas de compra
SalesOrder	Pedidos de venta
PurchaseOrder	Pedidos de compra
SalesDeliveryNote	Albaranes de venta
PurchaseDeliveryNote	Albaranes de compra
Employee	Empleados
Warehouse	Almacenes

---

Modelo

interface CustomField {
  id: string;
  plugin_id?: string;        // Si lo creo un plugin, si no null
  table_name: string;        // "Item", "BusinessPartner", etc.
  field_name: string;       // "loyalty_points", "custom_color"
  label: string;            // "Puntos de fidelidad", "Color personalizado"
  type: CustomFieldType;
  position: number;         // Orden en la UI
  visible_in_list: boolean;
  visible_in_form: boolean;
  required: boolean;
  default_value?: string;
  help_text?: string;
  options?: string[];       // Para campos de seleccion
  validation_regex?: string;
  active: boolean;
  created_at: string;
}

type CustomFieldType =
  | 'TEXT'
  | 'NUMBER'
  | 'DECIMAL'
  | 'BOOLEAN'
  | 'DATE'
  | 'DATETIME'
  | 'SELECT'
  | 'MULTISELECT'
  | 'TEXTAREA'
  | 'URL'
  | 'EMAIL'
  | 'PHONE'
  | 'CURRENCY'
  | 'PERCENTAGE';

---

Endpoints

Método	Ruta	Descripción
GET	/api/custom-fields	Listar campos personalizados
POST	/api/custom-fields	Crear campo
GET	/api/custom-fields/:id	Ver campo
PATCH	/api/custom-fields/:id	Actualizar campo
DELETE	/api/custom-fields/:id	Eliminar campo
GET	/api/custom-fields/by-table/:table	Campos de una tabla

Crear campo

POST /api/custom-fields
Authorization: Bearer <token>
Content-Type: application/json

{
  "table_name": "BusinessPartner",
  "field_name": "loyalty_points",
  "label": "Puntos de fidelidad",
  "type": "NUMBER",
  "position": 10,
  "visible_in_list": false,
  "visible_in_form": true,
  "required": false,
  "default_value": "0"
}

Listar campos de una tabla

GET /api/custom-fields/by-table/Item

Actualizar posición

PATCH /api/custom-fields/:id
Content-Type: application/json

{
  "position": 5,
  "visible_in_list": true
}

---

Uso en plugins

Los plugins pueden crear campos personalizados como parte de su migración:

plugins/mi-plugin/index.ts

export const init = async ({ hooks, migration }) => {
  await migration.addCustomField({
    pluginId: 'mi-plugin',
    tableName: 'Item',
    fieldName: 'custom_weight',
    type: 'DECIMAL',
    label: 'Peso personalizado (g)',
    defaultValue: '0',
    required: false,
  });
};

Los campos de plugin se identifican por plugin_id no nulo y no se pueden editar ni eliminar desde la UI (solo el plugin que los creo puede modificarlos).

---

Lectura y escritura de valores

Los valores de campos personalizados se leen y escriben como parte del documento/registro:

{
  "id": "item_001",
  "name": "Producto A",
  "sku": "PROD-A",
  "custom_loyalty_points": 150,
  "custom_color": "#FF0000"
}

Los campos personalizados se incluyen automáticamente en:

• GET del recurso (respuesta completa)
• POST/PATCH del recurso (se pueden escribir)
• Exportaciones (CSV, Excel)
• Filtros de búsqueda avanzada
• Plantillas PDF (via campo {{custom_field_name}})

---

Resumen de endpoints

Método	Ruta	Descripción
GET	/api/custom-fields	Listar todos los campos
POST	/api/custom-fields	Crear campo
GET	/api/custom-fields/:id	Ver campo
PATCH	/api/custom-fields/:id	Editar campo
DELETE	/api/custom-fields/:id	Eliminar campo
GET	/api/custom-fields/by-table/:table	Campos de una tabla