Chuyển đến nội dung chính

Giới thiệu

Mô-đun Giảm giá cho phép bạn quản lý và áp dụng giảm giá cho sản phẩm và đơn hàng

Thông tin thêm về giao diện người dùng của mô-đun https://doc.oneentry.cloud/docs/category/discounts

🎯 Mô-đun này làm gì?​

Mô-đun Giảm giá cho phép bạn lấy giảm giá và xác thực mã coupon — giảm giá theo phần trăm hoặc số tiền cố định, tích lũy điểm thưởng và giảm giá cá nhân. Bạn định nghĩa các quy tắc giảm giá trong bảng điều khiển quản trị OneEntry; mô-đun này sẽ lấy chúng, xác thực mã coupon tại thanh toán và đọc số dư điểm thưởng và lịch sử của người dùng hiện tại.

SDK là chỉ đọc: giảm giá được tạo và cấu hình trong bảng điều khiển quản trị.

🚀 Bắt đầu nhanh​

Khởi tạo mô-đun từ defineOneEntry:


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

Xác thực mã coupon tại thanh toán và đọc kết quả:

// 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);
}

✨ Khái niệm chính​

Giảm giá là gì?​

Một Giảm giá (IDiscountsEntity) là một quy tắc giá cả làm giảm chi phí của sản phẩm hoặc đơn hàng:

  • type — DISCOUNT, BONUS, hoặc PERSONAL_DISCOUNT
  • discountValue — cách tính toán mức giảm: discountType (PERCENT hoặc FIXED_AMOUNT), một giá trị số, một applicability (TO_PRODUCT hoặc TO_ORDER), và một maxAmount tùy chọn
  • identifier — dấu hiệu duy nhất để lọc và tham chiếu
  • startDate / endDate — thời gian hiệu lực tùy chọn
  • conditions — các quy tắc quyết định khi nào giảm giá được áp dụng (theo sản phẩm, danh mục, số tiền giỏ hàng, người dùng, …)

Cấu trúc Giảm giá​

{
  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' }
  ]
}

Các loại Giảm giá​

Trường type phân loại giảm giá:

typeMô tả
DISCOUNTGiảm giá tiêu chuẩn áp dụng cho sản phẩm/đơn hàng
BONUSTích lũy điểm thưởng (khách hàng thân thiết)
PERSONAL_DISCOUNTGiảm giá nhắm đến người dùng hoặc nhóm cụ thể

Cách tính toán mức giảm nằm trong discountValue.discountType:

discountValue.discountTypeMô tảVí dụ
PERCENTGiảm giá theo phần trămGiảm 20% cho tất cả sản phẩm mùa hè
FIXED_AMOUNTGiảm giá theo số tiền cố địnhGiảm $10 cho đơn hàng trên $50

📋 Những điều bạn cần biết​

Giảm giá được tạo trong bảng điều khiển quản trị​

Bạn không thể tạo giảm giá qua SDK — chúng được tạo trong bảng điều khiển quản trị OneEntry. Khi tạo một cái, bạn cung cấp một Tên, một Dấu hiệu (identifier), một loại (DISCOUNT, BONUS, hoặc PERSONAL_DISCOUNT), một discountValue (PERCENT hoặc FIXED_AMOUNT cộng với giá trị số), một thời gian hiệu lực tùy chọn (startDate / endDate), và các điều kiện tùy chọn.

Những gì mô-đun làm​

  • ✅ Lấy tất cả giảm giá — getAllDiscounts()
  • ✅ Lấy một giảm giá cụ thể theo dấu hiệu — getDiscountByMarker()
  • ✅ Xác thực mã coupon tại thanh toán — validateDiscountsCoupon()
  • ✅ Đọc số dư điểm thưởng và lịch sử của người dùng hiện tại
  • ❌ Không tạo hoặc sửa đổi giảm giá (sử dụng bảng điều khiển quản trị)

📊 Bảng tham khảo nhanh​

Phương thứcMô tả
getAllDiscounts()Lấy tất cả giảm giá
getDiscountByMarker()Lấy một giảm giá đơn lẻ theo dấu hiệu
validateDiscountsCoupon()Xác thực mã coupon giảm giá
getBonusBalance()Lấy số dư điểm thưởng của người dùng hiện tại
getBonusHistory()Lấy lịch sử giao dịch điểm thưởng của người dùng hiện tại

❓ Câu hỏi thường gặp (FAQ)​

Làm thế nào để áp dụng giảm giá tại thanh toán?​

Lấy giảm giá với getDiscountByMarker() hoặc xác thực một coupon với validateDiscountsCoupon(), sau đó sử dụng giá trị giảm giá trả về để tính toán giá đã giảm.

Giảm giá có thể có ngày hết hạn không?​

Có. Giảm giá có thể có các trường startDate và endDate tùy chọn — kiểm tra chúng trước khi hiển thị một giảm giá để đảm bảo nó đang hoạt động.

Làm thế nào để hiển thị huy hiệu giảm giá trên sản phẩm?​

Lấy tất cả giảm giá với getAllDiscounts(), khớp chúng với sản phẩm theo logic kinh doanh của bạn, và hiển thị một huy hiệu từ localizeInfos.title và discountValue.value.

Điều gì xảy ra nếu mã coupon không hợp lệ?​

validateDiscountsCoupon() trả về một ICouponValidationResult — { valid: boolean; coupon?; error? }. Khi coupon không tồn tại hoặc đã hết hạn, valid là false và một thông báo error được cung cấp. Kiểm tra result.valid và hiển thị một thông điệp phù hợp.

🎓 Thực hành tốt nhất​

  • Lưu cache giảm giá khi tải — chúng thay đổi không thường xuyên; tránh gọi API lặp lại.
  • Xác thực coupon trước khi áp dụng — luôn gọi validateDiscountsCoupon() trước khi định giá một đơn hàng.
  • Xử lý giảm giá đã hết hạn — kiểm tra endDate trước khi hiển thị một giảm giá.
  • Sử dụng dấu hiệu mô tả — summer_sale_2025, không phải discount1.
  • Địa phương hóa tên giảm giá — sử dụng localizeInfos để hỗ trợ đa ngôn ngữ.

🔗 Tài liệu liên quan​