Nota

Alcance de esta sección: Esta sección explica la creación, reglas y configuraciones del Motor de Promociones Automático y Combos. Su aplicación en tiempo real en la cuenta y la validación de cupones se cubren de forma cruzada en Nueva Venta y Cupones.

Depot OS — Promociones, Combos y Descuentos

El módulo de Promociones es la herramienta de mercadotecnia y el motor de precios automatizado de Depot. Su propósito es permitirte configurar incentivos de venta (como descuentos simples, ofertas de volumen o combos complejos de alimentos) aplicados de manera 100% matemática y en tiempo real durante la venta. Esto elimina el error humano de cálculo del cajero y previene fugas de efectivo.

1. Tipos de Beneficios y Mecánicas de Descuento

Depot clasifica las promociones según su comportamiento matemático en el punto de venta (type):

Descuento Porcentual (percentage_off): Deduce un porcentaje específico sobre los artículos válidos (ej. "15% de descuento en bebidas").
Descuento por Monto Fijo (fixed_off): Resta una cantidad monetaria exacta al total de los artículos válidos (ej. "$30.00 pesos de descuento en hamburguesas").
Promociones de Volumen (bogo): Mecánica "Compra X y lleva Y" (Compre X y obtenga Y gratis o con descuento, ej. "2x1 en pizzas los martes", donde la cantidad mínima requerida es 2 y la unidad de menor precio se descuenta al 100%).
Combos / Paquetes (bundle): Permite armar grupos independientes de productos que, al juntarse en el carrito, adquieren un precio fijo total unificado (ej. "1 Hamburguesa + 1 Papa + 1 Refresco por $180.00 pesos").
Producto de Regalo (free_item): Regala un artículo específico si se cumplen ciertas condiciones en el ticket de venta.

2. Segmentación, Alcance y Filtros del Catálogo

Puedes delimitar con precisión quirúrgica a qué productos o áreas del pedido afectará el beneficio (scope):

Total del Pedido (order): El descuento se calcula sobre la sumatoria de todo el carrito de compras (sujeto al consumo mínimo).
Artículos Específicos (item): Aplica el beneficio de forma exclusiva a una lista manual de productos o variantes seleccionadas de tu catálogo.
Categorías (category): El descuento aplica únicamente a los productos pertenecientes a las categorías seleccionadas (ej. "15% de descuento solo en la categoría de Cervezas").

3. Reglas de Activación y Calendario (Vigencia)

Para garantizar la rentabilidad de tus campañas, puedes establecer condiciones restrictivas de uso que el sistema valida automáticamente:

Consumo Mínimo (minOrderAmount): La promoción se activa únicamente si el valor de los productos válidos en el carrito alcanza o supera el monto monetario establecido.
Vigencia en el Tiempo (startDate y endDate): Configura fechas de inicio y fin para que las campañas estacionales (como Navidad o el Buen Fin) comiencen y concluyan de forma automática.
Días de la Semana (daysOfWeek): Permite limitar el beneficio a ciertos días específicos (ej. lunes, martes y miércoles).
Rango Horario (startTime y endTime): Ideal para configurar ofertas de Happy Hour, limitando la aplicación al horario exacto de la transacción (ej. de 5:00 PM a 7:00 PM).
Límite de Redenciones (maxUses): Controla el número máximo de veces que la promoción puede aplicarse en toda la empresa (ej. "Limitado a los primeros 500 combos").

4. Nuevo Constructor Visual de Combos (Bundle Builder)

Un combo se compone de Grupos de Selección independientes (ej. "Entrada", "Plato Fuerte", "Bebida"). Para cada grupo, puedes definir:

Nombre del Grupo: Etiqueta que orienta al cajero (ej. "Elige tu refresco").
Cantidad Requerida (requiredQuantity): Número de artículos que el cliente debe seleccionar de ese grupo para completar el combo (ej. 1 refresco).
Artículos Elegibles: Selección múltiple de productos, categorías o variantes específicas que califican para este grupo.

Restricciones Avanzadas de Ingredientes en Combos

