Quản lý quà tặng

Nhóm API cho phép bạn tạo, cập nhật, xoá và tra cứu quà tặng trong cửa hàng Mini Gift.

Xác thực

Tất cả endpoint bên dưới đều yêu cầu header x-api-key. Xem chi tiết tại trang Giới thiệu Open API.

1. Đối tượng quà tặng (Gift)

Toàn bộ API dưới đây thao tác trên đối tượng quà tặng có cấu trúc sau:

Bảng thuộc tính Gift

Trường	Kiểu	Mô tả
id	string	ID của quà tặng
name	string	Tên quà tặng
description	string	Mô tả chi tiết
image	string	URL hình ảnh quà tặng
winDisplayImage	string	URL hình hiển thị khi trúng quà
status	string (enum)	Trạng thái: `active`, `inactive`
quantity	number	Số lượng quà phát hành
integrationType	string (enum)	Loại tích hợp (xem bảng bên dưới)
redeemMethod	string (enum)	Cách nhận quà (xem bảng bên dưới)
deliveryMethod	string (enum)	Hình thức giao quà: `in_store`, `delivery`
giftCode	string	Mã quà tặng (hệ thống tự sinh với một số loại tích hợp)
pointsRequired	number	Số điểm cần để đổi quà (khi redeemMethod = exchange_points)
discountVoucherConfig	object	Cấu hình voucher giảm giá (khi integrationType = discount_voucher)
claimStartDate	string (ISO 8601)	Ngày bắt đầu cho phép đổi quà — chỉ dùng khi redeemMethod = exchange_points. Trước thời điểm này, quà không hiển thị cho khách đổi điểm
claimEndDate	string (ISO 8601)	Ngày kết thúc cho phép đổi quà — chỉ dùng khi redeemMethod = exchange_points. Sau thời điểm này, quà không còn khả dụng để đổi điểm
expirationGiftDate	string (ISO 8601)	Ngày hết hạn sử dụng voucher — chỉ dùng khi integrationType = discount_voucher. Sau ngày này, voucher đã nhận sẽ không thể sử dụng
createdAt	string (ISO 8601)	Thời điểm tạo
updatedAt	string (ISO 8601)	Thời điểm cập nhật gần nhất

Giá trị enum

Bảng integrationType

Loại tích hợp quyết định cách quà được sử dụng:

Giá trị	Ý nghĩa
direct_claim	Nhận quà trực tiếp (sinh mã quà)
campaign	Quà gắn với chiến dịch (minigame, vòng quay...)
miniapp	Quà sử dụng trong Mini App
external	Quà tích hợp hệ thống ngoài (mã do bên thứ ba cấp)
discount_voucher	Voucher giảm giá (cần discountVoucherConfig)

Bảng redeemMethod

Cách khách nhận/đổi quà:

Giá trị	Ý nghĩa
self_confirm	Khách tự xác nhận
staff_scan	Nhân viên quét mã để trao quà
exchange_points	Đổi quà bằng điểm tích lũy

Bảng discountVoucherConfig

Cấu hình voucher giảm giá:

Trường	Kiểu	Bắt buộc	Mô tả
discountType	string	Có	`percentage` (giảm %) hoặc `fixed_amount` (giảm số tiền cố định)
discountValue	number	Có	Giá trị giảm (theo % hoặc theo VND)
maxUses	number	Có	Số lần sử dụng tối đa (mặc định 1)
minimumOrderAmount	number	Không	Giá trị đơn hàng tối thiểu để áp dụng
maximumDiscountAmount	number	Không	Số tiền giảm tối đa (dùng cho giảm %)

Quy tắc nghiệp vụ

redeemMethod = exchange_points chỉ áp dụng cho quà loại direct_claim hoặc discount_voucher. Kết hợp khác sẽ trả về 400. - Không được tạo hai quà trùng cả name + integrationType trong cùng cửa hàng — sẽ trả về 409 Conflict. - giftCode được hệ thống tự sinh cho các loại direct_claim, campaign, external, miniapp; bạn không cần gửi lên.

