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

API Nghiệp vụ Quản lý & Đối tác (Partner) trên Ứng dụng

Ứng dụng Staff hỗ trợ chế độ đăng nhập dành cho Chủ sở hữu / Cấp Quản lý (Partner). Khi đăng nhập bằng tài khoản Partner, ứng dụng mở khoá các màn hình điều hành nâng cao: Dashboard phân tích doanh thu kinh doanh, báo cáo khách hàng quay lại (retention), vận hành chốt chia sẻ lợi nhuận định kỳ, duyệt hàng loạt đặt bàn và quản lý cây hệ thống giới thiệu.

Xác thực Partner

Tài khoản Partner đăng nhập qua endpoint POST /api/{locale}/v1/partner/login. Tất cả các endpoint dưới đây đều yêu cầu token xác thực auth:partner_api (Bearer Token).

1. Dashboard Điều hành Doanh thu Toàn diện​

Cung cấp các chỉ số đo lường hiệu quả kinh doanh cốt lõi, doanh thu thực tế ghi nhận từ hệ thống CukCuk POS, số lượng thành viên mới và danh sách khách hàng chi tiêu nhiều nhất.

  • Method: GET
  • Endpoint: /api/vi-vn/v1/partner/dashboard
  • Auth: auth:partner_api

Query Parameters​

Tham sốKiểuMô tả
monthstringTháng cần xem báo cáo định dạng YYYY-MM (ví dụ: 2026-05).
freshinteger1 để ép hệ thống tính toán lại bỏ qua cache.

Response Thành công​

{
  "dashboardData": {
    "currency": "VND",
    "gross_revenue": 1450000000,
    "net_revenue": 1380000000,
    "total_orders": 3420,
    "total_members": 2840,
    "new_members_this_month": 185,
    "active_members_count": 920,
    "top_spenders": [
      {
        "member_id": "019b8d48-97df-7177-8aa0-47f2107a8eb3",
        "name": "Nguyễn Văn A",
        "phone": "0901234567",
        "total_spent": 45000000,
        "order_count": 22
      }
    ]
  }
}

2. Báo cáo Giữ chân Khách hàng​

Phân tích tỷ lệ khách hàng quay lại quán theo từng kỳ, tần suất ghé thăm và giá trị vòng đời của từng khách hàng.

2.1 Danh sách khách hàng giữ chân​

  • Method: GET
  • Endpoint: /api/vi-vn/v1/partner/reports/retained-members
  • Auth: auth:partner_api

Query Parameters​

  • period: this_month, last_month, this_quarter, custom.
  • from, to: Ngày bắt đầu / kết thúc khi chọn custom (YYYY-MM-DD).
  • search: Tìm theo tên hoặc SĐT khách.
  • page, per_page: Phân trang dữ liệu.

2.2 Chi tiết lịch sử ghé thăm của khách hàng​

  • Method: GET
  • Endpoint: /api/vi-vn/v1/partner/reports/retained-members/{memberId}/details
  • Auth: auth:partner_api

3. Quản lý Chốt Chia sẻ Lợi nhuận​

Đây là tính năng tài chính độc quyền của hệ thống Loyalty: Mỗi kỳ (tháng hoặc khoảng thời gian tùy chọn), Quản lý nhập lợi nhuận ròng của quán. Hệ thống tự động phân bổ tỷ lệ thưởng cho các hội viên đủ điều kiện theo từng phân hạng.

3.1 Danh sách các kỳ chốt lợi nhuận​

  • Method: GET
  • Endpoint: /api/{locale}/v1/partner/profit-closings
  • Auth: auth:partner_api

Query Parameters​

  • year_month: Lọc theo tháng YYYY-MM.

3.2 Lấy doanh thu tạm tính từ CukCuk trong kỳ​

Giúp Quản lý kiểm tra nhanh doanh số thực tế trên POS CukCuk trước khi tạo kỳ chốt.

  • Method: GET
  • Endpoint: /api/{locale}/v1/partner/profit-closings/revenue
  • Auth: auth:partner_api

Query Parameters​

  • year_month: Tháng cần kiểm tra (YYYY-MM).
  • period_start: Ngày bắt đầu kỳ (YYYY-MM-DD).
  • period_end: Ngày kết thúc kỳ (YYYY-MM-DD).
  • cukcuk_branch_id: Chi nhánh CukCuk cụ thể.

3.3 Tạo kỳ chốt chia sẻ lợi nhuận mới​

  • Method: POST
  • Endpoint: /api/{locale}/v1/partner/profit-closings
  • Auth: auth:partner_api

