POS — Artículos

¿Qué es?

Los artículos son los productos que se venden en el negocio. Desde aquí el administrador crea, edita y organiza el catálogo de productos que los cajeros y meseros ven al hacer una venta.

Se accede desde Catálogo → Artículos en el sidebar, URL: .../articles. Requiere permiso articles:read.

---

Lista de artículos (`.../articles`)

Encabezado

Título "Artículos"
Botón "Nuevo artículo" (requiere articles:create)
Campo de búsqueda por nombre

Lista

Tabla o lista de artículos mostrando para cada uno:

Imagen (miniatura)
Nombre
Categoría asignada
Precio base
Estado activo/inactivo
Indicadores de capacidades: variantes, modificadores, composición
Botones de editar y eliminar

La lista se actualiza en tiempo real vía Ably cuando otro usuario o el Asistente IA crea, edita o elimina un artículo — no es necesario recargar la página.

---

Crear / Editar artículo

Al pulsar "Nuevo artículo" o el ícono de edición, se abre un formulario con las siguientes secciones:

Información básica

Nombre (requerido)
Descripción (texto libre, visible al cliente)
Categoría (selector de categorías existentes)
Imagen (subida a Vercel Blob, almacenada como URL)
Precio base (numérico)
Activo/Inactivo — si está inactivo, no aparece en el catálogo de venta

Capacidades del artículo (flags)

Casillas que definen el tipo de artículo:

Flag	Nombre	Descripción
`has_variants`	Tiene variantes	El artículo tiene versiones con precio diferente (ej. tamaños)
`has_modifiers`	Tiene modificadores	Tiene grupos de opciones adicionales (ej. extras, salsas)
`has_composition`	Tiene composición	Es un artículo configurable con ingredientes seleccionables (tipo pizza)
`has_kitchen`	Va a cocina	Al crear una orden, este artículo se envía a la pantalla de cocina

Configuración por sucursal (branch overrides)

Si el artículo es de empresa, el administrador puede configurar:

Si el artículo está disponible en cada sucursal individualmente
Un precio diferente por sucursal (override de precio)
Si el artículo va a cocina en esa sucursal específica

Requiere permiso articles:branch_config.

---

Variantes (`.../articles/{id}/variants`)

Requisito: el artículo debe tener has_variants = true para poder agregar variantes. Si no está habilitado, la API devuelve error VARIANTS_NOT_ENABLED. Activa el flag al crear o editar el artículo.

Cuando has_variants = true, el artículo puede tener múltiples variantes. Cada variante tiene:

Nombre (ej. "Chica", "Mediana", "Grande")
Precio (puede ser diferente al precio base)
SKU (opcional)
Imagen específica de la variante (opcional)
Item de inventario vinculado (inventoryItemId): si se asigna, al vender esa variante se descuenta el inventario del ítem correspondiente

Al vender un artículo con variantes, el cajero debe seleccionar cuál antes de agregar al carrito.

---

Grupos de modificadores (`.../ingredients`)

Los modificadores son opciones que el cliente puede agregar a un artículo (ej. "¿Con o sin cebolla?", "Elige tu salsa").

Requisito: el artículo debe tener has_modifiers = true para poder asignarle grupos de modificadores. Si no, la API devuelve MODIFIERS_NOT_ENABLED.

Se gestionan en Catálogo → Modificadores (.../ingredients) y luego se asignan a artículos.

Grupo de modificadores

Nombre del grupo (ej. "Extras", "Salsas")
Tipo de selección: single (solo uno) o multiple (varios)
Mínimo de selecciones (0 = opcional)
Máximo de selecciones (null = sin límite)
Requerido (minSelections > 0)

Modificador individual

Nombre (ej. "Queso extra")
Precio extra (se suma al precio base del artículo)
Es por defecto (pre-seleccionado al abrir el diálogo)
Imagen (opcional)

---

Composición / Ingredientes de composición (`.../composition-ingredients`)

Requisito: el artículo debe tener has_composition = true para poder asignarle ingredientes. Si no, la API devuelve COMPOSITION_NOT_ENABLED.

Para artículos con has_composition = true. Los ingredientes de composición son los componentes configurables del artículo (ej. los ingredientes de una pizza).

Se gestionan en Catálogo → Ingredientes de composición. Cada ingrediente tiene:

Nombre (ej. "Pepperoni", "Champiñones")
Precio extra cuando se agrega completo
Precio mitad cuando se agrega como media porción
Imagen
Item de inventario vinculado (inventoryItemId): para descontar stock
Es por defecto (viene incluido en el artículo base)
Activo

Receta fija (article_composition_ingredients)

Además de los ingredientes seleccionables, un artículo con composición puede tener una receta fija — una lista de ingredientes con cantidades específicas que siempre se descuentan del inventario al vender el artículo, sin importar las selecciones del cliente.

---

Artículos de empresa vs. artículos de sucursal

Los artículos se crean a nivel empresa pero se asignan a sucursales:

articleAutoPropagate = true: al crear un artículo, se agrega automáticamente a todas las sucursales activas
articleAutoPropagate = false: se deben sincronizar manualmente desde Configuración → POS → Artículos → "Sincronizar ahora"
Desde la configuración de sucursal, se puede habilitar/deshabilitar cada artículo individualmente o cambiar su precio

---

Ordenamiento de artículos

El administrador puede reordenar los artículos dentro de cada categoría arrastrando las filas. El orden se guarda en el campo sortOrder y se respeta en la pantalla de venta y en la app de clientes.

Artículos