Cupones

Los cupones son códigos promocionales que los clientes pueden canjear para obtener descuentos en compras y facturas.

Campos del Cupón

Campo	Descripción
Código	Código único, almacenado en mayúsculas
Nombre	Nombre interno del cupón
Descripción	Detalles de la promoción
Tipo de descuento	percentage (porcentual) o fixed_amount (valor fijo)
Valor del descuento	Porcentaje (0–100) o valor en BRL, según el tipo
Moneda	Predeterminado: BRL
Compra mínima	Valor mínimo del pedido para usar el cupón
Descuento máximo	Tope del descuento (para cupones porcentuales)
Límite de uso total	Máximo de canjes permitidos
Límite por cliente	Máximo de canjes por cuenta de cobro
Válido de / hasta	Período de validez
Se aplica a	Planes y/o productos específicos (JSON)
Excluye	Planes y/o productos excluidos (JSON)
Activo	Si el cupón está habilitado

Validación de Cupón

Al validar un cupón, el sistema verifica:

1. El cupón existe y el código coincide
2. El cupón está activo (isActive = true)
3. Está dentro del período de validez
4. El límite de uso total no fue alcanzado
5. El límite de uso por cliente no fue alcanzado
6. La compra alcanza el valor mínimo

Cálculo del Descuento

Si porcentual: descuento = subtotal × porcentaje / 100
Si fijo: descuento = valor_del_descuento

Aplica tope: descuento = min(descuento, maxDiscountCents)
No excede subtotal: descuento = min(descuento, subtotal)

Canjeando un Cupón

Al aplicar un cupón:

1. Valida todas las condiciones
2. Crea un registro de CouponRedemption con el valor del descuento
3. Incrementa el contador de uso del cupón
4. Retorna el canje con el valor descontado

El proceso es atómico (transacción) para prevenir condiciones de carrera.

Operaciones

• Activar/Desactivar: Controla si el cupón puede ser validado
• Eliminar: Solo si nunca fue utilizado (ningún canje registrado)
• Actualizar: Código, nombre, límites, fechas y valores editables

Reporte de Canjes

Para cada cupón, el sistema rastrea:

• Quién canjeó (cuenta de cobro)
• Cuándo canjeó
• Valor del descuento aplicado
• Factura asociada (opcional)

Captura de pantalla

La pantalla /dashboard/coupons lista todos los cupones de la organización, con código, tipo de descuento, valor, vigencia, número de canjes y status. La interfaz permite crear cupones porcentuales o de valor fijo, con límite total y por cliente.