Skip to main content

Tài liệu chuẩn bị tích hợp POS - Golden Lotus Member App

Phiên bản: 1.0
Ngày lập: 07/07/2026
Dự án: Golden Lotus Member App + Loyalty Backend
Mục đích: Xác định rõ phạm vi, luồng dữ liệu và các câu hỏi cần thống nhất trước khi bắt đầu tích hợp hệ thống POS.

1. Tổng quan​

Hệ thống hiện tại đã hoàn thiện backend loyalty gồm:

  • Quản lý hội viên: đăng ký, đăng nhập, hạng thẻ (Silver/Gold/Platinum...), lịch sử điểm.
  • Quản lý điểm: tích điểm, trừ điểm, hết hạn, chuyển điểm.
  • Voucher: đổi điểm lấy voucher, quét QR sử dụng tại quầy.
  • Booking dịch vụ: khách đặt lịch dịch vụ qua app.
  • Chi nhánh & dịch vụ: quản lý chi nhánh, nhóm dịch vụ, giá, thờI lượng.
  • Thông báo: push notification qua Expo/Firebase.

Việc còn lại để đưa vào vận hành thực tế là tích hợp hai chiều với hệ thống POS tại quầy thu ngân.

2. Các luồng dữ liệu cần tích hợp​

2.1. Đồng bộ khách hàng / hội viên (App ↔ POS)​

HướngMô tả
App → POSKhi khách đăng ký tài khoản trên app, thông tin cần đẩy xuống POS để thu ngân có thể tra cứu bằng SĐT/mã member/QR.
POS → AppKhi thu ngân tạo hoặc cập nhật khách hàng trên POS, thông tin cần đồng bộ ngược lên hệ thống loyalty.

Thông tin đồng bộ:

  • Mã khách hàng duy nhất (externalPosId)
  • Số điện thoại, email, họ tên
  • Ngày sinh, giới tính (nếu có)
  • Hạng thẻ hiện tại
  • Số điểm hiện có

2.2. Đồng bộ danh mục dịch vụ & sản phẩm (POS → App)​

  • Danh mục chi nhánh
  • Danh mục nhóm dịch vụ
  • Danh mục dịch vụ/sản phẩm: tên, mã SKU, giá, thờI lượng
  • Danh mục loại thẻ hội viên
  • Danh mục voucher/chương trình khuyến mãi

2.3. Đồng bộ danh mục từ Loyalty CMS xuống POS (App → POS)​

  • Chương trình khuyến mãi / ưu đãi
  • Voucher được phát hành trên app
  • Banner / bài viết / event (nếu POS cần hiển thị)

2.4. Tích điểm khi mua hàng tại POS (POS → App)​

  • Khách mở app → hiển thị QR Member.
  • Thu ngân quét QR hoặc nhập SĐT để tra cứu.
  • POS xử lý thanh toán.
  • Sau khi thanh toán thành công, POS gửi giao dịch lên hệ thống loyalty.
  • Hệ thống tự động tính điểm thưởng theo hạng thẻ và cập nhật về app.

2.5. Mua hàng / booking trên App đồng bộ xuống POS (App → POS)​

  • Khách đặt lịch dịch vụ hoặc mua voucher trên app.
  • Dữ liệu booking/voucher cần đồng bộ xuống POS để thu ngân xác nhận khi khách đến.
  • Voucher có thể quét QR tại quầy để kiểm tra tính hợp lệ.

3. Data contract đề xuất​

3.1. Khách hàng / Hội viên​

{
  "externalPosId": "POS-KH-001",
  "phoneNumber": "0901234567",
  "emailAddress": "khach@example.com",
  "firstName": "Nguyễn",
  "lastName": "Văn A",
  "birthDate": "1990-05-15",
  "tierCode": "GOLD",
  "currentPoints": 12500,
  "source": "POS|APP|ADMIN"
}

3.2. Dịch vụ / Sản phẩm​

{
  "sku": "GL-BODY-MASSAGE-60",
  "name": "Body Massage 60 phút",
  "category": "Massage",
  "group": "Body Massage",
  "price": 395000,
  "currencyCode": "VND",
  "durationMinutes": 60,
  "branchCode": "GL-D7",
  "enabled": true
}

3.3. Giao dịch / Đơn hàng từ POS​

{
  "posOrderId": "POS-ORD-20260707-0001",
  "externalPosId": "POS-KH-001",
  "phoneNumber": "0901234567",
  "branchCode": "GL-D7",
  "orderDate": "2026-07-07T14:30:00+07:00",
  "paymentMethod": "CASH|CARD|TRANSFER",
  "totalAmount": 790000,
  "items": [
    {
      "sku": "GL-BODY-MASSAGE-60",
      "quantity": 2,
      "unitPrice": 395000,
      "lineTotal": 790000
    }
  ],
  "voucherCode": "HW50-XXXXXX",
  "discountAmount": 0
}

3.4. Kết quả tích điểm trả về POS​

{
  "customerId": "12345",
  "externalPosId": "POS-KH-001",
  "earnedPoints": 790,
  "currentPoints": 13290,
  "tierCode": "GOLD",
  "message": "Tích thành công 790 điểm"
}

3.5. Voucher​

