Chuyển tới nội dung chính

API Quét QR & Tra cứu Hội viên tại Quầy

Đây là nghiệp vụ cốt lõi hàng ngày của nhân viên thu ngân và phục vụ: quét mã QR của khách từ Member App hoặc tìm kiếm theo số điện thoại để tra cứu hạng thẻ, thông tin giới thiệu F1, lịch sử chi tiêu, món ăn yêu thích, ghi nhận lượt quay lại và cập nhật sở thích ẩm thực.

Nguồn dữ liệu & Cơ chế Tích luỹ
  • Mã QR hiển thị trên Member App có dạng: {baseUrl}/staff/earn/{memberIdentifier}/{cardUniqueIdentifier}. Camera trên ứng dụng Staff bóc tách chuỗi này và lấy {memberIdentifier} để tra cứu.
  • Hệ thống áp dụng mô hình Hạn mức chi tiêu (Spend Threshold) và Chia sẻ lợi nhuận (Profit Sharing) được đồng bộ từ POS MISA CukCuk. Không sử dụng Thẻ tích tem (Stamp Cards).

1. Tra cứu Hội viên từ Mã QR / Định danh​

Khi nhân viên dùng camera quét mã QR của khách, ứng dụng gọi endpoint này để tải hồ sơ khách hàng.

  • Method: GET
  • Endpoint: /api/{locale}/v1/staff/member/{identifier}
  • Auth: auth:staff_api (Bearer Token)

Path Parameters​

Tham sốKiểuBắt buộcMô tả
identifierstringCóMã UUID của Member, số điện thoại, email hoặc unique_identifier.

Response Thành công​

{
  "id": "019b8d48-97df-7177-8aa0-47f2107a8eb3",
  "name": "Nguyễn Văn A",
  "phone": "0901234567",
  "email": "nguyenvana@gmail.com",
  "birthday": "1995-08-15",
  "avatar": "https://api-zodutcan.datacomtech.vn/storage/avatars/user-1.jpg",
  "is_avatar_public": true,
  "rank": "Hạng Vàng (Gold)",
  "rank_color": "#F59E0B",
  "rank_icon": "🥇",
  "tier_name": "Hạng Vàng (Gold)",
  "tier_level": 2,
  "is_vip": true,
  "is_created_by_me": false,
  "preferences": [
    "Ít đá",
    "Không hành lá",
    "Ngồi gần cửa sổ"
  ],
  "is_birthday": false,
  "days_to_birthday": 45,
  "signed_up_at": "2026-01-10 09:30:00",
  "return_count": 14,
  "last_return_clicked_at": "2026-05-18 19:45:00",
  "today_reservations": [
    {
      "id": "019b8d49-bb12-7001-a123-001122334455",
      "booking_time": "2026-05-20T19:00:00.000000Z",
      "quantity": 4,
      "status": "confirmed",
      "table_name": "Bàn VIP 02"
    }
  ],
  "vouchers": [
    {
      "id": "019b8d49-vch-001",
      "code": "GIAM50K",
      "title": "Giảm 50.000đ cho hoá đơn từ 300.000đ",
      "type": "fixed_amount",
      "formatted_value": "50.000 ₫",
      "valid_until": "2026-06-30T23:59:59.000000Z",
      "is_used": false
    }
  ]
}

2. Kiểm tra Số điện thoại Khách tại Quầy​

Dùng cho tính năng nhập nhanh SĐT khi khách đọc số tại quầy hoặc trong luồng Check-in bàn vãng lai.

  • Method: POST
  • Endpoint: /api/{locale}/v1/staff/members/check-phone
  • Auth: auth:staff_api (Bearer Token)

Request Body​

{
  "phone": "0901234567"
}

Response Thành công - Đã có tài khoản​

{
  "found": true,
  "name": "Nguyễn Văn A",
  "avatar": "https://api-zodutcan.datacomtech.vn/storage/avatars/user-1.jpg",
  "is_avatar_public": true,
  "tier": "Hạng Vàng (Gold)",
  "rank": "Hạng Vàng (Gold)",
  "rank_color": "#F59E0B",
  "rank_icon": "🥇",
  "tier_level": 2,
  "is_vip": true,
  "is_active": true,
  "is_created_by_me": false,
  "preferences": ["Ít đá", "Không hành lá"],
  "today_reservations": [],
  "vouchers": [],
  "is_birthday": false,
  "days_to_birthday": 45,
  "birthday": "1995-08-15",
  "signed_up_at": "2026-01-10 09:30:00",
  "return_count": 14,
  "last_return_clicked_at": "2026-05-18 19:45:00"
}

Response - Chưa có tài khoản​

{
  "found": false
}

3. Danh sách Hội viên Quán Quản lý​

Hỗ trợ tìm kiếm, lọc theo hạng hội viên, sinh nhật, hoặc hội viên do chính nhân viên giới thiệu (F1).

  • Method: GET
  • Endpoint: /api/{locale}/v1/staff/members
  • Auth: auth:staff_api (Bearer Token)

Query Parameters​