2. Lấy danh sách quà tặng

Endpoint

🔗Endpoint Production

GET https://api.minigift.vn/api/v1/open/gifts

Tham số truy vấn (Query Parameters)

Tham số	Kiểu	Bắt buộc	Mô tả
page	number	Không	Trang hiện tại (mặc định 1)
limit	number	Không	Số bản ghi mỗi trang (mặc định 10, tối đa 1000)
search	string	Không	Tìm theo tên quà hoặc mã quà
status	string	Không	Lọc theo trạng thái: `active`, `inactive`
integrationTypes	string[]	Không	Lọc theo một hoặc nhiều loại tích hợp
giftIds	string[]	Không	Lọc theo danh sách ID quà cụ thể

Ví dụ request

cURL
curl -X GET "https://api.minigift.vn/api/v1/open/gifts?status=active&page=1&limit=10" \
  -H "x-api-key: sk_your_api_key_here"

Phản hồi (Response)

{
  "data": [
    {
      "id": "6650f1a2b3c4d5e6f7a8b9c0",
      "name": "Voucher giảm 50.000đ",
      "image": "https://cdn.minigift.vn/gifts/voucher-50k.png",
      "description": "Voucher giảm giá cho đơn từ 200.000đ",
      "integrationType": "discount_voucher",
      "status": "active",
      "redeemMethod": "self_confirm",
      "deliveryMethod": "in_store",
      "giftCode": "1234567890123",
      "pool": {
        "_id": "6650f1a2b3c4d5e6f7a8b9c1",
        "quantity": 100,
        "usedCount": 12,
        "reservedCount": 3
      },
      "usedCodesCount": 12,
      "createdAt": "2026-06-20T03:15:00.000Z",
      "updatedAt": "2026-06-25T08:40:00.000Z"
    }
  ],
  "meta": { "total": 1, "page": 1, "limit": 10 },
  "success": true
}

Trường bổ sung khi lấy danh sách

pool: thông tin kho mã quà — quantity (tổng), usedCount (đã dùng), reservedCount (đang giữ chỗ). Trả về null nếu quà không có kho. - usedCodesCount: số mã quà đã được sử dụng.

3. Lấy chi tiết quà tặng

Endpoint

🔗Endpoint Production

GET https://api.minigift.vn/api/v1/open/gifts/{id}

Tham số đường dẫn (Path Parameters)

Tham số	Kiểu	Bắt buộc	Mô tả
id	string	Có	ID của quà tặng

Ví dụ request

cURL
curl -X GET "https://api.minigift.vn/api/v1/open/gifts/6650f1a2b3c4d5e6f7a8b9c0" \
  -H "x-api-key: sk_your_api_key_here"

Phản hồi (Response)

200 OK
404 Not Found

{
  "data": {
    "id": "6650f1a2b3c4d5e6f7a8b9c0",
    "name": "Voucher giảm 50.000đ",
    "image": "https://cdn.minigift.vn/gifts/voucher-50k.png",
    "description": "Voucher giảm giá cho đơn từ 200.000đ",
    "integrationType": "discount_voucher",
    "status": "active",
    "redeemMethod": "self_confirm",
    "deliveryMethod": "in_store",
    "giftCode": "1234567890123",
    "discountVoucherConfig": {
      "discountType": "fixed_amount",
      "discountValue": 50000,
      "minimumOrderAmount": 200000,
      "maxUses": 1
    },
    "claimStartDate": "2026-06-20T00:00:00.000Z",
    "claimEndDate": "2026-07-20T00:00:00.000Z",
    "createdAt": "2026-06-20T03:15:00.000Z",
    "updatedAt": "2026-06-25T08:40:00.000Z"
  },
  "success": true
}