{
  "code": "HW50-XXXXXX",
  "voucherDefinitionCode": "HW50",
  "customerId": "12345",
  "status": "ACTIVE|USED|EXPIRED|CANCELLED",
  "expiresAt": "2026-08-07T23:59:59+07:00"
}

4. API / Webhook cần thiết​

4.1. Nếu POS chủ động gọi lên Cloud (khuyên dùng)​

EndpointMục đích
POST /pos/customer/lookupTìm khách hàng theo SĐT, mã member hoặc QR
POST /pos/customer/syncPOS đẩy thông tin khách hàng mới/cập nhật
POST /pos/transactionPOS gửi giao dịch sau thanh toán
POST /pos/voucher/validateKiểm tra voucher có hợp lệ không
POST /pos/voucher/redeemĐánh dấu voucher đã sử dụng
GET /pos/productsLấy danh sách dịch vụ/sản phẩm từ loyalty
GET /pos/customer/{id}/pointsLấy số điểm hiện tại của khách

4.2. Nếu Cloud chủ động đẩy xuống POS​

WebhookMô tả
POST {posUrl}/webhook/customerĐẩy thông tin khách hàng mới/cập nhật
POST {posUrl}/webhook/voucherĐẩy voucher mới phát hành
POST {posUrl}/webhook/bookingĐẩy booking mới từ app
POST {posUrl}/webhook/productĐẩy cập nhật danh mục dịch vụ

Khuyến nghị: Sử dụng kết hợp cả hai: POS gọi API cho giao dịch real-time, Cloud push webhook cho cập nhật danh mục.

5. Các câu hỏi cần khách hàng xác nhận​

Về POS hiện tại​

  1. POS vendor là hãng nào? (KiotViet, Sapo, POS do nội bộ phát triển, v.v.)
  2. POS đã có API sẵn chưa, hay cần bên bạn cung cấp API?
  3. POS có thể gọi API ra ngoài Internet không, hay chỉ chạy trong mạng nội bộ?
  4. POS có khả năng quét QR từ điện thoại không?

Về định danh khách hàng​

  1. POS hiện đang dùng mã khách hàng như thế nào? (SĐT, mã tự sinh, mã thẻ vật lý...)
  2. Có cần import danh sách khách hàng cũ từ POS sang loyalty không?
  3. Nếu khách đã có trên POS nhưng chưa có trên app, có cho phép đăng ký app tự động link không?

Về luồng giao dịch​

  1. POS sẽ gửi giao dịch lên Cloud ngay sau thanh toán hay batch cuối ngày?
  2. Có cần tích điểm ngay lập tức tại quầy để khách nhìn thấy trên app không?
  3. Nếu giao dịch bị hoàn tiền/hủy, điểm đã tích có cần thu hồi không?

Về danh mục​

  1. Dịch vụ/sản phẩm sẽ được quản lý trên POS hay trên hệ thống loyalty?
  2. Giá dịch vụ có khác nhau giữa các chi nhánh không?
  3. Có voucher/điểm/chương trình khuyến mãi nào đang chạy trên POS cũ cần giữ lại không?

Về voucher​

  1. Voucher trên app sẽ được POS kiểm tra online hay offline?
  2. Khi khách dùng voucher, POS có cần trừ tiền ngay trên hóa đơn không?

6. Checklist chuẩn bị trước khi có POS​

Phía bên phát triển (đã sẵn sàng hoặc cần hoàn thiện)​

  • Hoàn thiện master data: chi nhánh, dịch vụ, hạng thẻ, voucher, khách hàng.
  • Xây dựng POS Adapter abstraction + Mock POS adapter để test nội bộ.
  • Implement QR Member cho app hiển thị.
  • Implement API lookup khách hàng cho POS.
  • Implement API nhận giao dịch từ POS + tự động tính điểm.
  • Implement API validate/redeem voucher cho POS.
  • Viết tài liệu API spec chi tiết (OpenAPI/Swagger).
  • Chuẩn bị test data và test scenarios.

Phía khách hàng / POS vendor​

  • Cung cấp thông tin POS vendor và khả năng tích hợp.
  • Cung cấp sample data khách hàng, dịch vụ, giao dịch.
  • Xác nhận luồng đồng bộ: POS push hay Cloud pull hay hybrid.
  • Cung cấp môi trường test/staging của POS (nếu có).
  • Thống nhất định dạng mã khách hàng, mã đơn hàng, mã voucher.

7. Phụ lục: Ví dụ luồng tích điểm tại quầy​

1. Khách đưa QR Member trên app cho thu ngân.
2. POS quét QR → gọi POST /pos/customer/lookup → nhận thông tin KH + điểm.
3. Thu ngân thêm dịch vụ vào hóa đơn POS.
4. Khách thanh toán tại POS.
5. POS gọi POST /pos/transaction với thông tin hóa đơn.
6. Cloud tính điểm thưởng theo hạng thẻ → cộng điểm.
7. Cloud trả kết quả về POS (điểm đã tích, tổng điểm hiện tại).
8. Khách mở app → thấy điểm và hạng thẻ đã cập nhật.

8. Liên hệ​

Nếu có bất kỳ thắc mắc hoặc cần bổ sung thông tin, vui lòng phản hồi để hai bên thống nhất trước khi triển khai.