Para qué sirve#
Los cupones son códigos de descuento que puedes crear para todos tus compradores o solo para uno o varios contactos, con las reglas que necesites (vigencia, límites de uso, productos…). Una tienda o carrito externo los valida con la API de cupones.
Quién puede usarlo: administradores y supervisores. Solo un administrador enciende o apaga el módulo.
Cómo llegar: menú lateral → Cupones (junto a Pedidos). El módulo viene apagado: enciende el interruptor Módulo, arriba a la derecha. Mientras esté apagado, la API responde «modulo_apagado» y ningún cupón se puede usar.
Tipos de descuento#
| Tipo | Qué hace |
|---|---|
| Porcentaje | Descuenta un % del subtotal de los productos elegibles del carrito. Opcionalmente tiene un tope máximo en USD (por ejemplo 15 % sin superar 50 USD). |
| Envío gratis | No descuenta productos: la tienda pone el envío del pedido en cero. |
El descuento se calcula en centavos y se reparte entre las líneas elegibles; nunca supera el subtotal elegible.
Crear un cupón#
- Pulsa Nuevo cupón, escribe el nombre interno (el botón azul se habilita al escribirlo) y, si quieres, el código. Si lo dejas vacío se genera uno aleatorio fácil de leer (sin 0, O, 1 ni I).
- Se abre el editor. Todo se guarda solo: cada cambio aparece como «Guardado» en el toast negro.
Secciones del editor#
- General: código (letras, números y guiones; no distingue mayúsculas y no se puede cambiar cuando el cupón ya se usó), nombre, descripción e interruptor Cupón activo (apaga el cupón al instante sin borrarlo).
- Descuento: tipo, porcentaje y tope máximo.
- Vigencia y límites (todos opcionales; vacío = sin límite): fecha de inicio y de vencimiento, usos totales, usos por contacto (por defecto 1; si el comprador solo envía su correo, se cuenta por correo), monto mínimo y cantidad mínima (se calculan sobre los productos elegibles), solo primera compra (el contacto no tiene pedidos pendientes, en proceso ni completados) y se puede combinar con otros cupones.
- Quién puede usarlo: por defecto cualquier comprador. Con Solo para contactos específicos agregas los contactos con el buscador; solo ellos podrán usarlo.
- Productos: sin reglas el cupón aplica a todos los productos. Agrega reglas de Incluir (solo estos) o Excluir (estos no):
- Un producto con todas sus referencias,
- una o varias referencias concretas del producto (por ejemplo solo «A-PRO»),
- una categoría completa.
- Probar el cupón: arma un carrito de prueba y ve si el cupón se puede usar y cuánto descontaría. No gasta ningún uso.
- Usarlo desde una tienda externa: ejemplo de llamada a la API con el código de este cupón.
- Historial de usos: fecha, comprador, referencia (número de pedido de la tienda), descuento, origen y estado (canjeado o liberado).
Un cupón individual por contacto#
Generar para contactos crea un cupón distinto para cada contacto elegido (código tipo VIP-7K3M9QX2), de un solo uso y que solo ese contacto puede usar. Eliges el prefijo, el tipo y valor, y la fecha de vencimiento; luego puedes ajustar las reglas de cada cupón. Al final puedes copiar la lista «contacto → código» para enviarla.
Cupones de los asesores (pestaña «Cupones» del contacto)#
Los asesores pueden crear un cupón para el cliente que están atendiendo, desde la pestaña Cupones del panel de información del contacto (en el Chat, al responder un correo y en las llamadas). Está apagado: un administrador lo permite en la pantalla Cupones, tarjeta Cupones de los asesores (se guarda solo), y fija los topes:
| Tope | Qué limita |
|---|---|
| Porcentaje máximo | El mayor descuento que puede dar un asesor (por defecto 10 %). |
| Vigencia máxima | Los días de validez del cupón (por defecto 30). |
| Cupones activos por contacto | Cuántos cupones activos puede tener a la vez un contacto (por defecto 3), para evitar abusos. |
Administradores y supervisores ven la pestaña siempre que el módulo esté encendido y no tienen topes. Los topes se comprueban también en el servidor.
En la pestaña ves los cupones de ese contacto (código, descuento, vigencia, usos y estado; el número de la pestaña cuenta los activos). Con Crear cupón eliges porcentaje o envío gratis, la vigencia y un motivo opcional. El cupón nace de un solo uso y solo ese contacto lo puede usar, con un código tipo CL-7K3M9QX2. Puedes Crear y enviar (por el chat, el correo o las notas de la llamada, según dónde estés) o solo crearlo y luego usar Enviar o Copiar código. El cupón queda en la lista general de Cupones, con quién lo creó en la descripción.
Combinar cupones#
Por defecto se usa un cupón por pedido. Si dos cupones están marcados como combinables se pueden sumar; si cualquiera de los dos no lo es, la API responde «no_combinable».
Estados#
Activo, Programado (todavía no inicia), Vencido, Agotado (llegó al límite de usos) y Desactivado.
Eliminar#
El icono de papelera (gris, rojo al pasar el cursor) pide confirmación. Un cupón sin usos se elimina; uno que ya se usó se desactiva para conservar su historial.
Motivos por los que un cupón no se puede usar#
| Motivo | Significado |
|---|---|
no_existe | El código no existe |
inactivo | Está desactivado |
no_iniciado / vencido | Fuera de su vigencia |
agotado | Llegó al límite de usos totales |
limite_contacto | El comprador ya lo usó el máximo permitido |
contacto_requerido | Hay que identificar al comprador (contacto o correo) |
contacto_no_elegible | El cupón es para otros contactos |
no_es_primera_compra | Solo valía para la primera compra |
no_combinable / ya_aplicado | Choca con otro cupón del carrito |
items_requeridos | Faltan los productos del carrito para calcular el descuento |
sin_productos_elegibles | Ningún producto del carrito entra en las reglas |
monto_minimo / cantidad_minima | El carrito no alcanza el mínimo |
<!-- Fuente: tenant-app/public/cupones/index.php, tenant-app/public/api/cupones.php, shared/src/Core/Cupones.php, db/migrations/0216_cupones.sql -->