Saltar al contenido principal

Introducción

🎯 ¿Qué hace este módulo?​

El módulo de Descuentos te permite gestionar y aplicar descuentos a productos y pedidos - desde promociones basadas en porcentajes hasta reducciones de monto fijo - soportando códigos de cupones, descuentos por categoría y ofertas específicas para clientes en toda tu tienda de comercio electrónico.

Piénsalo como tu motor de promociones - define las reglas de descuento en el panel de administración de OneEntry, aplícalas a productos o pedidos completos, valida los códigos de cupones en el proceso de pago y automatiza los ajustes de precios para tus clientes.

📖 Explicación Simple​

Cada tienda de comercio electrónico necesita descuentos flexibles:

  • 🏷️ Descuentos por Porcentaje - 10% de descuento en productos seleccionados
  • 💰 Descuentos Fijos - $5 de descuento en pedidos superiores a $50
  • 🎟️ Códigos de Cupones - Códigos promocionales para campañas específicas
  • 📦 Descuentos por Categoría - Descuentos en categorías completas de productos
  • 👤 Descuentos para Clientes - Precios especiales para clientes o grupos específicos
  • 📅 Ofertas por Tiempo Limitado - Ventas con fechas de inicio y fin definidas

Problemas sin gestión de descuentos:

  • 🔒 Precios inflexibles - Necesidad de cambios de código para cada promoción
  • 📊 Difícil de rastrear - Sin gestión centralizada de descuentos
  • 🔄 Sin automatización - Actualizaciones manuales de precios para cada venta

La solución de Descuentos:

Beneficios:

  • 🔒 Promociones flexibles - Crea y gestiona descuentos en el panel de administración
  • 📊 Control centralizado - Todos los descuentos en un solo lugar
  • 🔄 Aplicación automatizada - Descuentos aplicados automáticamente en el proceso de pago
  • 🎟️ Validación de cupones - Verificación de códigos de cupones en tiempo real

✨ Conceptos Clave​

¿Qué es un Descuento?​

Un Descuento es una regla de precios que reduce el costo de productos o pedidos:

  • Tipo de Descuento - Porcentaje (por ejemplo, 20%) o monto fijo (por ejemplo, $10)
  • Valor del Descuento - La cantidad o porcentaje a reducir
  • Marcador - Identificador único para filtrar y referenciar
  • Período de Validez - Fechas de inicio y fin opcionales
  • Código de Cupón - Código promocional opcional para descuentos activados por el cliente

Estructura del Descuento​

Cada descuento tiene esta estructura:

{
  id: 1,
  identifier: 'summer_sale',
  localizeInfos: {
    title: 'Summer Sale'
  },
  discountType: 'percentage',
  discountValue: 20,
  isActive: true,
  validFrom: '2025-06-01T00:00:00.000Z',
  validTo: '2025-08-31T23:59:59.999Z',
}

Tipos de Descuentos​

TipoDescripciónEjemplo
porcentajeReducir el precio por un porcentaje20% de descuento en todos los artículos de verano
fijoReducir el precio por un monto fijo$10 de descuento en pedidos superiores a $50

Operaciones Comunes de Descuentos​

OperaciónDescripciónCaso de Uso Ejemplo
Obtener Todos los DescuentosListar todos los descuentos disponiblesGestión de descuentos en administración
Obtener Descuento por MarcadorObtener un descuento específicoMostrar insignia de descuento
Validar CupónVerificar si un código de cupón es válidoCampo de cupón en el proceso de pago

¿Por qué usar el módulo de Descuentos?​

BeneficioDescripción
Promociones AutomatizadasSin edición manual de precios para cada venta
Gestión de CuponesCrear, distribuir y validar códigos promocionales
Reglas FlexiblesDescuentos por porcentaje, fijo, por categoría o para clientes
Ofertas Limitadas en el TiempoProgramar campañas con fechas de inicio/fin
Soporte MultilingüeNombres de descuentos localizados por idioma

📋 Lo Que Necesitas Saber​

Los Descuentos se Crean en el Panel de Administración​

No puedes crear descuentos a través del SDK - se crean en el panel de administración de OneEntry.

Proceso de Creación:

  • Proporcionar un Nombre - Designación del descuento (requerido)
  • Proporcionar un Marcador - Identificador único (requerido)
  • Seleccionar Tipo de Descuento - Porcentaje o monto fijo
  • Establecer Valor del Descuento - La cantidad de reducción
  • Opcionalmente establecer Período de Validez - Fechas de inicio y fin

Validación de Cupones​

Usa validateDiscountsCoupon() en el proceso de pago para verificar códigos de cupones en tiempo real antes de aplicarlos a un pedido.

💡 Notas Importantes​

Los Descuentos se Crean en el Panel de Administración​

El módulo de Descuentos maneja:

  • ✅ Obtener todos los descuentos activos
  • ✅ Recuperar un descuento específico por marcador
  • ✅ Validar códigos de cupones en el proceso de pago
  • ❌ NO crea ni modifica descuentos (usa el panel de administración)

Tu responsabilidad:

  • Mostrar insignias de descuento en listados de productos
  • Aplicar campos de entrada de cupones en el proceso de pago
  • Mostrar totales de descuento en el resumen del carrito/pedido

📊 Tabla de Referencia Rápida​

MétodoDescripción
getAllDiscounts()Obtener todos los descuentos
getDiscountByMarker()Obtener un solo descuento por marcador
validateDiscountsCoupon()Validar un código de cupón de descuento

❓ Preguntas Comunes (FAQ)​

¿Cómo aplico un descuento en el proceso de pago?​

Obtén el descuento usando getDiscountByMarker() o valida un código de cupón con validateDiscountsCoupon(). Usa el valor de descuento devuelto para calcular el precio reducido en el lado del cliente antes de crear el pedido.

¿Puede un descuento tener una fecha de expiración?​

¡Sí! Los descuentos pueden tener campos opcionales validFrom y validTo. Verifica estos campos al mostrar descuentos para asegurarte de que estén actualmente activos.

¿Cómo muestro insignias de descuento en los productos?​

Obtén todos los descuentos con getAllDiscounts(), luego empareja los descuentos con los productos según tu lógica de negocio. Renderiza una insignia usando el localizeInfos.title del descuento y el discountValue.

¿Qué sucede si un código de cupón es inválido?​

validateDiscountsCoupon() devuelve false si el cupón no existe o ha expirado. Muestra un mensaje de error apropiado al cliente.

🎓 Mejores Prácticas​

  • Almacena en caché los descuentos al cargar - Cambian con poca frecuencia; evita llamadas repetidas a la API
  • Valida cupones del lado del servidor - Siempre verifica antes de aplicar a un pedido
  • Muestra el descuento claramente - Muestra los precios originales y descontados juntos
  • Maneja descuentos expirados - Verifica validTo antes de mostrar un descuento
  • Usa marcadores descriptivos - summer_sale_2025, no discount1
  • Localiza los nombres de los descuentos - Usa localizeInfos para soporte multilingüe

Más información sobre la interfaz de usuario del módulo https://doc.oneentry.cloud/docs/category/discounts

Definición del módulo de Descuentos​


const { Discounts } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

🔗 Documentación Relacionada​