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

API Điều hành Bàn & Quản lý Đặt bàn

Nhóm API này phục vụ công tác điều phối phục vụ tại chỗ của nhân viên thu ngân và phục vụ: theo dõi sơ đồ bàn theo thời gian thực từ POS MISA CukCuk, xem order món ăn đang phục vụ, phê duyệt yêu cầu đặt bàn từ User App, và thực hiện check-in xếp bàn cho khách vãng lai hoặc hội viên.

Nguồn Dữ liệu Trạng thái Bàn
  • Danh sách bàn và trạng thái chiếm dụng: Được đồng bộ trực tiếp từ bảng cukcuk_tables (nguồn chân lý từ CukCuk POS) kết hợp với các lượt check-in mới tạo trong vòng 2 phút để chống xung đột/trễ đồng bộ.
  • Tự động đóng phiên: Khi thu ngân in và thanh toán hoá đơn trên POS CukCuk, hệ thống POS sẽ tự động đồng bộ và đánh dấu hoàn tất (completed) phiên bàn trên hệ thống Loyalty.

1. Sơ đồ Bàn & Trạng thái Thực tế​

Lấy toàn bộ danh sách bàn của chi nhánh, kèm trạng thái bận/trống, cờ phát hiện khách quen (has_member) và ID đặt bàn đang giữ chỗ.

  • Method: GET
  • Endpoint: /api/{locale}/v1/staff/tables
  • Auth: auth:staff_api,partner_api (Bearer Token của Staff hoặc Quản lý Partner)

Response Thành công​

[
  {
    "id": "cukcuk-tbl-01",
    "name": "Bàn VIP 01",
    "area_name": "Khu Vực Trong Nhà",
    "status": "occupied",
    "has_member": true,
    "active_reservation": null,
    "active_order": {
      "id": "cukcuk-ord-8890"
    },
    "reserved_booking_id": null
  },
  {
    "id": "cukcuk-tbl-02",
    "name": "Bàn VIP 02",
    "area_name": "Khu Vực Trong Nhà",
    "status": "available",
    "has_member": false,
    "active_reservation": null,
    "active_order": null,
    "reserved_booking_id": "019b8d49-bb12-7001-a123-001122334455"
  }
]

2. Chi tiết Hoá đơn Món ăn tại Bàn​

Khi nhân viên bấm vào một bàn đang có khách (status: occupied), ứng dụng gọi API này để xem danh sách món ăn đã gọi và số lượng khách thực tế từ CukCuk.

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

Path Parameters​

Tham sốKiểuBắt buộcMô tả
idstringCóMã đơn hàng cukcuk_id lấy từ trường active_order.id.

Response Thành công​

{
  "id": "cukcuk-ord-8890",
  "table_name": "Bàn VIP 01",
  "status": 1,
  "customer_name": "Nguyễn Văn A",
  "customer_tel": "0901234567",
  "total_amount": 1250000,
  "order_date": "2026-05-20 18:45:00",
  "number_of_guests": 4,
  "items": [
    {
      "id": "item-001",
      "name": "Bò Fuji Nướng Đá Núi Lửa",
      "quantity": 2,
      "price": 350000,
      "total_amount": 700000,
      "unit_name": "Phần"
    },
    {
      "id": "item-002",
      "name": "Bia Thủ Công Jasmine IPA",
      "quantity": 4,
      "price": 85000,
      "total_amount": 340000,
      "unit_name": "Ly"
    }
  ]
}

3. Quản lý Yêu cầu Đặt bàn​

Dành cho tiếp tân/thu ngân quản lý các đơn đặt bàn trước gửi về từ Member App.

3.1 Thống kê đặt bàn theo ngày​

  • Method: GET
  • Endpoint: /api/{locale}/v1/staff/bookings/stats
  • Auth: auth:staff_api

Query Parameters​

  • date: Ngày cần xem định dạng YYYY-MM-DD (mặc định là hôm nay).

Response Thành công​

{
  "total": 12,
  "pending": 3,
  "confirmed": 8,
  "arrived": 1,
  "cancelled": 0,
  "monthly_dates": ["2026-05-01", "2026-05-05", "2026-05-20"]
}

3.2 Lấy danh sách đặt bàn​

  • Method: GET
  • Endpoint: /api/{locale}/v1/staff/bookings
  • Auth: auth:staff_api

Query Parameters​

  • status: Lọc theo trạng thái (pending, confirmed).
  • date: Lọc theo ngày YYYY-MM-DD.
  • limit: Số bản ghi mỗi trang (mặc định 20).