Tham sốKiểuMô tả
qstringTìm kiếm theo tên hoặc số điện thoại (hỗ trợ nhập 3-4 số cuối).
filter_typestringBộ lọc: active, inactive, birthday (sinh nhật tuần này), vip, my_customers (F1 của nhân viên).
tier_idstringLọc theo ID phân hạng cụ thể.
sort_bystringnewest, oldest, name_asc, name_desc. Mặc định: newest.
limitintegerSố lượng bản ghi mỗi trang (mặc định: 20).
pageintegerSố trang hiện tại.

4. Chi tiết Hồ sơ Hội viên & Doanh số Mạng lưới​

Hiển thị toàn bộ thông tin tài chính, doanh số cá nhân và mạng lưới F1 của khách, danh sách người được giới thiệu, đặt bàn gần nhất và thông tin người bảo trợ.

  • Method: GET
  • Endpoint: /api/{locale}/v1/staff/members/{id}
  • Auth: auth:staff_api (Bearer Token)

Query Parameters​

Tham sốKiểuMặc địnhMô tả
f1_pageinteger1Số trang danh sách cấp dưới F1.
f1_limitinteger20Số lượng F1 mỗi trang.

Response Thành công​

{
  "id": "019b8d48-97df-7177-8aa0-47f2107a8eb3",
  "name": "Nguyễn Văn A",
  "phone": "0901234567",
  "email": "nguyenvana@gmail.com",
  "birthday": "1995-08-15",
  "rank": "Hạng Vàng (Gold)",
  "rank_color": "#F59E0B",
  "rank_icon": "🥇",
  "total_revenue": 54200000,
  "personal_revenue": 32000000,
  "f1_revenue": 22200000,
  "order_count": 18,
  "referrer_id": "019b8d48-upline-001",
  "referrer_name": "Trần Thị Trưởng Nhóm",
  "referrer_phone": "0988776655",
  "preferences": [
    "Ít cay",
    "Thích ngồi lầu 2"
  ],
  "f1_list": {
    "data": [
      {
        "id": "019b8d48-f1-0001",
        "name": "Lê Văn C",
        "phone": "0912345678",
        "avatar": null
      }
    ],
    "current_page": 1,
    "last_page": 1,
    "total": 1
  },
  "reservations": [
    {
      "id": "019b8d49-res-001",
      "booking_time": "2026-05-18T18:30:00Z",
      "quantity": 2,
      "status": "arrived"
    }
  ]
}

5. Món ăn Yêu thích của Khách​

Phân tích lịch sử gọi món từ các hoá đơn CukCuk POS trong 6 tháng gần nhất để gợi ý nhân viên tư vấn đúng khẩu vị của khách.

  • Method: GET
  • Endpoint: /api/{locale}/v1/staff/members/{id}/favorite-dishes
  • Auth: auth:staff_api (Bearer Token)

Query Parameters​

Tham sốKiểuMặc địnhMô tả
limitinteger5Số món ưa thích cần lấy (tối đa 10).

Response Thành công​

{
  "data": [
    {
      "dish_name": "Bò Fuji Nướng Đá Núi Lửa",
      "order_count": 9,
      "last_ordered_at": "2026-05-18"
    },
    {
      "dish_name": "Salad Rong Nho Cá Hồi",
      "order_count": 6,
      "last_ordered_at": "2026-05-10"
    }
  ]
}

6. Lịch sử Giao dịch của Hội viên​

Truy xuất dòng thời gian hợp nhất của hội viên gồm hoá đơn CukCuk (cá nhân và F1 phát sinh doanh số), voucher đã quy đổi và các khoản thưởng chia sẻ lợi nhuận.

  • Method: GET
  • Endpoint: /api/{locale}/v1/staff/members/{id}/transactions
  • Auth: auth:staff_api (Bearer Token)

Query Parameters​

Tham sốKiểuMô tả
typestringPhân loại: all (tất cả), purchase (hoá đơn POS), voucher_used (voucher), profit_sharing (thưởng chia sẻ).
limitintegerSố lượng bản ghi mỗi trang (mặc định: 20).
pageintegerSố trang cần xem.
monthstringLọc theo tháng định dạng YYYY-MM.

7. Ghi nhận Khách Ghé Quán​

Khi khách hàng đến quán trải nghiệm mà không có đặt bàn trước, nhân viên nhấn nút "Ghé quán" để tăng số lượt ghé thăm và cập nhật thời điểm tương tác gần nhất.

  • Method: POST
  • Endpoint: /api/{locale}/v1/staff/members/{id}/increment-return
  • Auth: auth:staff_api (Bearer Token)
Giới hạn Thao tác (Rate Limit)

Hệ thống cài đặt khoảng cách an toàn 2 giờ giữa 2 lần nhấn liên tiếp cho cùng một khách hàng để tránh thao tác nhầm hoặc spam số lượt. Nếu bấm trong thời gian chờ, API trả về 429 Too Many Requests.

Response Thành công​

{
  "message": "Đã cập nhật lượt quay lại thành công",
  "return_count": 15,
  "last_return_clicked_at": "2026-05-20 18:40:00"
}

