Wixtar Member Vouchers

Description

Wixtar 全通路會員中介平台 - 會員票券清單查詢 API。提供外部平台透過全通路 API 中介層發送票券清單查詢請求至 Wixtar 會員平台 (GET /v1/public/members/vouchers)。

業務與運算邏輯

票券狀態分類 (voucher_status)：
all：查詢全部票券（預設），回傳 available_vouchers 與 history_vouchers。
available：僅查詢可使用票券（狀態為銷售 status=1、領用 status=5 或公關 status=6 且在有效期限 valid_date_begin ~ valid_date 內）。
history：僅查詢歷史票券（已使用 status=2 或已過期之票券）。
歷史票券日期區間 (sdate, edate)：當 voucher_status 為 all 或 history 時為必填（格式 YYYY-MM-DD），用於篩選歷史票券區間（已過期以 valid_date 判斷，已使用以 redeem_date 判斷）。
Wixtar 票券狀態碼 (status) 定義：
1：銷售（付費購買/銷售之票券）
5：領用（活動贈送、會員領取之贈券）
6：公關（公關招待發送之票券）
2：兌回 / 已使用（出現在 history_vouchers，並附帶 redeem_date）
9：銷毀 / 作廢
查找鍵優先序：依 vip_id → mobile → external_platform + external_card_no → identity_type + identity_value 優先序，取首個有值者發送查詢。
品牌範圍 (brand_id)：brand_id 有值查該品牌；未帶或空字串則自動取 token_brand_id 篩選；token 為集團 Token 時查集團範圍。

Resource

GET /v1/member/wixtar/vouchers

Authorization

採用 OAuth 2.0 Bearer Token（全通路 Token），並支援以下兩種 Wixtar 認證模式（兩者擇一提供）： * 模式 1 (裝置端自管 Token，推薦)：於 Header 帶入 X-Member-Center-Token（由 Wixtar Member Token 取得），此時 X-Client-Id 與 X-Shop-Id 為選填。 * 模式 2 (後端代管 Token，向後相容)：未帶入 X-Member-Center-Token 時，必須在 Header 提供 X-Client-Id 與 X-Shop-Id，全通路將自動依後台設定與 Redis 快取代管換發 Token。

Request Headers

認證模式二擇一：若提供 X-Member-Center-Token，則 X-Client-Id 與 X-Shop-Id 為選填；若未提供 X-Member-Center-Token，則 X-Client-Id 與 X-Shop-Id 為必填。

Name	Type	Description
X-Member-Center-Token	string	(optional) 裝置端自管之 Wixtar Access Token (由 `POST /v1/member/wixtar/token` 取得)。若有提供則優先以此 Token 轉發 Wixtar
X-Client-Id	string	(optional/條件必填) POS 機或呼叫端設備代碼。若未提供 `X-Member-Center-Token` 則為必填
X-Shop-Id	string	(optional/條件必填) 門市代碼。若未提供 `X-Member-Center-Token` 則為必填

Request Query Parameters

Name	Type	Description
vip_id	string	(optional) 會員編號 (查找鍵優先序 1)
mobile	string	(optional) 手機號碼 (查找鍵優先序 2)
external_platform	string	(optional) 外部平台代碼 (查找鍵優先序 3，須搭配 `external_card_no`；合法值 1~13)
external_card_no	string	(optional) 外部會員卡號 (查找鍵優先序 3，須搭配 `external_platform`)
identity_type	string	(optional) 身分綁定類型 (查找鍵優先序 4，須搭配 `identity_value`；2=LINE UID)
identity_value	string	(optional) 身分綁定值 (查找鍵優先序 4，須搭配 `identity_type`)
brand_id	string	(optional) 品牌編號 (有值查該品牌；未帶自動取 token_brand_id 或集團範圍)
voucher_status	string	(optional) 票券狀態分類：`all` (全部，預設)、`available` (可使用)、`history` (歷史票券)
sdate	string	(optional/條件必填) 查詢起始日期 (`YYYY-MM-DD`，當 `voucher_status` 為 `all` 或 `history` 時為必填)
edate	string	(optional/條件必填) 查詢結束日期 (`YYYY-MM-DD`，當 `voucher_status` 為 `all` 或 `history` 時為必填)

Request Example

GET /v1/member/wixtar/vouchers?vip_id=CM00000001&voucher_status=available HTTP/1.1
Host: localhost:5000
Authorization: Bearer <YOUR_ACCESS_TOKEN>

Response Body Parameters

Name	Type	Description
status	integer	HTTP 狀態碼 (例如: 200)
code	string	業務回應代碼 (成功為 "000000")
message	string	回應訊息 (例如: "Success")
data	Data	主要業務資料內容

Response Body Parameters - Data

Name	Type	Description
available_vouchers	Available Vouchers[]	可用票券清單；voucher_status 為 available 或 all 時提供
history_vouchers	History Vouchers[]	歷史票券清單（已使用＋已過期）；voucher_status 為 history 或 all 時提供

