API Xử lý Voucher tại Quầy

Tài liệu này mô tả các endpoint cho phép nhân viên thu ngân kiểm tra tính hợp lệ và quy đổi (redeem) voucher của khách hàng trực tiếp tại quầy thanh toán.

Quy trình Xử lý Voucher tại Quầy

1. Kiểm tra (Validate): Thu ngân quét mã QR voucher trên máy khách hoặc nhập mã code thủ công. Hệ thống đối chiếu điều kiện áp dụng (thời hạn, hạng thành viên, giá trị đơn tối thiểu, số lần dùng còn lại) và tính trước số tiền giảm giá.
2. Quy đổi (Redeem): Khi khách đồng ý thanh toán, thu ngân xác nhận áp dụng voucher vào hoá đơn (order reference từ POS). Hệ thống trừ lượt sử dụng và ghi nhận bản ghi voucher_redemptions.

---

1. Kiểm tra Tính Hợp lệ của Voucher

Dùng để xác thực voucher trước khi áp dụng vào hoá đơn. Có thể truyền thêm số tiền đơn hàng (order_amount) để hệ thống kiểm tra điều kiện giá trị đơn hàng tối thiểu và tính toán số tiền chiết khấu thực tế.

• Method: POST
• Endpoint: /api/{locale}/v1/staff/vouchers/validate
• Auth: auth:staff_api (Bearer Token)

Request Body

Trường	Kiểu	Bắt buộc	Mô tả
code	string	Có	Mã voucher (không phân biệt chữ hoa/thường).
member_id	string	Có	UUID, số điện thoại, hoặc unique_identifier của khách hàng.
order_amount	integer	Không	Tổng giá trị đơn hàng trước giảm giá (theo VNĐ) để kiểm tra hạn mức tối thiểu.

{
  "code": "GIAM50K",
  "member_id": "019b8d48-97df-7177-8aa0-47f2107a8eb3",
  "order_amount": 450000
}

Response Thành công - Hợp lệ

{
  "valid": true,
  "voucher": {
    "id": "019b8d49-vch-001",
    "code": "GIAM50K",
    "title": "Giảm 50.000đ cho đơn từ 300.000đ",
    "type": "fixed_amount",
    "value": 50000,
    "min_purchase_amount": 300000,
    "valid_until": "2026-06-30T23:59:59.000000Z"
  },
  "error_code": null,
  "error_message": null,
  "discount_amount": 50000,
  "capped": false,
  "original_amount": 450000,
  "final_amount": 400000,
  "member": {
    "id": "019b8d48-97df-7177-8aa0-47f2107a8eb3",
    "name": "Nguyễn Văn A",
    "phone": "0901234567"
  }
}

Response Khi Không Hợp lệ

Nếu voucher không đủ điều kiện, API trả về mã lỗi và thông báo chi tiết:

{
  "valid": false,
  "voucher": null,
  "error_code": "minimum_not_met",
  "error_message": "Yêu cầu đơn hàng tối thiểu 300.000 ₫.",
  "discount_amount": null,
  "minimum_required": 300000,
  "member": {
    "id": "019b8d48-97df-7177-8aa0-47f2107a8eb3",
    "name": "Nguyễn Văn A"
  }
}

Các mã error_code thường gặp:

Mã lỗi	Mô tả
invalid_code	Mã voucher không tồn tại trong hệ thống chi nhánh.
inactive	Voucher hiện đang tạm ngừng áp dụng.
not_yet_valid	Voucher chưa đến ngày bắt đầu có hiệu lực.
expired	Voucher đã quá hạn sử dụng.
exhausted	Voucher đã hết tổng số lượt phát hành toàn hệ thống.
member_limit_reached	Khách hàng đã dùng hết số lượt cho phép của cá nhân.
tier_restricted	Hạng thành viên của khách không đủ điều kiện áp dụng voucher.
minimum_not_met	Giá trị đơn hàng chưa đạt mức tối thiểu.
single_use	Voucher này là loại dùng một lần và đã được sử dụng trước đó.

---

2. Áp dụng Quy đổi Voucher

Ghi nhận voucher đã được áp dụng vào giao dịch thanh toán. Thao tác này sẽ trừ lượt sử dụng của voucher và liên kết với mã hoá đơn CukCuk POS.

• Method: POST
• Endpoint: /api/{locale}/v1/staff/vouchers/{voucherId}/redeem
• Auth: auth:staff_api (Bearer Token)

Path Parameters

Tham số	Kiểu	Bắt buộc	Mô tả
voucherId	string	Có	UUID của Voucher cần quy đổi.

Request Body

Trường	Kiểu	Bắt buộc	Mô tả
member_id	string	Có	UUID hoặc SĐT của hội viên sử dụng.
order_amount	integer	Không	Tổng giá trị hoá đơn (VNĐ).
order_reference	string	Không	Mã hoá đơn hoặc số phiếu thanh toán trên POS MISA CukCuk.

{
  "member_id": "019b8d48-97df-7177-8aa0-47f2107a8eb3",
  "order_amount": 450000,
  "order_reference": "HD-CUKCUK-2026-0520-0089"
}

Response Thành công

{
  "success": true,
  "message": "Áp dụng voucher thành công",
  "discount_applied": 50000,
  "redemption_id": "019b8d49-rdm-7788-99aa-123456789abc"
}

Response Thất bại

{
  "success": false,
  "message": "Voucher này đã hết lượt sử dụng."
}