Wixtar Member Profile
Description
Wixtar 全通路會員中介平台 - 會員資料查詢 API。提供外部平台透過全通路 API 中介層發送會員資料查詢請求至 Wixtar 會員平台 (GET /v1/public/members/profile)。支援以會員編號 (vip_id)、手機號碼 (mobile)、外部平台與卡號組合 (external_platform + external_card_no) 或身分綁定組合 (identity_type + identity_value) 查詢會員基本資料、點數、票券等資訊。
Resource
GET /v1/member/wixtar/profile
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 則為必填 |
Query Parameters
| Name |
Type |
Description |
| field |
string |
回傳欄位選擇，逗號分隔。
ALLOWED VALUES:
vip: 回傳會員基本資料point: 回傳點數資料voucher: 回傳可用票券列表point_rules: 回傳點數規則external_data: 回傳外部平台綁定資料buyer_number: 回傳手機載具號碼id_citizen: 回傳自然人憑證
|
| vip_id |
string |
(optional) 會員編號 (查找鍵之一) |
| qrcode |
string |
(optional) 動態會員 QRCode 掃碼字串 (查找鍵之一，由 POS 掃碼取得之 Base64 加密字串) |
| mobile |
string |
(optional) 手機號碼 (查找鍵之一) |
| external_platform |
string |
(optional) 外部平台代碼 (查找鍵之一，須搭配 external_card_no) |
| external_card_no |
string |
(optional) 外部會員卡號 (查找鍵之一，須搭配 external_platform) |
| identity_type |
string |
(optional) 身分綁定類型 (查找鍵之一，須搭配 identity_value；2=LINE UID) |
| identity_value |
string |
(optional) 身分綁定值 (查找鍵之一，須搭配 identity_type) |
| brand_id |
string |
(optional) 品牌編號 (未帶時自動取 token_brand_id 或集團範圍) |
Request Example
GET /v1/member/wixtar/profile?field=vip,point&vip_id=CM00000001 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 |
| vip_id |
string |
會員編號 (VIP ID，field 包含 vip 時出現) |
| name |
string |
會員姓名 (field 包含 vip 時出現) |
| mobile |
string |
手機號碼 (全局唯一鍵，field 包含 vip 時出現) |
| email |
string |
電子信箱 (field 包含 vip 時出現) |
| sex |
string |
性別代碼：M=男、F=女、X=中性、N=不提供 (field 包含 vip 時出現) |
| birthday |
string |
生日 (格式: YYYY-MM-DD，field 包含 vip 時出現) |
| member_status |
string |
會員狀態：0=正常、1=停權、2=刪除 (field 包含 vip 時出現) |
| brand_vip_groups |
Brand Vip Groups[] |
品牌會員等級與權益清單 (field 包含 vip 時出現) |
| buyer_number |
string |
手機載具號碼 (例如: /AB12345，field 包含 buyer_number 時出現) |
| id_citizen |
string |
自然人憑證 (共 16 碼，field 包含 id_citizen 時出現) |
| remaining_total_points |
integer |
當前有效可用總點數 (已扣除活動凍結點數，field 包含 point 時出現) |
| nearest_deadline |
string |
最近一筆點數到期日 (格式: YYYY-MM-DD HH:mm:ss，field 包含 point 時出現) |
| available_vouchers |
Available Vouchers[] |
可用票券清單 (field 包含 voucher 時出現) |
| point_rules |
Point Rules |
品牌點數規則資訊 (field 包含 point_rules 時出現) |
| external_data |
External Data[] |
外部平台綁定清單 (field 包含 external_data 時出現) |
Response Body Parameters - Brand Vip Groups
| Name |
Type |
Description |
| brand_id |
string |
品牌編號 |
| vip_group_id |
string |
會員群組編號 |
| vip_group_name |
string |
會員群組名稱 |
| point_multiplier |
number |
點數倍率 (例如: 1.2 代表積點 1.2 倍) |
| discount_rate |
number |
門市折扣率 (例如: 0.98 代表 98 折；1.00 代表無折扣) |
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 |
票券說明或規則限制 |
Response Body Parameters - Point Rules
Response Body Parameters - Bonus Point Rule
| Name |
Type |
Description |
| spending_per_point |
number |
消費滿多少元累積 1 點 |
| point_multiplier |
number |
點數倍率 (例如: 1.2 代表積點 1.2 倍) |
Response Body Parameters - Cash Redeem Rule
| Name |
Type |
Description |
| rule_id |
string |
折抵/兌換規則代碼 |
| rule_name |
string |
折抵/兌換規則名稱 |
| exchange_rate |
number |
折抵兌換比率 (多少點兌換 1 元或 1 張票券) |
| max_amount |
number |
金額上限 (元，無上限為 null) |
| max_percent |
number |
比例上限 (%，無上限為 null) |
| voucher_prod_id |
string |
兌換票券商品編號 (僅 voucher_redeem_rules 有值；cash_redeem_rule 固定為 null) |
| voucher_prod_name |
string |
兌換票券商品名稱 (僅 voucher_redeem_rules 有值；cash_redeem_rule 固定為 null) |
| description |
string |
票券說明或規則限制 |
Response Body Parameters - Voucher Redeem Rules
| Name |
Type |
Description |
| rule_id |
string |
折抵/兌換規則代碼 |
| rule_name |
string |
折抵/兌換規則名稱 |
| exchange_rate |
number |
折抵兌換比率 (多少點兌換 1 元或 1 張票券) |
| max_amount |
number |
金額上限 (元，無上限為 null) |
| max_percent |
number |
比例上限 (%，無上限為 null) |
| voucher_prod_id |
string |
兌換票券商品編號 (僅 voucher_redeem_rules 有值；cash_redeem_rule 固定為 null) |
| voucher_prod_name |
string |
兌換票券商品名稱 (僅 voucher_redeem_rules 有值；cash_redeem_rule 固定為 null) |
| description |
string |
票券說明或規則限制 |
Response Body Parameters - External Data
| Name |
Type |
Description |
| external_platform |
string |
外部平台代碼：1=精誠商品券、2=怡客、3=萊爾富、4=馬修-層次票券、5=威許、6=Ocard、7=墨攻、8=沂動行銷、9=晶新、10=91APP、11=券券12cm、12=宜睿、13=點點票券(吾蜂)（需搭配 external_card_no） |
| external_card_no |
string |
外部會員卡號 |
Response Example - Http Code = 200
{
"status": 200,
"code": "000000",
"message": "Success",
"data": {
"vip_id": "CM00000001",
"name": "王小明",
"mobile": "0912345678",
"email": "[email protected]",
"sex": "M",
"birthday": "1990-01-15",
"member_status": "0",
"brand_vip_groups": [
{
"brand_id": "24436074",
"vip_group_id": "NORMAL",
"vip_group_name": "一般會員"
}
],
"remaining_total_points": 500,
"nearest_deadline": "2026-12-31 00:00:00"
}
}
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 查找鍵全空
{
"status": 200,
"code": "400",
"message": "vip_id、mobile、external_platform + external_card_no、identity_type + identity_value 至少填一個"
}
Response Example 錯誤回應 - 400 field為必填參數
{
"status": 200,
"code": "400",
"message": "field 為必填參數"
}
Response Example 錯誤回應 - 400 field包含不合法值
{
"status": 200,
"code": "400",
"message": "field 包含不合法值：xxx，合法值為：vip, point, voucher, point_rules, external_data, buyer_number, id_citizen"
}
Response Example 錯誤回應 - 400 identity查詢需帶brand_id
{
"status": 200,
"code": "400",
"message": "identity 查詢需帶 brand_id 或使用集團 Token"
}
Response Example 錯誤回應 - 400 QRCode無效
{
"status": 200,
"code": "400",
"message": "QRCode 無效"
}
Response Example 錯誤回應 - 4101 QRCode已逾期
{
"status": 200,
"code": "4101",
"message": "QRCode 已逾期，請重新產生"
}
Response Example 錯誤回應 - 404 查無對應會員
{
"status": 200,
"code": "404",
"message": "查無對應會員"
}
Response Example 錯誤回應 - 400 會員交易處理中
{
"status": 200,
"code": "400",
"message": "會員交易處理中，請稍後再試"
}
Response Example 錯誤回應 - 400 point_rules查詢需帶brand_id
{
"status": 200,
"code": "400",
"message": "point_rules 查詢需帶 brand_id 或使用品牌 Token"
}
Response Example 錯誤回應 - 500 查詢點數規則失敗
{
"status": 200,
"code": "500",
"message": "查詢點數規則失敗"
}
Response Example 錯誤回應 - 500 查詢外部平台資料失敗
{
"status": 200,
"code": "500",
"message": "查詢外部平台資料失敗"
}
Response Example 錯誤回應 - 500 查無會員完整資訊
{
"status": 200,
"code": "500",
"message": "查無會員完整資訊"
}