Discounts

El módulo Discounts te permite leer descuentos, validar cupones y consultar el saldo de bonificaciones del usuario.

Más información sobre la interfaz de usuario del módulo: https://doc.oneentry.cloud/docs/category/discounts (abre en una nueva pestaña)

---

Usa este módulo para obtener descuentos y validar códigos de cupón: rebajas porcentuales o de importe fijo, acumulación de puntos de bonificación y descuentos personales. Las reglas de descuento se definen en el panel de administración de OneEntry. El módulo las obtiene, valida los cupones al finalizar la compra y lee el saldo y el historial de bonificaciones del usuario actual.

El SDK es de solo lectura. No puedes crear ni modificar descuentos con él; eso se hace en el panel de administración. Al crear un descuento allí, defines 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 periodo de validez opcional (startDate / endDate) y condiciones opcionales.

Inicio rápido

Inicializa el módulo desde defineOneEntry:

const {  } = defineOneEntry(
  , {
    
  }
);

Valida un código de cupón al finalizar la compra y lee el resultado:

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

if ('statusCode' in result) {
  console.error(result.message); // IError: the request failed
} else if (result.valid) {
  console.log("Coupon applied:", result.coupon);
} else {
  console.log("Invalid coupon:", result.error); // e.g. "Coupon not found"
}

Objeto de descuento

Un descuento (IDiscountsEntity) es una regla de precios que reduce el coste de los productos o los pedidos:

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

{
  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: [
    { id: 1, conditionType: 'MIN_CART_AMOUNT', entityIds: null, value: { amount: 50 } }
  ]
}

Tipos de descuento

El campo type clasifica el descuento:

type	Descripción
DISCOUNT	Descuento estándar aplicado a productos/pedidos
BONUS	Acumulación de puntos de bonificación (fidelización)
PERSONAL_DISCOUNT	Descuento dirigido a usuarios o grupos concretos

La forma de calcular la rebaja se define en discountValue.discountType:

discountValue.discountType	Descripción	Ejemplo
PERCENT	Reduce el precio en un porcentaje	20 % de descuento en todos los artículos de verano
FIXED_AMOUNT	Reduce el precio en un importe fijo	10 $ de descuento en pedidos de más de 50 $

---

Métodos

Método	Descripción
getAllDiscounts()	Obtener todos los descuentos
getDiscountByMarker()	Obtener un único descuento por marcador
validateDiscountsCoupon()	Validar un código de cupón de descuento
getBonusBalance()	Obtener el saldo de bonificaciones del usuario actual
getBonusHistory()	Obtener el historial de transacciones de bonificación del usuario actual
getDiscountsByVectorSearch()	Busca descuentos por significado (búsqueda vectorial)

Aplicar un descuento al finalizar la compra

Valida el código que introduce el cliente con validateDiscountsCoupon() y después pásalo como couponCode a Orders.previewOrder() para obtener los totales con descuento, y a Orders.createOrder() al realizar el pedido. Para aplicar un descuento sin cupón, pasa su marcador en additionalDiscountsMarkers. La plataforma aplica los descuentos y cupones al calcular el pedido, así que no recalcules los precios en el cliente. Usa getDiscountByMarker() solo para mostrar un descuento (por ejemplo, su discountValue). createOrder() requiere autorización del usuario.

validateDiscountsCoupon() devuelve un ICouponValidationResult: { valid: boolean; coupon?; error? }. Si el cupón no existe o un cupón de un solo uso ya se ha usado, valid es false y error contiene el motivo (por ejemplo, "Coupon not found"). La validación del cupón no comprueba startDate/endDate del descuento, así que compruébalos tú mismo (consulta Periodo de validez).

Periodo de validez

startDate y endDate son opcionales. Compruébalos antes de mostrar un descuento, para mostrar solo los descuentos que están activos en ese momento.

Insignias de descuento en los productos

Obtén todos los descuentos con getAllDiscounts(), asócialos a los productos con tu propia lógica de negocio y muestra una insignia a partir de localizeInfos.title y discountValue.value. Los descuentos cambian poco, así que almacénalos en caché al cargar en lugar de llamar a la API repetidamente. Para los nombres multilingües, usa localizeInfos.

---

Relacionado

• Products: productos a los que se aplican los descuentos
• Orders: previsualizar y crear pedidos con los descuentos aplicados
• Payments: pagos de pedidos con descuento
• Locales: nombres de descuentos multilingües

---