Skip to content

Wixtar Member Update

Description

Wixtar 全通路會員中介平台 - 會員異動 API。提供外部平台更新會員基本資料，透傳至 Wixtar 會員平台 (PUT /v1/public/members/update)。查找鍵依優先序 vip_id → mobile → external_platform + external_card_no → identity_type + identity_value 執行查詢，僅異動有帶值的欄位。

Resource

PUT /v1/member/wixtar/update

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 格式)
vip_id string (optional) 會員編號 (查找鍵，優先序 1)
mobile string (optional) 手機號碼 (查找鍵，優先序 2)
external_platform string (optional) 外部平台代碼 (查找鍵，須與 external_card_no 成對提供，優先序 3)
external_card_no string (optional) 外部會員卡號 (查找鍵，須與 external_platform 成對提供)
identity_type string (optional) 身分綁定類型 (查找鍵，須與 identity_value 成對提供；2=LINE UID，優先序 4)
identity_value string (optional) 身分綁定值 (查找鍵，須與 identity_type 成對提供)
name string (optional) 會員姓名 (有值才異動)
email string (optional) 電子郵箱 (有值才異動)
sex string (optional) 性別 (有值才異動)。
ALLOWED VALUES:
  • M: 男
  • F: 女
  • X: 中性
  • N: 不提供
birthday string (optional) 生日 (格式: YYYY-MM-DD，有值才異動)
buyer_number string (optional) 手機載具號碼 (/ 開頭 + 7 碼，有值才異動)
id_citizen string (optional) 自然人憑證 (2 碼大寫英文 + 14 碼數字，有值才異動)
updated_at string (optional) 來源系統異動時間 (ISO 8601 格式)

Request Example

{
  "request_id": "550e8400-e29b-41d4-a716-446655440001",
  "vip_id": "CM00000001",
  "email": "[email protected]",
  "updated_at": "2026-08-03T15:00:00+08:00"
}

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 會員編號
updated_fields list[string] 實際異動的欄位名稱
member_status string 會員狀態：0=正常；1=停權；2=刪除

Response Example - Http Code = 200

{
  "status": 200,
  "code": "000000",
  "message": "Success",
  "data": {
    "vip_id": "CM00000001",
    "updated_fields": [
      "email"
    ],
    "member_status": "0"
  }
}

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

{
  "status": 200,
  "code": "400",
  "message": "缺少必填欄位：request_id（欄位代號：request_id）",
  "data": {
    "errors_zh": [
      "缺少必填欄位：request_id（欄位代號：request_id）"
    ],
    "errors": [
      {
        "type": "missing",
        "loc": [
          "body",
          "request_id"
        ],
        "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 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 錯誤回應 - 400 未帶任何可更新欄位

{
  "status": 200,
  "code": "400",
  "message": "未帶任何可更新欄位"
}

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

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

Response Example 錯誤回應 - 500 會員資料更新失敗

{
  "status": 200,
  "code": "500",
  "message": "會員資料更新失敗"
}