3.3 Duyệt & Gán bàn cho đơn đặt bàn​

  • Method: PUT
  • Endpoint: /api/{locale}/v1/staff/bookings/{id}/approve
  • Auth: auth:staff_api (Quyền: can_manage_booking hoặc can_create_checkin)

Request Body​

{
  "cukcuk_table_id": "cukcuk-tbl-02",
  "cukcuk_table_name": "Bàn VIP 02"
}

3.4 Đổi bàn cho đơn đặt bàn đã duyệt​

  • Method: PUT
  • Endpoint: /api/{locale}/v1/staff/bookings/{id}/table
  • Auth: auth:staff_api

Request Body​

{
  "cukcuk_table_id": "cukcuk-tbl-05",
  "cukcuk_table_name": "Bàn VIP 05"
}

3.5 Huỷ đơn đặt bàn​

  • Method: PUT
  • Endpoint: /api/{locale}/v1/staff/bookings/{id}/cancel
  • Auth: auth:staff_api

4. Quy trình Check-in & Điều phối Bàn​

4.1 Check-in Khách vào Bàn​

Hỗ trợ cả khách vãng lai (nhập số điện thoại) hoặc hội viên (quét mã QR định danh).

  • Method: POST
  • Endpoint: /api/{locale}/v1/staff/reservations/checkin
  • Auth: auth:staff_api (Quyền: can_create_checkin)

Request Body - Check-in Hội viên đã có bàn​

{
  "member_id": "019b8d48-97df-7177-8aa0-47f2107a8eb3",
  "table_ids": ["cukcuk-tbl-02"],
  "table_names": ["Bàn VIP 02"],
  "quantity": 4,
  "notes": "Khách yêu cầu mang đồ nguội trước"
}

Request Body - Check-in Khách Vãng lai​

{
  "phone": "0912345678"
}

Response Thành công​

{
  "message": "Tạo Check-in thành công",
  "is_new_member": false,
  "tier_level": 2,
  "is_vip": true,
  "customer_name": "Nguyễn Văn A",
  "reservation": {
    "id": "019b8d49-res-7701",
    "checkin_code": "ZC-984210",
    "cukcuk_table_id": "cukcuk-tbl-02",
    "cukcuk_table_name": "Bàn VIP 02",
    "quantity": 4,
    "status": "active",
    "created_at": "2026-05-20T19:05:00Z"
  }
}

4.2 Tìm Phiên Bàn bằng Mã QR Check-in​

Khi khách mở mã QR Check-in đặt bàn từ User App (ZC-XXXXXX), nhân viên quét mã để kiểm tra thông tin.

  • Method: GET
  • Endpoint: /api/{locale}/v1/staff/reservations/by-code/{code}
  • Auth: auth:staff_api

4.3 Xếp Bàn Lần Đầu cho Đặt Bàn​

Dành cho trường hợp khách đã có đơn đặt trước (Booking) đến quán, nhân viên bấm "Nhận bàn" và chọn bàn trống.

  • Method: PUT
  • Endpoint: /api/{locale}/v1/staff/reservations/{id}/seat
  • Auth: auth:staff_api
{
  "cukcuk_table_id": "cukcuk-tbl-03",
  "cukcuk_table_name": "Bàn VIP 03"
}

4.4 Chuyển Bàn​

Khi khách đang ngồi có nhu cầu đổi sang bàn khác (ví dụ: chuyển sang bàn to hơn khi có thêm bạn bè).

  • Method: PUT
  • Endpoint: /api/{locale}/v1/staff/reservations/{id}/change-table
  • Auth: auth:staff_api
{
  "new_cukcuk_table_id": "cukcuk-tbl-08",
  "new_cukcuk_table_name": "Bàn VIP 08 - Ngoài trời"
}

4.5 Huỷ Phiên Bàn​

Dành cho trường hợp khách huỷ hoặc check-in nhầm bàn.

  • Method: PUT
  • Endpoint: /api/{locale}/v1/staff/reservations/{id}/cancel
  • Auth: auth:staff_api
Cơ chế Hoàn tất Phiên (/complete)

Endpoint PUT /api/{locale}/v1/staff/reservations/{id}/complete đã được khoá (trả về mã 410 Gone). Nhân viên không cần đóng phiên thủ công vì hệ thống sẽ tự động chuyển trạng thái sang completed ngay khi đơn hàng tương ứng được thanh toán trên phần mềm MISA CukCuk POS.