API Thẻ Thành viên & Lịch sử Giao dịch Doanh số

Các endpoint phục vụ hiển thị danh sách thẻ hội viên đang tham gia, tiến trình tích luỹ doanh số cá nhân & F1, và lịch sử giao dịch tổng hợp trên ứng dụng zodutcan-user.

---

1. Lấy danh sách Thẻ Thành viên

Lấy danh sách các thẻ hội viên mà người dùng đã liên kết hoặc theo dõi, hiển thị tại thanh cuộn thẻ Trang chủ.

• Method: GET
• Endpoint: /api/{locale}/v1/member/followed-cards
• Auth: auth:member_api (Bearer Token)

Response Thành công

[
  {
    "id": "019b8d48-card-001",
    "name": "Thẻ Hội Viên VIP Zodutcan",
    "unique_identifier": "C-CARD01",
    "club": {
      "id": "019b8d48-club-hcm",
      "name": "Zodutcan Saigon Center",
      "address": "65 Lê Lợi, Bến Nghé, Quận 1, TP.HCM"
    },
    "tier": {
      "name": "Hạng Vàng",
      "level": 3,
      "color": "#F59E0B",
      "profit_sharing_percentage": 5.0
    },
    "total_spend": 28500000,
    "card_background_url": "https://api-zodutcan.datacomtech.vn/storage/cards/bg-gold.png",
    "is_primary": true
  }
]

---

2. Lịch sử Giao dịch Hợp nhất

Đây là endpoint cốt lõi cung cấp dữ liệu cho màn hình Lịch sử & Ví (wallet_api.dart). Hệ thống tổng hợp 3 luồng dữ liệu theo thời gian thực:

1. purchase: Giao dịch phát sinh doanh số (gồm doanh số trực tiếp của khách và doanh số từ bạn bè F1 giới thiệu).
2. voucher_used: Các lần áp dụng voucher giảm giá tại nhà hàng.
3. profit_sharing: Tiền thưởng nhận được từ Quỹ chia thưởng hàng tháng.

• Method: GET
• Endpoint: /api/{locale}/v1/member/transaction-history
• Auth: auth:member_api (Bearer Token)

Query Parameters

Tham số	Kiểu	Mặc định	Mô tả
type	string	all	Lọc loại giao dịch: all, purchase, voucher_used, profit_sharing.
page	integer	1	Số trang.
per_page	integer	20	Số lượng bản ghi trên một trang (tối đa: 100).
from	string	null	Từ ngày (YYYY-MM-DD).
to	string	null	Đến ngày (YYYY-MM-DD).
month	string	null	Lọc theo tháng (YYYY-MM).

Response Thành công

{
  "data": [
    {
      "id": "tx-019b8d48-001",
      "type": "purchase",
      "title": "Doanh số",
      "description": "Hoá đơn bàn B08 - Zodutcan Saigon Center",
      "amount": 1500000,
      "points_earned": 1500000,
      "is_personal": true,
      "created_at": "2026-05-21T20:30:00Z"
    },
    {
      "id": "tx-019b8d48-002",
      "type": "purchase",
      "title": "Doanh thu giới thiệu",
      "description": "F1 Trần Văn Hùng (Hoá đơn nhà hàng)",
      "amount": 2800000,
      "points_earned": 2800000,
      "is_personal": false,
      "created_at": "2026-05-20T19:15:00Z"
    },
    {
      "id": "tx-019b8d48-003",
      "type": "profit_sharing",
      "title": "Tiền thưởng chia thưởng",
      "description": "Quỹ thưởng tháng 04/2026 - Hạng Vàng (5%)",
      "amount": 350000,
      "created_at": "2026-05-01T00:00:00Z"
    },
    {
      "id": "tx-019b8d48-004",
      "type": "voucher_used",
      "title": "Sử dụng voucher",
      "description": "Giảm 100.000đ cho đơn hàng bàn B02",
      "amount": -100000,
      "created_at": "2026-04-28T12:45:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 45,
    "last_page": 3,
    "has_more": true
  }
}

---

3. Thống kê Tổng hợp Doanh số & Tiền thưởng

Lấy số liệu tóm tắt tổng tích luỹ chi tiêu cá nhân, doanh số F1 và tổng tiền thưởng đã nhận để hiển thị lên thẻ tóm tắt trên màn hình Ví.

• Method: GET
• Endpoint: /api/{locale}/v1/member/transaction-history/summary
• Auth: auth:member_api (Bearer Token)

Response Thành công

{
  "total_spending": 28500000,
  "personal_spending": 18200000,
  "f1_referral_spending": 10300000,
  "total_profit_sharing_reward": 850000,
  "total_vouchers_used": 6,
  "current_reward_balance": 450000
}