Wixtar Member Vouchers Check Redeem
Description
Wixtar 全通路會員中介平台 - 票券使用查詢 (預檢) API。提供外部平台在結帳前確認會員持有的指定票券是否可用於目前交易進行核銷 (POST /v1/public/members/vouchers/check_redeem)。回傳項目包含票券可否核銷 (can_redeem) 與不可核銷之原因說明 (reject_reason)。
業務與運算邏輯
- 票券號碼清單 (
tk_nos) 為必填：為字串陣列，至少填一筆。
- 查找鍵為選填：會員查找鍵（
vip_id / mobile / external / identity）皆為選填，可全部不帶（純以 tk_nos 查詢票券可用性）；有帶入時依優先序 vip_id → mobile → external → identity 校驗票券歸屬。
- 滿額門檻校驗 (
sale_amt)：帶入本次消費金額時，會檢查票券是否有設定最低消費滿額限制，未達門檻則回傳 can_redeem=false。
- 票券狀態碼 (
status)：1=銷售券、5=領用券、6=公關券；不可核銷或查無此券時為 null。
- 票券代號關聯 (
prod_id)：回傳之 prod_id 欄位即為 Wixtar 票券主檔的 [票券代號(Code)]（反填之 CWISE 促銷代號，即 prod_id = code = 促銷代號），供 POS / 前端直接比對 CWISE 促銷活動進行折抵計算。
Resource
POST /v1/member/wixtar/vouchers/check_redeem
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。
認證模式二擇一：若提供 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 Body Parameters
| Name |
Type |
Description |
| tk_nos |
array of string |
(必填) 票券號碼清單（至少一筆） |
| vip_id |
string |
(optional) 會員編號 (查找鍵優先序 1) |
| mobile |
string |
(optional) 手機號碼 (查找鍵優先序 2) |
| external_platform |
string |
(optional) 外部平台代碼 (查找鍵優先序 3，須搭配 external_card_no) |
| 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) |
| sale_amt |
number |
(optional) 本次消費金額 (用於判斷是否達到消費滿額門檻) |
Request Example
POST /v1/member/wixtar/vouchers/check_redeem HTTP/1.1
Host: localhost:5000
Authorization: Bearer <YOUR_ACCESS_TOKEN>
Content-Type: application/json
{
"vip_id": "CM00000001",
"tk_nos": ["TK00000001"],
"sale_amt": 500
}
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 |
| items |
Items[] |
票券可用性檢查結果清單 |
Response Body Parameters - Items
| Name |
Type |
Description |
| tk_no |
string |
票券號碼 |
| vip_id |
string |
票券實際所屬會員編號 (查無此票券時為 null) |
| vip_name |
string |
票券實際所屬會員姓名 (查無此票券時為 null) |
| batch_id |
string |
票券批號 (查無此票券時為 null) |
| prod_id |
string |
票券代號/商品編號（Wixtar 票券主檔 Code / 批次代碼，對應 POS/CWISE 促銷代號，即 prod_id = code） |
| prod_name |
string |
商品名稱/票券名稱 (查無此票券、查無對應批號主檔、或查無對應商品主檔時為 null) |
| can_redeem |
boolean |
是否可使用 |
| reject_reason |
string |
不可核銷之拒絕原因說明 (符合核銷時為 null) |
| value |
number |
票券面額/折抵價值 |
| sale_amt |
number |
本次交易消費金額 (用於門檻檢核) |
| is_once_discharge |
boolean |
是否一次性使用 (false=可累計使用) |
| status |
string |
票券狀態碼 (1=銷售；5=領用；6=公關 可核銷；查無時為 null) |
Response Example - Http Code = 200 (成功回應)
{
"status": 200,
"code": "000000",
"message": "Success",
"data": {
"items": [
{
"tk_no": "TK00000001",
"vip_id": "CM00000001",
"vip_name": "王小明",
"batch_id": "20260701000001",
"prod_id": "P0001",
"prod_name": "百元折價券",
"can_redeem": true,
"value": 100.0,
"sale_amt": 500.0,
"is_once_discharge": false,
"status": "0"
}
]
}
}
Response Example - Http Code = 200 (單張票券不屬於指定會員)
{
"status": 200,
"code": "000000",
"message": "Success",
"data": {
"items": [
{
"tk_no": "TK00000099",
"can_redeem": false,
"reject_reason": "票券不屬於此會員或查無此票券"
}
]
}
}
Response Example 錯誤回應 - 400 external欄位不成對
{
"status": 200,
"code": "400",
"message": "external_platform 與 external_card_no 必須同時提供或同時省略"
}
{
"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 tk_nos不可為空
{
"status": 200,
"code": "400",
"message": "tk_nos 不可為空，至少需填一張票券號碼"
}
Response Example 錯誤回應 - 404 查無對應會員
{
"status": 200,
"code": "404",
"message": "查無對應會員"
}
Response Example 錯誤回應 - 400 identity查詢需帶brand_id
{
"status": 200,
"code": "400",
"message": "identity 查詢需帶 brand_id 或使用集團 Token"
}
Response Example 錯誤回應 - 400 會員交易處理中
{
"status": 200,
"code": "400",
"message": "會員交易處理中，請稍後再試"
}