Module quản lý mã đổi quà

Mô tả tính năng

Tiền tố API thống nhất là http(s)://<your-domain>

Nên sử dụng HTTPS trong môi trường sản xuất để bảo mật mã thông báo xác thực. HTTP chỉ được khuyến nghị cho môi trường phát triển.

Hệ thống mã đổi thưởng dành riêng cho quản trị viên. Hỗ trợ các tính năng như tạo hàng loạt, quản lý trạng thái và lọc tìm kiếm. Bao gồm chức năng bảo trì để tự động xóa mã đổi quà không hợp lệ. Chủ yếu được sử dụng cho các hoạt động quảng cáo và khuyến khích người dùng.

🔐 Xác thực quản trị viên

Lấy danh sách mã đổi quà

Tên giao diện: Lấy danh sách mã đổi quà
Phương thức HTTP: NHẬN
Đường dẫn: /api/redemption/
Yêu cầu xác thực: Quản trị viên
Mô tả chức năng: Truy xuất thông tin danh sách theo trang của tất cả các mã đổi quà trong hệ thống

💡 Yêu cầu Ví dụ:

const response = await fetch('/api/redemption/?p=1&page_size=20', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ Ví dụ phản hồi thành công:

{
  "success": true,
  "message": "",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "New Year event redemption code",
        "key": "abc123def456",
        "status": 1,
        "quota": 100000,
        "created_time": 1640908800,
        "redeemed_time": 0,
        "expired_time": 1640995200,
        "used_user_id": 0
      }
    ],
    "total": 50,
    "page": 1,
    "page_size": 20
  }
}

❗ Ví dụ phản hồi không thành công:

{
  "success": false,
  "message": "Failed to retrieve redemption code list"
}

🧾 Mô tả trường:

p (Number): Số trang, mặc định là 1
page_size (Number): Mục trên mỗi trang, mặc định là 20
items (Array): Danh sách thông tin mã đổi quà
total (Số): Tổng số mã đổi quà
page (Number): Số trang hiện tại
page_size (Số): Mục trên mỗi trang

Tìm kiếm mã đổi thưởng

Tên giao diện: Tìm kiếm mã đổi thưởng
Phương thức HTTP: NHẬN
Đường dẫn: /api/redemption/search
Yêu cầu xác thực: Quản trị viên
Mô tả chức năng: Tìm kiếm mã đổi thưởng theo từ khóa, hỗ trợ tìm kiếm theo ID và tên

💡 Yêu cầu Ví dụ:

const response = await fetch('/api/redemption/search?keyword=new year&p=1&page_size=20', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ Ví dụ phản hồi thành công:

{
  "success": true,
  "message": "",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "New Year event redemption code",
        "key": "abc123def456",
        "status": 1,
        "quota": 100000
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}

❗ Ví dụ phản hồi không thành công:

{
  "success": false,
  "message": "Failed to search for redemption codes"
}

🧾 Mô tả trường:

keyword (String): Từ khóa tìm kiếm, có thể trùng với tên hoặc ID mã đổi quà
p (Number): Số trang, mặc định là 1
page_size (Number): Mục trên mỗi trang, mặc định là 20

Nhận mã đổi thưởng duy nhất

Tên giao diện: Nhận mã đổi quà duy nhất
Phương thức HTTP: NHẬN
Đường dẫn: /api/redemption/:id
Yêu cầu xác thực: Quản trị viên
Mô tả chức năng: Truy xuất thông tin chi tiết về mã đổi quà được chỉ định

💡 Yêu cầu Ví dụ:

const response = await fetch('/api/redemption/123', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ Ví dụ phản hồi thành công:

{
  "success": true,
  "message": "",
  "data": {
    "id": 123,
    "name": "New Year event redemption code",
    "key": "abc123def456",
    "status": 1,
    "quota": 100000,
    "created_time": 1640908800,
    "redeemed_time": 0,
    "expired_time": 1640995200,
    "used_user_id": 0,
    "user_id": 1
  }
}

❗ Ví dụ phản hồi không thành công:

{
  "success": false,
  "message": "Redemption code does not exist"
}

🧾 Mô tả trường:

id (Số): ID mã đổi quà, được chuyển qua đường dẫn URL

###Tạo mã đổi quà

Tên giao diện: Tạo mã đổi quà
Phương thức HTTP: POST
Đường dẫn: /api/redemption/
Yêu cầu xác thực: Quản trị viên
Mô tả chức năng: Tạo mã đổi quà hàng loạt, hỗ trợ tạo nhiều mã cùng lúc

💡 Yêu cầu Ví dụ:

const response = await fetch('/api/redemption/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  },
  body: JSON.stringify({
    name: "Spring Festival event redemption code",
    count: 10,
    quota: 100000,
    expired_time: 1640995200
  })
});
const data = await response.json();

✅ Ví dụ phản hồi thành công:

{
  "success": true,
  "message": "",
  "data": [
    "abc123def456",
    "def456ghi789",
    "ghi789jkl012"
  ]
}

❗ Ví dụ phản hồi không thành công:

{
  "success": false,
  "message": "Redemption code name length must be between 1 and 20"
}

🧾 Mô tả trường:

name (String): Tên mã đổi quà, độ dài phải từ 1 đến 20 ký tự
count (Number): Số mã đổi quà cần tạo, phải lớn hơn 0 và không vượt quá 100
quota (Số): Số tiền hạn ngạch cho mỗi mã đổi quà
expired_time (Number): Dấu thời gian hết hạn, 0 nghĩa là không bao giờ hết hạn
data (Array): Danh sách mã đổi thưởng được tạo thành công

Cập nhật mã đổi thưởng

Tên giao diện: Cập nhật mã đổi thưởng
Phương thức HTTP: PUT
Đường dẫn: /api/redemption/
Yêu cầu xác thực: Quản trị viên
Mô tả chức năng: Cập nhật thông tin mã đổi thưởng, chỉ hỗ trợ cập nhật trạng thái hoặc cập nhật đầy đủ

💡 Ví dụ về yêu cầu (Cập nhật đầy đủ):

const response = await fetch('/api/redemption/', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  },
  body: JSON.stringify({
    id: 123,
    name: "Updated redemption code name",
    quota: 200000,
    expired_time: 1672531200
  })
});
const data = await response.json();

