Skip to content

Wixtar Member Register

Description

Wixtar 全通路會員中介平台 - 會員註冊 API。提供外部平台透過全通路 API 中介層發送會員註冊請求至 Wixtar 會員平台 (POST /v1/public/members/register)。手機號碼 (mobile) 為全局唯一鍵。帶 external_platform + external_card_no 時可同步建立外部會員資料。

Resource

POST /v1/member/wixtar/register

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 Body Parameters

Name Type Description
request_id string 冪等識別碼 (UUID 格式)
brand_id string 申請品牌編號 (1 .. 10 字元)
name string 會員姓名 (1 .. 20 字元)
mobile string 手機號碼 (1 .. 20 字元，全局唯一鍵)
email string (optional) 電子郵箱
sex string (optional) 性別。
ALLOWED VALUES:
  • M: 男
  • F: 女
  • X: 中性
  • N: 不提供
birthday string (optional) 生日 (格式: YYYY-MM-DD)
buyer_number string (optional) 手機載具號碼 (/ 開頭 + 7 碼大寫英文/數字/.+-，共 8 碼)
id_citizen string (optional) 自然人憑證 (2 碼大寫英文 + 14 碼數字，共 16 碼)
external_platform string (optional) 外部平台代碼 (需搭配 external_card_no 填寫)。
ALLOWED VALUES:
  • 1: 精誠商品券
  • 2: 怡客
  • 3: 萊爾富
  • 4: 馬修-層次票券
  • 5: 威許
  • 6: Ocard
  • 7: 墨攻
  • 8: 沂動行銷
  • 9: 晶新
  • 10: 91APP
  • 11: 券券12cm
  • 12: 宜睿
  • 13: 點點票券(吾蜂)
external_card_no string (optional) 外部會員卡號 (需搭配 external_platform)
external_id string (optional) 外部會員編號
field string (optional) 回傳欄位選擇，逗號分隔。
ALLOWED VALUES:
  • vip: 回傳 name, mobile, email, sex, birthday, brand_vip_groups
  • point: 回傳 remaining_total_points, nearest_deadline
  • voucher: 回傳 available_vouchers
  • point_rules: 回傳 point_rules 累點/兌點規則
  • external_data: 回傳 external_data 外部平台綁定清單
  • buyer_number: 回傳 buyer_number
  • id_citizen: 回傳 id_citizen

Request Example

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "brand_id": "24436074",
  "name": "王小明",
  "mobile": "0912345678",
  "email": "[email protected]",
  "sex": "M",
  "birthday": "1990-01-15",
  "external_platform": "6",
  "external_card_no": "OC123456",
  "field": "vip,point"
}

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 系統產生的會員編號
member_status string 會員狀態：0=正常；1=停權；2=刪除
created boolean 是否新建（false 表示重複資料）
duplicated boolean 是否偵測到重複會員
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 時出現)
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

Name Type Description
bonus_point_rule Bonus Point Rule 積點規則資訊
cash_redeem_rule Cash Redeem Rule 折現規則資訊 (無規則時為 null)
voucher_redeem_rules Voucher Redeem 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",
    "member_status": "0",
    "created": true,
    "duplicated": false
  }
}

Response Example 錯誤回應 - 400 Pydantic參數驗證（必填欄位缺漏）

{
  "status": 200,
  "code": "400",
  "message": "缺少必填欄位：request_id（欄位代號：request_id）；缺少必填欄位：品牌編號（brand_id）（欄位代號：brand_id）；缺少必填欄位：name（欄位代號：name）；缺少必填欄位：mobile（欄位代號：mobile）",
  "data": {
    "errors_zh": [
      "缺少必填欄位：request_id（欄位代號：request_id）",
      "缺少必填欄位：品牌編號（brand_id）（欄位代號：brand_id）",
      "缺少必填欄位：name（欄位代號：name）",
      "缺少必填欄位：mobile（欄位代號：mobile）"
    ],
    "errors": [
      {
        "type": "missing",
        "loc": [
          "body",
          "request_id"
        ],
        "msg": "Field required",
        "input": {}
      },
      {
        "type": "missing",
        "loc": [
          "body",
          "brand_id"
        ],
        "msg": "Field required",
        "input": {}
      },
      {
        "type": "missing",
        "loc": [
          "body",
          "name"
        ],
        "msg": "Field required",
        "input": {}
      },
      {
        "type": "missing",
        "loc": [
          "body",
          "mobile"
        ],
        "msg": "Field required",
        "input": {}
      }
    ]
  }
}

Response Example 錯誤回應 - 4091 request_id重複但內容不一致

{
  "status": 200,
  "code": "4091",
  "message": "request_id 重複但請求內容不一致"
}

Response Example 錯誤回應 - 400 request_id快取損毀

{
  "status": 200,
  "code": "400",
  "message": "request_id 已完成但快取損毀，請確認後重試"
}

Response Example 錯誤回應 - 400 request_id處理中

{
  "status": 200,
  "code": "400",
  "message": "相同 request_id 處理中，請稍後查詢"
}

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 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 品牌尚未設定預設會員等級

{
  "status": 200,
  "code": "400",
  "message": "品牌 24436074 尚未設定預設會員等級"
}

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": "查詢外部平台資料失敗"
}

Response Example 錯誤回應 - 500 查無會員完整資訊

{
  "status": 200,
  "code": "500",
  "message": "查無會員完整資訊"
}