8. Cập nhật Sở thích Ẩm thực​

Nhân viên ghi nhận thói quen ăn uống, dị ứng, khẩu vị của khách để phục vụ tốt hơn ở các lần sau.

  • Method: PATCH
  • Endpoint: /api/{locale}/v1/staff/members/{id}/preferences
  • Auth: auth:staff_api (Bearer Token)

Request Body​

{
  "preferences": [
    "Dị ứng đậu phộng",
    "Ăn thanh đạm, ít dầu mỡ",
    "Uống bia không đá"
  ]
}

Response Thành công​

{
  "message": "Preferences updated successfully",
  "preferences": [
    "Dị ứng đậu phộng",
    "Ăn thanh đạm, ít dầu mỡ",
    "Uống bia không đá"
  ]
}

9. Đăng ký Thành viên Mới tại Quầy​

Quy trình đăng ký hội viên trực tiếp tại quầy yêu cầu xác thực OTP số điện thoại trước khi lưu dữ liệu.

9.1 Gửi mã OTP xác thực SĐT​

  • Method: POST
  • Endpoint: /api/{locale}/v1/staff/members/otp/send
  • Auth: auth:staff_api
{
  "mobile": "0912345678"
}

9.2 Xác nhận mã OTP​

  • Method: POST
  • Endpoint: /api/{locale}/v1/staff/members/otp/verify
  • Auth: auth:staff_api
{
  "mobile": "0912345678",
  "otp": "123456"
}

9.3 Tạo hồ sơ Hội viên mới​

  • Method: POST
  • Endpoint: /api/{locale}/v1/staff/members
  • Auth: auth:staff_api (Yêu cầu quyền can_create_members: true)
{
  "name": "Hoàng Minh Tuấn",
  "phone": "0912345678",
  "email": "minhtuan@gmail.com",
  "birthday": "1998-12-15",
  "referrer_id": "019b8d48-97df-7177-8aa0-47f2107a8eb3",
  "current_residence": "Quận 1, TP. Hồ Chí Minh",
  "school": "Đại học Kinh Tế",
  "course": "K44"
}

Response Thành công​

{
  "message": "Member created successfully",
  "member": {
    "id": "019b8d49-mem-new-001",
    "name": "Hoàng Minh Tuấn",
    "phone": "+84912345678",
    "created_at": "2026-05-20T19:15:00Z"
  }
}

Ghi chú: Sau khi tạo thành công, Backend tự động đẩy Job đồng bộ khách hàng sang phần mềm MISA CukCuk POS.

10. Danh sách Hạng Thành viên​

Lấy danh sách các bậc phân hạng cấu hình cho chi nhánh để hiển thị bộ lọc hoặc đối chiếu quyền lợi.

  • Method: GET
  • Endpoint: /api/{locale}/v1/staff/members/tiers
  • Auth: auth:staff_api (Bearer Token)

Response Thành công​

{
  "data": [
    {
      "id": "019b8d48-tier-01",
      "name": "Thành viên Đồng",
      "level": 0,
      "color": "#CD7F32",
      "icon": "🥉"
    },
    {
      "id": "019b8d48-tier-02",
      "name": "Hạng Bạc (Silver)",
      "level": 1,
      "color": "#94A3B8",
      "icon": "🥈"
    },
    {
      "id": "019b8d48-tier-03",
      "name": "Hạng Vàng (Gold)",
      "level": 2,
      "color": "#F59E0B",
      "icon": "🥇"
    },
    {
      "id": "019b8d48-tier-04",
      "name": "Hạng Kim Cương (Diamond)",
      "level": 3,
      "color": "#06B6D4",
      "icon": "💎"
    }
  ]
}

11. Quản lý Danh sách Quét Gần đây​

Lưu tối đa 10 lượt khách quét gần nhất vào bộ nhớ meta của tài khoản nhân viên, cho phép truy cập lại nhanh chóng khi cần kiểm tra lại đơn hoặc sửa đổi.

11.1 Lấy danh sách khách quét gần đây​

  • Method: GET
  • Endpoint: /api/{locale}/v1/staff/recent-scans
  • Auth: auth:staff_api
{
  "recent_scans": [
    {
      "member_id": "019b8d48-97df-7177-8aa0-47f2107a8eb3",
      "name": "Nguyễn Văn A",
      "phone": "0901234567",
      "tier": "Hạng Vàng (Gold)",
      "scanned_at": "2026-05-20T18:30:00Z"
    }
  ]
}

11.2 Cập nhật danh sách khách quét gần đây​

  • Method: POST
  • Endpoint: /api/{locale}/v1/staff/recent-scans
  • Auth: auth:staff_api
{
  "recent_scans": [
    {
      "member_id": "019b8d48-97df-7177-8aa0-47f2107a8eb3",
      "name": "Nguyễn Văn A",
      "phone": "0901234567",
      "tier": "Hạng Vàng (Gold)",
      "scanned_at": "2026-05-20T18:30:00Z"
    }
  ]
}