Saltar al contenido principal

Introducción

El módulo de Descuentos te permite gestionar y aplicar descuentos a productos y pedidos.

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

🎯 ¿Qué hace este módulo?​

El módulo de Descuentos te permite obtener descuentos y validar códigos de cupones — reducciones porcentuales o de cantidad fija, acumulación de puntos de bonificación y descuentos personales. Definís las reglas de descuento en el panel de administración de OneEntry; este módulo las recupera, valida los cupones en el proceso de pago y lee el saldo de bonificación y el historial del usuario actual.

El SDK es solo de lectura: los descuentos se crean y configuran en el panel de administración.

🚀 Inicio Rápido​

Inicializa el módulo desde defineOneEntry:


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

Valida un código de cupón en el proceso de pago y lee el resultado:

// Validate a coupon code entered by the customer.
const result = await Discounts.validateDiscountsCoupon("SUMMER20");

if (result.valid) {
  console.log("Coupon applied:", result.coupon);
} else {
  console.log("Invalid coupon:", result.error);
}

✨ Conceptos Clave​

¿Qué es un Descuento?​

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

  • type — DISCOUNT, BONUS, o PERSONAL_DISCOUNT
  • discountValue — cómo se calcula la reducción: discountType (PERCENT o FIXED_AMOUNT), un value numérico, una applicability (TO_PRODUCT o TO_ORDER), y un maxAmount opcional
  • identifier — marcador único para filtrar y referenciar
  • startDate / endDate — período de validez opcional
  • conditions — reglas que deciden cuándo se aplica el descuento (por producto, categoría, monto del carrito, usuario, …)

Estructura del Descuento​

{
  id: 1,
  identifier: 'summer_sale',
  localizeInfos: {
    title: 'Summer Sale'
  },
  type: 'DISCOUNT',
  startDate: '2025-06-01T00:00:00.000Z',
  endDate: '2025-08-31T23:59:59.999Z',
  discountValue: {
    applicability: 'TO_ORDER',
    discountType: 'PERCENT',
    value: 20,
    maxAmount: 100
  },
  conditionLogic: 'AND',
  conditions: [
    { type: 'MIN_CART_AMOUNT', value: '50' }
  ]
}

Tipos de Descuento​

El campo type clasifica el descuento:

typeDescripción
DISCOUNTDescuento estándar aplicado a productos/pedidos
BONUSAcumulación de puntos de bonificación (lealtad)
PERSONAL_DISCOUNTDescuento dirigido a usuarios o grupos específicos

Cómo se calcula la reducción se encuentra en discountValue.discountType:

discountValue.discountTypeDescripciónEjemplo
PERCENTReducir el precio en un porcentaje20% de descuento en todos los artículos de verano
FIXED_AMOUNTReducir el precio en una cantidad fija$10 de descuento en pedidos superiores a $50

📋 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. Al crear uno, proporcionas un Nombre, un Marcador (identifier), un tipo (DISCOUNT, BONUS, o PERSONAL_DISCOUNT), un discountValue (PERCENT o FIXED_AMOUNT más el value numérico), un período de validez opcional (startDate / endDate), y condiciones opcionales.

Lo que hace el módulo​

  • ✅ Obtener todos los descuentos — getAllDiscounts()
  • ✅ Recuperar un descuento específico por marcador — getDiscountByMarker()
  • ✅ Validar códigos de cupones en el proceso de pago — validateDiscountsCoupon()
  • ✅ Leer el saldo de bonificación y el historial del usuario actual
  • ❌ No crea ni modifica descuentos (usa el panel de administración)

📊 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
getBonusBalance()Obtener el saldo de bonificación del usuario actual
getBonusHistory()Obtener el historial de transacciones de bonificación del usuario actual

❓ Preguntas Comunes (FAQ)​

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

Obtén el descuento con getDiscountByMarker() o valida un cupón con validateDiscountsCoupon(), luego usa el valor de descuento devuelto para calcular el precio reducido.

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

Sí. Los descuentos pueden tener campos opcionales startDate y endDate — revísalos antes de mostrar un descuento para asegurarte de que esté actualmente activo.

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

Obtén todos los descuentos con getAllDiscounts(), emparejalos con los productos según tu lógica de negocio y renderiza una insignia a partir de localizeInfos.title y discountValue.value.

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

validateDiscountsCoupon() devuelve un ICouponValidationResult — { valid: boolean; coupon?; error? }. Cuando el cupón no existe o ha expirado, valid es false y se proporciona un mensaje de error. Verifica result.valid y muestra un mensaje apropiado.

🎓 Mejores Prácticas​

  • Cachea los descuentos al cargar — cambian con poca frecuencia; evita llamadas repetidas a la API.
  • Valida los cupones antes de aplicar — siempre llama a validateDiscountsCoupon() antes de fijar el precio de un pedido.
  • Maneja los descuentos expirados — verifica endDate 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.

🔗 Documentación Relacionada​