{
  "statusCode": 404,
  "message": "Không tìm thấy quà tặng",
  "error": "Not Found"
}

4. Tạo quà tặng

Endpoint

🔗Endpoint Production

POST https://api.minigift.vn/api/v1/open/gifts

Dữ liệu được gửi đi (Request Body)

Trường	Kiểu	Bắt buộc	Mô tả
name	string	Có	Tên quà tặng
integrationType	string	Có	`direct_claim`, `campaign`, `miniapp`, `external`, `discount_voucher`
status	string	Có	`active`, `inactive`
redeemMethod	string	Có	`self_confirm`, `staff_scan`, `exchange_points`
image	string	Không	URL hình ảnh quà tặng
winDisplayImage	string	Không	URL hình hiển thị khi trúng quà
description	string	Không	Mô tả quà tặng
quantity	number	Không	Số lượng quà
deliveryMethod	string	Không	`in_store`, `delivery`
pointsRequired	number	Không	Số điểm cần để đổi (khi redeemMethod = exchange_points)
couponId	string	Không	ID coupon liên kết
ecomShopId	string	Không	ID cửa hàng TMĐT liên kết
externals	array	Không	Mã ngoài: `[{ "code": "ABC", "link": "https://..." }]`
discountVoucherConfig	object	Không	Bắt buộc khi integrationType = discount_voucher
claimStartDate	string	Không	Ngày bắt đầu cho phép đổi quà (ISO 8601) — chỉ dùng khi redeemMethod = exchange_points
claimEndDate	string	Không	Ngày kết thúc cho phép đổi quà (ISO 8601) — chỉ dùng khi redeemMethod = exchange_points
expirationGiftDate	string	Không	Ngày hết hạn sử dụng voucher (ISO 8601) — chỉ dùng khi integrationType = discount_voucher

Lưu ý

Không cần gửi shopId — cửa hàng được xác định thông qua API Key.

Ví dụ request

cURL
curl -X POST "https://api.minigift.vn/api/v1/open/gifts" \
  -H "x-api-key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Voucher giảm 50.000đ",
    "integrationType": "discount_voucher",
    "status": "active",
    "redeemMethod": "self_confirm",
    "discountVoucherConfig": {
      "discountType": "fixed_amount",
      "discountValue": 50000,
      "minimumOrderAmount": 200000,
      "maxUses": 1
    }
  }'

{
  "name": "Voucher giảm 50.000đ",
  "integrationType": "discount_voucher",
  "status": "active",
  "redeemMethod": "self_confirm",
  "deliveryMethod": "in_store",
  "image": "https://cdn.minigift.vn/gifts/voucher-50k.png",
  "description": "Voucher giảm giá cho đơn từ 200.000đ",
  "discountVoucherConfig": {
    "discountType": "fixed_amount",
    "discountValue": 50000,
    "minimumOrderAmount": 200000,
    "maxUses": 1
  }
}

Phản hồi (Response)

201 Created
409 Conflict
400 Bad Request

{
  "data": {
    "id": "6650f1a2b3c4d5e6f7a8b9c0",
    "name": "Voucher giảm 50.000đ",
    "integrationType": "discount_voucher",
    "status": "active",
    "redeemMethod": "self_confirm",
    "deliveryMethod": "in_store",
    "giftCode": "1234567890123",
    "createdAt": "2026-07-02T02:00:00.000Z",
    "updatedAt": "2026-07-02T02:00:00.000Z"
  },
  "success": true
}

{
  "statusCode": 409,
  "message": "Quà tặng đã tồn tại",
  "error": "Conflict"
}

{
  "statusCode": 400,
  "message": "Đổi điểm chỉ áp dụng cho quà nhận trực tiếp hoặc voucher",
  "error": "Bad Request"
}

5. Cập nhật quà tặng

Endpoint

🔗Endpoint Production

PATCH https://api.minigift.vn/api/v1/open/gifts/{id}