Request Body​

{
  "year_month": "2026-05",
  "period_start": "2026-05-01",
  "period_end": "2026-05-31",
  "net_profit": 200000000,
  "cukcuk_branch_id": "c711738c-8f92-4ce6-a790-8e6d2bc6ec54",
  "notes": "Chốt lợi nhuận tháng 05/2026 cơ sở Zodutcan Q1"
}

3.4 Xem chi tiết & Danh sách phân bổ thưởng​

  • Method: GET
  • Endpoint: /api/{locale}/v1/partner/profit-closings/{id}
  • Auth: auth:partner_api

Response Thành công​

{
  "id": "019b8d49-pc-0001",
  "year_month": "2026-05",
  "net_profit": 200000000,
  "status": "draft",
  "total_reward_amount": 15000000,
  "details": [
    {
      "id": "019b8d49-pcd-001",
      "member_id": "019b8d48-97df-7177-8aa0-47f2107a8eb3",
      "member_name": "Nguyễn Văn A",
      "tier_name": "Hạng Vàng (Gold)",
      "profit_percentage": 5.0,
      "pool_size": 100000000,
      "reward_amount": 5000000,
      "actual_reward_amount": 5000000,
      "status": "pending"
    }
  ]
}

3.5 Khoá kỳ chốt​

Sau khi đối soát và rà soát số liệu, Quản lý khoá kỳ chốt để ngăn chỉnh sửa.

  • Method: POST
  • Endpoint: /api/{locale}/v1/partner/profit-closings/{id}/lock
  • Auth: auth:partner_api

3.6 Đánh dấu Đã chi trả thưởng​

Cập nhật trạng thái sau khi đã chuyển khoản hoặc thanh toán tiền thưởng cho hội viên.

  • Method: POST
  • Endpoint: /api/{locale}/v1/partner/profit-closings/{closingId}/details/mark-paid
  • Auth: auth:partner_api
{
  "detail_ids": [
    "019b8d49-pcd-001",
    "019b8d49-pcd-002"
  ]
}

4. Quản lý Đặt bàn Cấp Chuỗi / Quản lý​

Ngoài các chức năng duyệt từng bàn như nhân viên, Quản lý có thêm quyền thao tác phê duyệt nhanh toàn bộ yêu cầu.

4.1 Phê duyệt Hàng loạt Đặt bàn​

Tự động duyệt tất cả các yêu cầu đặt bàn đang ở trạng thái pending của ngày hiện tại.

  • Method: POST
  • Endpoint: /api/{locale}/v1/partner/bookings/approve-all
  • Auth: auth:partner_api

4.2 Thống kê Đặt bàn theo Bàn​

Theo dõi công suất phục vụ và hiệu suất lấp đầy chỗ ngồi của từng bàn ăn trong ngày.

  • Method: GET
  • Endpoint: /api/{locale}/v1/partner/bookings/table-stats
  • Auth: auth:partner_api

5. Sơ đồ Cây Hệ thống Hội viên​

Hiển thị mô hình mạng lưới phát triển khách hàng đa cấp độ (F1, F2...) do các hội viên lan toả, giúp đánh giá hiệu quả của chính sách giới thiệu.

  • Method: GET
  • Endpoint: /api/vi-vn/v1/partner/members/tree
  • Auth: auth:partner_api

Response Thành công​

[
  {
    "id": "019b8d48-upline-001",
    "name": "Trần Thị Trưởng Nhóm",
    "phone": "0988776655",
    "tier": "Hạng Kim Cương (Diamond)",
    "total_personal_revenue": 85000000,
    "total_network_revenue": 320000000,
    "children_count": 14,
    "children": [
      {
        "id": "019b8d48-97df-7177-8aa0-47f2107a8eb3",
        "name": "Nguyễn Văn A",
        "phone": "0901234567",
        "tier": "Hạng Vàng (Gold)",
        "total_personal_revenue": 32000000,
        "total_network_revenue": 54200000,
        "children_count": 1
      }
    ]
  }
]

6. Danh sách Cơ sở & Nhân sự Chi nhánh​

  • Danh sách chi nhánh CukCuk liên kết: GET /api/{locale}/v1/partner/cukcuk-branches
  • Danh sách các câu lạc bộ / quán (Clubs): GET /api/{locale}/v1/partner/clubs
  • Danh sách nhân viên (Staff): GET /api/{locale}/v1/partner/staff