Danh sách Subscription Packages

Subscription Packages API — Danh sách gói (v1.0)

Đối tượng: Agency F1 (Parent) & Agency F10 (Child)
Trạng thái: Stable
Ngôn ngữ: VI

---

1. Tổng quan

1.1 Định nghĩa

Subscription Packages API cho phép các Agency lấy danh sách các gói dịch vụ (subscription) trong hệ thống.

• F1 (Parent Agency): có quyền xem toàn bộ gói dịch vụ.
• F10 (Child Agency): chỉ xem được gói thuộc về F1 cha.

API thường dùng trong:

• Quản lý các gói đã mua.
• Theo dõi thời hạn & quyền dịch vụ kèm theo.
• Phân tích doanh thu & hành vi sử dụng.

1.2 Lợi ích khi sử dụng

• Quản lý minh bạch: biết rõ agency nào đang dùng gói nào, trạng thái ra sao.
• Phân quyền rõ ràng: F1 kiểm soát tất cả, F10 chỉ thấy gói cha cấp.
• Mở rộng dễ dàng: hỗ trợ filter nâng cao (giá, ngày tạo, dịch vụ kèm theo...).
• Tích hợp đa dạng: gắn với user portal, dashboard quản trị, hệ thống báo cáo.

---

2. Endpoint & Method

• URL: /api/v1/subscriptions/list (opens new window)
• Method: POST

---

3. Headers bắt buộc

Header	Mô tả
x-api-account	Tài khoản API của Agency F1
x-api-password	Mật khẩu API của Agency F1
x-api-token	Token API của Agency F1

---

4. Request Body

4.1 Ví dụ (Request body)

{
  "maxSize": 20,
  "offset": 0,
  "status": "active",
  "orderBy": "createdAt",
  "order": "desc"
}

5.2 Bảng mô tả trường (Request)

Trường	Type	Bắt buộc	Mô tả
maxSize	number	No	Số bản ghi mỗi trang (mặc định 20, tối đa 100)
offset	number	No	Vị trí bắt đầu (mặc định 0)
status	string	No	ACTIVE/INACTIVE/EXPIRED/SUSPENDED
orderBy	string	No	createdAt/updatedAt/name/price/status
order	string	No	ASC/DESC (mặc định DESC)

---

5. Response

5.1 Ví dụ (Response)

{
  "StatusCode": 200,
  "Timestamp": "2024-01-01T10:00:00",
  "Path": "/api/v1/subscriptions/list",
  "Message": "Lấy danh sách subscription thành công",
  "Data": {
    "ListSubscription": {
      "total": 0,
      "list": [
        {
          "id": "string",
          "name": "string",
          "description": "string",
          "avatarUrl": "string",
          "coverUrl": "string",
          "price": 0,
          "currency": "string",
          "billingCycle": "monthly",
          "duration": 0,
          "startsAt": "2025-09-22T09:47:27.772Z",
          "expiresAt": "2025-09-22T09:47:27.772Z",
          "status": "active",
          "agencyName": "string",
          "remainingDays": 0,
          "isActive": true,
          "agencyId": "string",
          "activeSubscribersCount": 5,
          "activeSubscribers": ["agency1", "agency2", "agency3"],
          "createdAt": "2025-09-22T09:47:27.772Z",
          "updatedAt": "2025-09-22T09:47:27.772Z",
          "hasAmadeusAccess": true,
          "hasAmadeusRestAccess": true,
          "hasVietnamAirlineAccess": true,
          "hasSabreAccess": true,
          "hasBambooAirwaysAccess": true,
          "hasVietjetAirAccess": true,
          "hasTourAccess": true,
          "hasEsimAccess": true,
          "hasHotelAccess": true,
          "hasAttractionAccess": true,
          "tourLimitSearch": 0,
          "tourLimitBooking": 0,
          "esimLimitSearch": 0,
          "esimLimitActivation": 0,
          "hotelLimitSearch": 0,
          "hotelLimitBooking": 0,
          "attractionLimitSearch": 0,
          "attractionLimitBooking": 0,
          "bambooLimitSearch": 0,
          "bambooLimitHold": 0,
          "bambooLimitIssues": 0,
          "vietjetLimitSearch": 0,
          "vietjetLimitHold": 0,
          "vietjetLimitIssues": 0,
          "amadeusRestLimitSearch": 0,
          "amadeusRestLimitHold": 0,
          "amadeusRestLimitIssues": 0,
          "maxUsers": 0,
          "subscribedAgencies": [],
          "terms": "string",
          "notes": "string",
          "features": "[\"Flight Search\", \"Booking\", \"Ticketing\"]",
          "hasPrioritySupport": true,
          "hasAdvancedAnalytics": true,
          "hasCustomBranding": true,
          "hasMultiUserAccess": true
        }
      ]
    }
  },
  "Errors": null,
  "RequestId": "req_1704096000000_abc123",
  "TotalDuration": 120
}

5.2 Bảng mô tả trường (Response)

Trường	Type	Mô tả
StatusCode	number	Mã trạng thái ứng dụng (200 = thành công)
Timestamp	string	Thời điểm phản hồi
Path	string	Endpoint được gọi
Message	string	Thông điệp kết quả
Data.ListSubscription.total	number	Tổng số subscription thỏa điều kiện
Data.ListSubscription.list[]	array	Danh sách subscription (mỗi phần tử là một gói)
RequestId	string	ID request để truy vết
TotalDuration	number	Tổng thời gian xử lý (ms)

Các trường trong Data.ListSubscription.list[]:

Trường	Type	Mô tả
id	string	UUID định danh gói
name	string	Tên gói
description	string	Mô tả ngắn của gói
avatarUrl	string	URL ảnh đại diện
coverUrl	string	URL ảnh bìa
price	number	Giá gói
currency	string	Đơn vị tiền tệ
billingCycle	string	Chu kỳ thanh toán (vd: monthly)
duration	number	Thời hạn theo chu kỳ
startsAt	string	Ngày bắt đầu hiệu lực (ISO-8601)
expiresAt	string	Ngày hết hạn (ISO-8601)
status	string	Trạng thái: active/inactive/expired/suspended
agencyName	string	Tên agency F1 sở hữu gói
remainingDays	number	Số ngày còn lại
isActive	boolean	Gói còn hiệu lực hay không
agencyId	string	ID agency F1 sở hữu gói
activeSubscribersCount	number	Số lượng agency F10 đang dùng gói
activeSubscribers[]	string[]	Danh sách ID agency F10 đang dùng
createdAt	string	Thời điểm tạo
updatedAt	string	Thời điểm cập nhật
has...Access	boolean	Quyền truy cập cho một dịch vụ
...Limit...	number	Giới hạn của một dịch vụ
maxUsers	number	Số người dùng tối đa
subscribedAgencies[]	array	Danh sách agency đã đăng ký
terms	string	Điều khoản sử dụng
notes	string	Ghi chú
features	string	Danh sách tính năng (JSON string)
hasPrioritySupport	boolean	Quyền truy cập Priority Support
hasAdvancedAnalytics	boolean	Quyền truy cập Advanced Analytics
hasCustomBranding	boolean	Quyền truy cập Custom Branding
hasMultiUserAccess	boolean	Quyền truy cập Multi User Access

5.3 Mã phản hồi

HTTP	Mô tả
200	Lấy danh sách subscription thành công
400	Dữ liệu không hợp lệ
401	Không có quyền truy cập danh sách subscription
403	Không có quyền xem subscription
404	Không tìm thấy subscription
500	Lỗi hệ thống