> ## Documentation Index
> Fetch the complete documentation index at: https://docs.filexpress.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Promociones

> Descuentos automáticos por porcentaje, monto fijo, precio nuevo o combo que se aplican al agregar productos al carrito

Las promociones permiten definir descuentos que el sistema aplica automáticamente en **POS** y **Nueva Venta** al detectar que los productos y condiciones configuradas se cumplen — sin intervención manual del vendedor.

## Tipos de promoción

| Tipo             | Código           | Descripción                                       |
| ---------------- | ---------------- | ------------------------------------------------- |
| **Porcentaje**   | `percentage`     | Rebaja un % sobre el precio o subtotal            |
| **Monto fijo**   | `fixed`          | Rebaja una cantidad fija en dólares               |
| **Precio nuevo** | `override_price` | Reemplaza el precio por uno nuevo                 |
| **Combo**        | `combo`          | Fija un precio total para un paquete de productos |

## Crear una promoción

<Steps>
  <Step title="Ir a Ventas → Promociones → Nueva Promoción" />

  <Step title="Completar los campos principales">
    | Campo                | Descripción                                                                                         |
    | -------------------- | --------------------------------------------------------------------------------------------------- |
    | Nombre               | Identificador visible en el carrito (ej. "2x1 Producto A")                                          |
    | Descripción          | Texto interno, no visible al cliente                                                                |
    | Tipo de descuento    | Ver tabla de tipos arriba                                                                           |
    | Valor / Precio combo | Porcentaje, monto fijo, precio nuevo o precio total del combo                                       |
    | Aplica en            | **Precio unitario** o **Subtotal de la venta**                                                      |
    | Cantidad mínima      | Mínimo de unidades requeridas para activar la promo                                                 |
    | Vigencia             | Rango de fechas opcionales (inicio y fin)                                                           |
    | Prioridad            | Mayor número = mayor prioridad. Cuando dos promos aplican al mismo ítem, gana la de mayor prioridad |
    | Activa               | Activar o pausar sin eliminar                                                                       |
  </Step>

  <Step title="Agregar condiciones">
    Define **a qué se aplica** la promo. Si no hay condiciones, aplica a todos los productos.

    | Tipo de condición     | Descripción                                    |
    | --------------------- | ---------------------------------------------- |
    | Productos específicos | Lista de productos por nombre                  |
    | Categorías            | Todos los productos de una o varias categorías |
    | Marcas                | Todos los productos de una o varias marcas     |

    Para combos: se requieren condiciones de tipo **Productos específicos** — todos deben estar en el carrito para que el combo se active.
  </Step>

  <Step title="Guardar">
    La promoción queda activa de inmediato (si está dentro del rango de fechas).
  </Step>
</Steps>

## Cómo se evalúan las promociones

Cuando se agrega o modifica un producto en el carrito, el sistema consulta automáticamente todas las promociones activas vigentes:

### Promos por ítem (apply\_on: unit\_price)

* Se evalúan todas las promos que apliquen al producto.
* **Solo se aplica la de mayor prioridad** — no se acumulan.
* El descuento se muestra como `promo_discount` junto al producto en el carrito.

### Promos por subtotal (apply\_on: subtotal)

* Se acumulan todas las promos de subtotal que apliquen.
* El descuento total se muestra en el resumen de la venta como descuento global de promoción.

### Combos

* Requieren que **todos** los productos de las condiciones estén presentes en el carrito.
* El descuento es a nivel de orden: `descuento = suma de precios individuales − combo_price`.
* Si algún producto del combo se elimina del carrito, el descuento desaparece automáticamente.

## Precios y clientes exentos de IVA

Los precios de tipo **Precio nuevo** y **Combo** se configuran como **precios al consumidor final (IVA incluido)** para productos gravados.

Cuando el cliente seleccionado está marcado como exento de IVA (`is_exent`), el sistema extrae automáticamente el impuesto:

```
Precio combo consumidor: $45.00 (IVA incluido)
Para cliente exento:     $45.00 ÷ 1.13 = $39.82
```

<Note>
  El sistema realiza este cálculo automáticamente tanto en POS como en Nueva Venta. No es necesario crear una promoción separada para clientes exentos.
</Note>

## Ejemplo: promoción por porcentaje

| Campo           | Valor                     |
| --------------- | ------------------------- |
| Nombre          | 10% OFF Categoría Bebidas |
| Tipo            | Porcentaje                |
| Valor           | 10                        |
| Aplica en       | Precio unitario           |
| Condición       | Categoría: Bebidas        |
| Cantidad mínima | 1                         |

Resultado en carrito:

* Producto "Agua 500ml" $1.50 → promo_discount $0.15 → precio efectivo **\$1.35**

## Ejemplo: combo de productos

| Campo        | Valor                                                             |
| ------------ | ----------------------------------------------------------------- |
| Nombre       | Combo Almuerzo                                                    |
| Tipo         | Combo                                                             |
| Precio combo | \$8.99                                                            |
| Condiciones  | Producto: Hamburguesa, Producto: Papas fritas, Producto: Refresco |

Resultado en carrito (si los 3 productos están presentes):

* Hamburguesa $5.00 + Papas $2.50 + Refresco $1.50 = $9.00 normal
* Con combo → descuento de $0.01 aplicado al total → **$8.99\*\*

## Prioridad y orden de evaluación

Cuando hay varias promos activas, el sistema las evalúa en orden descendente de prioridad. Para promos por ítem, la **primera que aplica gana** y las demás son ignoradas para ese producto.

<Warning>
  Una misma promo de subtotal puede combinarse con promos por ítem, pero dos promos de tipo "precio unitario" no se acumulan en el mismo producto.
</Warning>

## Gestionar promociones activas

Desde el listado de promociones se puede:

* **Activar / Desactivar** con el toggle — útil para promociones de temporada.
* **Editar** todos los campos sin afectar el historial de ventas ya procesadas.
* **Eliminar** si la promoción ya no se necesita.