Skip to main content

Shop API

The Shop API allows Web User to manage shop-realted management.

Endpoints​

# Endpoints
GET
/web/shop/vouchers/codes/{redeem_code}
# Get voucher
POST
/web/shop/vouchers/codes/{redeem_code}/redeem
# Redeem voucher
GET
/web/shop/vouchers
# Get vouchers
POST
/web/shop/page
# Filter shop items
POST
/web/shop/vouchers/users/page
# Get user vouchers
GET
/web/shop/vouchers/item-total
# Get user vouchers total

Get voucher​

This endpoint gets a voucher.

Request​

GET /web/shop/vouchers/codes/{redeem_code}

Response (VoucherResDTO)​

{
  "success": true,
  "message": "",
  "data": {
    "username": "eWZeVb",
    "nickname": null,
    "voucherName": "Lv. 3 現金券兌換碼",
    "redeemCode": "490aeb5b-4c31-49c4-9e7f-7f5dc86d30fa",
    "status": 2,
    "isValid": true
  }
}

Redeem voucher​

This endpoint redeems a voucher.

Request​

POST /web/shop/vouchers/codes/{redeem_code}/redeem

Response​

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

Get vouchers​

This endpoint gets a list of vouchers.

Request​

GET /web/shop/vouchers

Response (VoucherItemResDTO)​

{
  "success": true,
  "message": "",
  "data": [
    {
      "name": "Lv. 3 現金券兌換碼",
      "description": "10元現金劵兌換碼",
      "priceTag": "$10",
      "level": 3
    }
  ]
}

Filter shop items​

This endpoint filters shop items.

Request (FilterShopItemReqDTO)​

POST /web/shop/page
{
  "pagination": {
    "page": 1,
    "size": 10
  },
  "sortings": [],
  "searchKey": "",
  "subcategoryIds": [
    1,
    3
  ]
}

Response (FilterShopResDTO)​

{
  "success": true,
  "message": "",
  "data": [
    {
      "pagination": {
        "page": 1,
        "size": 10,
        "totalItems": 1,
        "totalPages": 1
      },
      "sortings": [],
      "items": [
        {
          "name": "聖誕節麋鹿車",
          "coin": 0,
          "categoryName": "地上玩具",
          "publishedAt": "2024-07-24T16:14:07Z"
        }
      ]
    }
  ]
}

Filter user vouchers​

This endpoint filters users' vouchers.

Request (FilterUserVoucherReqDTO)​

POST /web/shop/vouchers/users/page
{
  "pagination": {
    "page": 1,
    "size": 10
  },
  "sortings": [],
  "searchKey": "",
  "voucherRedeemStatuses": [
    1,
    3
  ],
  "staffIds": [
    "a75f8b21-f0e8-4750-9b60-76c77cfbb5d8"
  ]
}

Response (FilterUserVoucherResDTO)​

{
  "success": true,
  "message": "",
  "data": [
    {
      "username": "username1",
      "phone": "phone",
      "email": "email",
      "district": "district",
      "serviceNumber": "serviceNumber",
      "staff": "staff",
      "voucherName": "voucherName",
      "voucherRedeemStatus": 2,
      "expiredAt": "2024-11-25T03:37:17.217527Z",
      "redeemAt": "2024-08-16T03:28:38.950301Z",
      "redeemCode": "490aeb5b-4c31-49c4-9e7f-7f5dc86d30fa"
    }
  ]
}

Item total​

Get user vouchers total

Request​

GET /web/shop/vouchers/item-total

Response (VoucherTotal)​

{
  "success": true,
  "message": "",
  "data": [
    {
      "purchased": 7
    }
  ]
}

Resources​

VoucherResDTO​

properties
  • username
    string
    The username of the user.
  • nickname
    string
    The nickname of the user.
  • voucherName
    string
    The name of the voucher.
  • redeemCode
    string
    The url of the redeem QR code.
  • status
    VoucherRedeemStatus
    The voucher redeem status.
  • isValid
    boolean
    It indicates if the voucher is allowed to be redeemed or not. If false, frontend may display '兌換券不存在或已兌換'

VoucherItemResDTO​

properties
  • name
    string
    The name of the voucher.
  • description
    string
    The description of the voucher.
  • priceTag
    string
    The price tag of the voucher.
  • level
    number
    The level.

FilterShopItemReqDTO​

properties
  • pagination
    Pagination
    required
    index-1
    Indicates the page information of the resource.
  • sortings
    Sorting[]
    A list of sorting elements, the order of the list matters.
  • searchKey
    string
    The search key should be about title.
  • subcategoryIds
    Category[]
    The subcategory id of the shop item.

FilterShopResDTO​

properties
  • pagination
    Pagination
    required
    index-1
    Indicates the page information of the resource.
  • sortings
    Sorting[]
    A list of sorting elements, the order of the list matters.
  • items
    FilterShopItemResDTO[]
    A list of filtered elements.

FilterShopItemResDTO​

properties
  • name
    string
    The name id of the shop item.
  • coin
    number
    The coin needed to purchase the shop item.
  • categoryName
    string
    The category name of the shop item.
  • publishedAt
    datetime
    The published time.

FilterUserVoucherReqDTO​

properties
  • pagination
    Pagination
    required
    index-1
    Indicates the page information of the resource.
  • sortings
    Sorting[]
    A list of sorting elements, the order of the list matters.
  • searchKey
    string
    The search key should be about title.
  • VoucherRedeemStatuses
    VoucherRedeemStatus[]
    The voucher redeem status.
  • staffIds
    array
    The list of staff Ids. Multiple selection is allowed. If no staff is selected, please pass empty array to the server.

FilterUserVoucherResDTO​

properties
  • username
    string
    用戶名稱
  • phone
    string
    電話號碼
  • email
    string
    電郵地址
  • district
    string
    所屬地區
  • serviceNumber
    string
    服務編號，
  • staff
    string
    服務職員，
  • voucherName
    string
    The name of the voucher.
  • VoucherRedeemStatus
    VoucherRedeemStatus
    The voucher redeem status.
  • expiredAt
    datetime
    The time when the voucher is expired.
  • redeemedAt
    datetime
    The time when the voucher is redeemed.
  • redeemCode
    string
    The url of the redeem QR code.

VoucherTotal​

properties
  • purchased
    int
    Awaiting exchange

VoucherRedeemStatus​

NameValue
-0
待換領1
已換領2
已過期3