💡 Ví dụ về yêu cầu (Chỉ cập nhật trạng thái):

const response = await fetch('/api/redemption/?status_only=true', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  },
  body: JSON.stringify({
    id: 123,
    status: 2
  })
});
const data = await response.json();

✅ Ví dụ phản hồi thành công:

{
  "success": true,
  "message": "",
  "data": {
    "id": 123,
    "name": "Updated redemption code name",
    "status": 1,
    "quota": 200000,
    "expired_time": 1672531200
  }
}

❗ Ví dụ phản hồi không thành công:

{
  "success": false,
  "message": "Expiration time cannot be earlier than the current time"
}

🧾 Mô tả trường:

id (Số): ID mã đổi quà, bắt buộc
status_only (Tham số truy vấn): Có chỉ cập nhật trạng thái hay không
name (String): Tên mã đổi quà, tùy chọn
quota (Number): Số lượng hạn ngạch, tùy chọn
expired_time (Number): Dấu thời gian hết hạn, tùy chọn
status (Số): Trạng thái mã đổi quà, tùy chọn

Xóa mã đổi quà không hợp lệ

Tên giao diện: Xóa mã đổi quà không hợp lệ
Phương thức HTTP: XÓA
Đường dẫn: /api/redemption/invalid
Yêu cầu xác thực: Quản trị viên
Mô tả chức năng: Xóa hàng loạt mã đổi quà đã sử dụng, bị vô hiệu hóa hoặc hết hạn

💡 Yêu cầu Ví dụ:

const response = await fetch('/api/redemption/invalid', {
  method: 'DELETE',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ Ví dụ phản hồi thành công:

{
  "success": true,
  "message": "",
  "data": 15
}

❗ Ví dụ phản hồi không thành công:

{
  "success": false,
  "message": "Deletion failed"
}

🧾 Mô tả trường:

Không có tham số yêu cầu
data (Số): Số mã đổi quà đã xóa

Xóa mã đổi quà

Tên giao diện: Xóa mã đổi quà
Phương thức HTTP: XÓA
Đường dẫn: /api/redemption/:id
Yêu cầu xác thực: Quản trị viên
Mô tả chức năng: Xóa mã quy đổi đã chỉ định

💡 Yêu cầu Ví dụ:

const response = await fetch('/api/redemption/123', {
  method: 'DELETE',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your_admin_token',
    'New-Api-User': 'your_user_id'
  }
});
const data = await response.json();

✅ Ví dụ phản hồi thành công:

{
  "success": true,
  "message": ""
}

❗ Ví dụ phản hồi không thành công:

{
  "success": false,
  "message": "Redemption code does not exist"
}

🧾 Mô tả trường:

id (Số): ID mã đổi quà, được chuyển qua đường dẫn URL

🔐 Xác thực quản trị viên

Lấy danh sách mã đổi quà

Tìm kiếm mã đổi thưởng

Nhận mã đổi thưởng duy nhất

Cập nhật mã đổi thưởng

Xóa mã đổi quà không hợp lệ

Xóa mã đổi quà

Mục lục