Tham số đường dẫn (Path Parameters)

Tham số	Kiểu	Bắt buộc	Mô tả
id	string	Có	ID của quà tặng cần cập nhật

Dữ liệu được gửi đi (Request Body)

Gửi các trường cần cập nhật (tất cả đều tuỳ chọn), dùng cùng tập trường như khi tạo quà. Các trường không gửi sẽ giữ nguyên.

Ví dụ request

cURL
curl -X PATCH "https://api.minigift.vn/api/v1/open/gifts/6650f1a2b3c4d5e6f7a8b9c0" \
  -H "x-api-key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Voucher giảm 70.000đ", "status": "inactive" }'

{
  "name": "Voucher giảm 70.000đ",
  "status": "inactive"
}

Phản hồi (Response)

{
  "data": {
    "id": "6650f1a2b3c4d5e6f7a8b9c0",
    "name": "Voucher giảm 70.000đ",
    "status": "inactive",
    "updatedAt": "2026-07-02T02:30:00.000Z"
  },
  "success": true
}

6. Xoá quà tặng

Endpoint

🔗Endpoint Production

DELETE https://api.minigift.vn/api/v1/open/gifts/{id}

Tham số đường dẫn (Path Parameters)

Tham số	Kiểu	Bắt buộc	Mô tả
id	string	Có	ID của quà tặng cần xoá

Ví dụ request

cURL
curl -X DELETE "https://api.minigift.vn/api/v1/open/gifts/6650f1a2b3c4d5e6f7a8b9c0" \
  -H "x-api-key: sk_your_api_key_here"

Phản hồi (Response)

200 OK
404 Not Found

{
  "data": {
    "id": "6650f1a2b3c4d5e6f7a8b9c0",
    "deleted": true
  },
  "success": true
}

{
  "statusCode": 404,
  "message": "Không tìm thấy quà tặng",
  "error": "Not Found"
}

1. Đối tượng quà tặng (Gift)​

Bảng thuộc tính Gift​

Giá trị enum​

Bảng integrationType​

Bảng redeemMethod​

Bảng discountVoucherConfig​

2. Lấy danh sách quà tặng​

Endpoint​

Tham số truy vấn (Query Parameters)​

Ví dụ request​

Phản hồi (Response)​

3. Lấy chi tiết quà tặng​

Endpoint​

Tham số đường dẫn (Path Parameters)​

Ví dụ request​

Phản hồi (Response)​

4. Tạo quà tặng​

Endpoint​

Dữ liệu được gửi đi (Request Body)​

Ví dụ request​

Phản hồi (Response)​

5. Cập nhật quà tặng​

Endpoint​

Tham số đường dẫn (Path Parameters)​

Dữ liệu được gửi đi (Request Body)​

Ví dụ request​

Phản hồi (Response)​

6. Xoá quà tặng​

Endpoint​

Tham số đường dẫn (Path Parameters)​

Ví dụ request​

Phản hồi (Response)​

1. Đối tượng quà tặng (Gift)

Bảng thuộc tính Gift

Giá trị enum

Bảng integrationType

Bảng redeemMethod

Bảng discountVoucherConfig

2. Lấy danh sách quà tặng

Endpoint

Tham số truy vấn (Query Parameters)

Ví dụ request

Phản hồi (Response)

3. Lấy chi tiết quà tặng

Endpoint

Tham số đường dẫn (Path Parameters)

Ví dụ request

Phản hồi (Response)

4. Tạo quà tặng

Endpoint

Dữ liệu được gửi đi (Request Body)

Ví dụ request

Phản hồi (Response)

5. Cập nhật quà tặng

Endpoint

Tham số đường dẫn (Path Parameters)

Dữ liệu được gửi đi (Request Body)

Ví dụ request

Phản hồi (Response)

6. Xoá quà tặng

Endpoint

Tham số đường dẫn (Path Parameters)

Ví dụ request

Phản hồi (Response)