Response Body Parameters - Available Vouchers

Name	Type	Description
batch_id	string	票券批號
prod_id	string	票券指定商品編號 (無指定商品為 null)
prod_name	string	票券指定商品名稱 (無指定商品為 null)
tk_no	string	票券號碼
brand_id	string	品牌編號
status	string	票券狀態碼：1=銷售；5=領用；6=公關
valid_date_begin	string	有效起日 (格式: YYYY-MM-DD HH:mm:ss)
valid_date	string	有效迄日 (格式: YYYY-MM-DD HH:mm:ss)
value	number	票券面額/折抵價值
is_once_discharge	boolean	是否一次性使用（false=可累計使用）
description	string	票券說明或規則限制
redeem_date	string	使用日期 (格式: YYYY-MM-DD HH:mm:ss，歷史票券中已使用才有值)

Response Body Parameters - History Vouchers

Name	Type	Description
batch_id	string	票券批號
prod_id	string	票券指定商品編號 (無指定商品為 null)
prod_name	string	票券指定商品名稱 (無指定商品為 null)
tk_no	string	票券號碼
brand_id	string	品牌編號
status	string	票券狀態碼：1=銷售；5=領用；6=公關
valid_date_begin	string	有效起日 (格式: YYYY-MM-DD HH:mm:ss)
valid_date	string	有效迄日 (格式: YYYY-MM-DD HH:mm:ss)
value	number	票券面額/折抵價值
is_once_discharge	boolean	是否一次性使用（false=可累計使用）
description	string	票券說明或規則限制
redeem_date	string	使用日期 (格式: YYYY-MM-DD HH:mm:ss，歷史票券中已使用才有值)

Response Example - Http Code = 200

{
  "status": 200,
  "code": "000000",
  "message": "Success",
  "data": {
    "available_vouchers": [
      {
        "batch_id": "B2026001",
        "prod_id": "P001",
        "prod_name": "春節折扣券商品",
        "tk_no": "TK00000001",
        "brand_id": "24436074",
        "status": "5",
        "valid_date_begin": "2026-01-01 00:00:00",
        "valid_date": "2026-12-31 23:59:59",
        "value": 100.0,
        "is_once_discharge": false,
        "description": "春節限定折扣券"
      }
    ],
    "history_vouchers": [
      {
        "batch_id": "B2025009",
        "prod_id": "P002",
        "prod_name": "會員生日禮券商品",
        "tk_no": "TK00000099",
        "brand_id": "24436074",
        "status": "2",
        "valid_date_begin": "2025-06-01 00:00:00",
        "valid_date": "2026-06-30 23:59:59",
        "redeem_date": "2026-03-15 10:22:00",
        "value": 50.0,
        "is_once_discharge": true,
        "description": "會員生日禮券"
      }
    ]
  }
}

Response Example 錯誤回應 - 400 voucher_status不合法

{
  "status": 200,
  "code": "400",
  "message": "voucher_status 不合法，合法值為：all、available、history"
}

Response Example 錯誤回應 - 400 all/history缺日期區間

{
  "status": 200,
  "code": "400",
  "message": "voucher_status=all 或 history 時 sdate 與 edate 為必填"
}

Response Example 錯誤回應 - 400 sdate格式不合法

{
  "status": 200,
  "code": "400",
  "message": "sdate 格式須為 YYYY-MM-DD"
}

Response Example 錯誤回應 - 400 edate早於sdate

{
  "status": 200,
  "code": "400",
  "message": "edate 不可早於 sdate"
}

Response Example 錯誤回應 - 400 external欄位不成對

{
  "status": 200,
  "code": "400",
  "message": "external_platform 與 external_card_no 必須同時提供或同時省略"
}

Response Example 錯誤回應 - 400 external_platform不合法

{
  "status": 200,
  "code": "400",
  "message": "external_platform 不合法，合法值為：1~13"
}

Response Example 錯誤回應 - 400 identity欄位不成對

{
  "status": 200,
  "code": "400",
  "message": "identity_type 與 identity_value 必須同時提供或同時省略"
}

Response Example 錯誤回應 - 400 identity_type不合法

{
  "status": 200,
  "code": "400",
  "message": "identity_type 不合法，本 API 僅支援 2（會員載具）"
}

Response Example 錯誤回應 - 400 查找鍵全空

{
  "status": 200,
  "code": "400",
  "message": "vip_id、mobile、external_platform + external_card_no、identity_type + identity_value 至少填一個"
}

Response Example 錯誤回應 - 400 identity查詢需帶brand_id

{
  "status": 200,
  "code": "400",
  "message": "identity 查詢需帶 brand_id 或使用集團 Token"
}

Response Example 錯誤回應 - 404 查無對應會員

{
  "status": 200,
  "code": "404",
  "message": "查無對應會員"
}

Response Example 錯誤回應 - 400 會員交易處理中

{
  "status": 200,
  "code": "400",
  "message": "會員交易處理中，請稍後再試"
}