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

API Chương trình Giới thiệu Bạn bè

Hệ thống cho phép hội viên chia sẻ mã giới thiệu hoặc link QR (zodutcan://referral/CODE hoặc https://domain/ref/CODE) để mời người mới cài đặt ứng dụng. Doanh số của người được giới thiệu (F1) sẽ được tự động tính vào doanh số tích luỹ của người giới thiệu để xét duyệt thăng hạng.

1. Giải mã Mã QR / Link Giới thiệu​

Được gọi ngay khi người dùng chưa đăng nhập quét mã QR hoặc mở Deep Link vào ứng dụng, nhằm lấy thông tin chiến dịch và người giới thiệu.

  • Method: GET
  • Endpoint: /api/{locale}/v1/member/referrals/resolve
  • Auth: Không yêu cầu (Public)

Query Parameters​

Tham sốKiểuBắt buộcMô tả
codestringCóMã giới thiệu (VD: MH39XT hoặc REF090123).

Response Thành công​

{
  "referral_code_id": "019b8d48-refcode-01",
  "code": "MH39XT",
  "referrer": {
    "name": "Nguyễn Văn A",
    "avatar": "https://api-zodutcan.datacomtech.vn/storage/avatars/user-1.jpg"
  },
  "campaign": {
    "id": "019b8d48-camp-01",
    "name": "Mời Bạn Cùng Thưởng Ngoạn Zodutcan",
    "referrer_points": 50000,
    "referee_points": 20000
  },
  "referrer_card": {
    "name": "Thẻ VIP Zodutcan"
  },
  "referee_card": {
    "name": "Thẻ VIP Zodutcan"
  }
}

2. Nhập Mã Giới thiệu​

Được gọi sau khi người dùng đăng nhập/đăng ký thành công và có mã giới thiệu chờ xử lý, hoặc nhập thủ công mã người quen trong trang Giới thiệu.

  • Method: POST
  • Endpoint: /api/{locale}/v1/member/referrals/apply
  • Auth: auth:member_api (Bearer Token)

Request Body​

{
  "code": "MH39XT"
}

Response Thành công​

{
  "success": true,
  "message": "Áp dụng mã giới thiệu thành công.",
  "referral": {
    "status": "pending",
    "referee_points": 20000
  }
}

Lỗi thường gặp​

  • 404 Not Found: Mã giới thiệu không tồn tại.
  • 422 Unprocessable Entity: Tự giới thiệu chính mình (cannot_refer_yourself), hoặc tài khoản đã gắn người giới thiệu từ trước.

3. Bảng Điều khiển Giới thiệu​

Lấy thông tin mã chia sẻ cá nhân, đường link QR, danh sách các chiến dịch tham gia và thống kê lượt mời.

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

Response Thành công​

{
  "can_refer": true,
  "programs": [
    {
      "campaign": {
        "id": "019b8d48-camp-01",
        "name": "Mời Bạn Cùng Thưởng Ngoạn Zodutcan",
        "description": "Chia sẻ mã để nhận thưởng và cộng dồn doanh số F1"
      },
      "code": "MH39XT",
      "share_url": "https://zodutcan.datacomtech.vn/ref/MH39XT",
      "referral_count": 18,
      "successful_count": 12,
      "points_earned": 600000,
      "recent_referrals": [
        {
          "referee_name": "Lê *** Mai",
          "status": "completed",
          "created_at": "2026-05-18T15:30:00Z"
        }
      ]
    }
  ],
  "as_referee": []
}

4. Lịch sử Chi tiết Giới thiệu theo Chiến dịch​

  • Method: GET
  • Endpoint: /api/{locale}/v1/member/referrals/{campaignId}/history
  • Auth: auth:member_api (Bearer Token)
  • Query Params: page, limit (mặc định 15), status, date.