Máximo de Ingredientes Permitidos (maxIngredientsAllowed): Limita la cantidad de extras/ingredientes adicionales que el comensal puede agregar al producto dentro del combo sin costo extra o de forma permitida (ej. "La pizza del combo solo puede llevar hasta 2 ingredientes extra").
Ingredientes Prohibidos (forbiddenIngredientIds): Permite vetar ingredientes específicos de un producto cuando se pide dentro del combo (ej. "El combo no permite extra pepperoni").

5. Caso de Estudio Práctico: Configurar el Combo "Refresco + Alitas por $150"

A continuación, se detalla la configuración exacta paso a paso para crear este paquete de manera correcta en el panel de Depot OS:

Paso 1: Datos Generales de la Promoción

Nombre: Combo Alitas y Refresco
Tipo de Promoción: Combo (bundle)
Valor de Descuento (Precio del Combo): 150.00
Aplica a (Alcance): Artículos específicos (item)

Paso 2: Configurar los Grupos en el Constructor Visual

Agrega dos grupos independientes de la siguiente manera:

Grupo 1: El Refresco

Nombre del Grupo: Refresco de lata
Cantidad Requerida: 1
Artículos Elegibles: Selecciona los artículos o variantes del catálogo que correspondan a refrescos de lata (ej. Coca-Cola Lata, Fanta Lata, Sprite Lata).

Grupo 2: Las Alitas

Nombre del Grupo: Alitas
Cantidad Requerida: 1
Artículos Elegibles: Selecciona los artículos que correspondan a orden de alitas (ej. Alitas BBQ, Alitas Búfalo).
Máx ingredientes permitidos: null (sin límite).

Paso 3: Guardar y Activar

Activa el interruptor "Activa".
Guarda los cambios.

¿Cómo opera esto en el Punto de Venta (POS)?

Cuando el cajero agregue al carrito 1 Coca-Cola Lata ($30.00) y 1 Alitas BBQ ($140.00), el motor de promociones de Depot OS detectará automáticamente que se cumple el combo y aplicará un descuento de -$20.00 para ajustar el precio total del paquete exactamente a $150.00.

6. Configuración y Parámetros del Sistema (POS Settings)

Las políticas generales del motor de ofertas automáticas se guardan en la base de datos a nivel empresa en companies.pos_settings. En el menú de configuración de Depot OS, puedes modificar:

Parámetro / Key	Tipo	Valor por Defecto	Descripción y Efecto Operativo
`enablePromotions`	`boolean`	`false`	Habilitar Promociones: Interruptor maestro que activa o desactiva por completo el motor de promociones y combos tanto en el punto de venta como en las validaciones de backend.
`promotionAutoApply`	`boolean`	`false`	Auto-aplicar descuento: Si es `true`, la terminal calcula y aplica de forma automática la promoción más conveniente en el subtotal sin que el cajero deba seleccionarla manualmente.
`promotionMaxStack`	`select`	`"1"`	Promociones acumulables: Define el límite máximo de promociones acumulables permitidas en un mismo ticket de venta (`1` = no acumulable, `2`, `3`).

Advertencia

Exclusión de Cupones (excludeCoupons): Si una promoción tiene activa la casilla "Excluir Cupones", el sistema bloqueará la aplicación de cualquier cupón de descuento adicional sobre el mismo ticket, protegiendo los márgenes de ganancia mínimos del negocio.

7. Validación Servidor y Seguridad

Para evitar fraudes, discrepancias horarias o manipulaciones en el cliente móvil:

Cálculo y Validación en el Servidor: El servidor valida que posSettings.enablePromotions esté en true y recalcula todos los descuentos en el backend al procesar POST /api/orders utilizando los datos de precios originales de la base de datos.
Evaluación de Zona Horaria (Timezone-Aware): Las fechas de vigencia (startDate y endDate) se evalúan rigurosamente de forma relativa a la zona horaria de la compañía/sucursal configurada en la base de datos para evitar discrepancias por la localización del cliente.
Límite de Descuento: El descuento de monto fijo se limita automáticamente por el valor de la sumatoria de los artículos para evitar subtotales negativos.
Contador Atómico: Tras insertar la orden, el contador usedCount se incrementa de manera atómica en la base de datos.

Módulo: Promociones