Wixtar Member Points Manage

Description

Wixtar 全通路會員中介平台 - 會員點數增減 API。提供外部平台透過全通路 API 中介層發送點數增減請求至 Wixtar 會員平台 (POST /v1/public/members/points)。支援加點（正數）與扣點（負數），不可為 0。支援以會員編號 (vip_id)、手機號碼 (mobile)、外部平台與卡號組合 (external_platform + external_card_no) 或身分綁定組合 (identity_type + identity_value) 指定目標會員。

Resource

POST /v1/member/wixtar/points

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	會員編號 (長度 1..20)
source_id	string	來源單號 / 銷貨單號 (長度 1..40)
point_type	string	點數類型：`1`=銷售新增(+)；`2`=銷退減少(-)；`3`=兌換點數(-)；`4`=兌換銷退(+)；`5`=點數轉出(-)；`6`=點數轉入(+)；`7`=活動扣點(-)；`8`=活動贈點(+)；`A`=人工扣點(-)；`B`=人工加點(+)；`Y`=點數歸零加點(+)；`Z`=點數歸零扣點(-)
points	integer	異動點數 (正整數，數值須 > 0，正負向由 point_type 決定)
amount	number	關聯消費金額 (數值 ≥ 0)
occurred_at	string	發生時間 (格式: `YYYY-MM-DD HH:mm:ss`)
brand_id	string	(optional) 品牌編號 (未帶時自動取 token_brand_id 或集團範圍)

Request Example

{
  "request_id": "550e8400-e29b-41d4-a716-446655440002",
  "brand_id": "24436074",
  "vip_id": "CM00000001",
  "source_id": "POS20260604001",
  "point_type": "B",
  "points": 100,
  "amount": 1000.0,
  "occurred_at": "2026-06-04 10:00: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
source_id	string	來源單號
remaining_total_points	integer	異動後可用點數（已扣除 active freeze）
deadline	string	點數到期時間 (格式: YYYY-MM-DD HH:mm:ss，永久有效或扣點時為 null)

Response Example - Http Code = 200

{
  "status": 200,
  "code": "000000",
  "message": "Success",
  "data": {
    "source_id": "POS20260604001",
    "remaining_total_points": 600,
    "deadline": "2026-12-31 23:59:59"
  }
}

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

{
  "status": 200,
  "code": "400",
  "message": "缺少必填欄位：request_id（欄位代號：request_id）；缺少必填欄位：vip_id（欄位代號：vip_id）；缺少必填欄位：source_id（欄位代號：source_id）；缺少必填欄位：point_type（欄位代號：point_type）；缺少必填欄位：points（欄位代號：points）；缺少必填欄位：amount（欄位代號：amount）；缺少必填欄位：occurred_at（欄位代號：occurred_at）",
  "data": {
    "errors_zh": [
      "缺少必填欄位：request_id（欄位代號：request_id）",
      "缺少必填欄位：vip_id（欄位代號：vip_id）",
      "缺少必填欄位：source_id（欄位代號：source_id）",
      "缺少必填欄位：point_type（欄位代號：point_type）",
      "缺少必填欄位：points（欄位代號：points）",
      "缺少必填欄位：amount（欄位代號：amount）",
      "缺少必填欄位：occurred_at（欄位代號：occurred_at）"
    ],
    "errors": [
      {
        "type": "missing",
        "loc": [
          "body",
          "request_id"
        ],
        "msg": "Field required",
        "input": {}
      },
      {
        "type": "missing",
        "loc": [
          "body",
          "vip_id"
        ],
        "msg": "Field required",
        "input": {}
      },
      {
        "type": "missing",
        "loc": [
          "body",
          "source_id"
        ],
        "msg": "Field required",
        "input": {}
      },
      {
        "type": "missing",
        "loc": [
          "body",
          "point_type"
        ],
        "msg": "Field required",
        "input": {}
      },
      {
        "type": "missing",
        "loc": [
          "body",
          "points"
        ],
        "msg": "Field required",
        "input": {}
      },
      {
        "type": "missing",
        "loc": [
          "body",
          "amount"
        ],
        "msg": "Field required",
        "input": {}
      },
      {
        "type": "missing",
        "loc": [
          "body",
          "occurred_at"
        ],
        "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 brand_id無法確定

{
  "status": 200,
  "code": "400",
  "message": "brand_id 未提供且 Token 無品牌歸屬，無法確定操作品牌"
}

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

{
  "status": 200,
  "code": "400",
  "message": "point_type 不合法，合法值為：1~8、A、B、Y、Z"
}

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

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

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

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

Response Example 錯誤回應 - 400 點數異動業務錯誤（動態訊息）

{
  "status": 200,
  "code": "400",
  "message": "點數不足，無法扣除"
}

Response Example 錯誤回應 - 500 點數異動失敗

{
  "status": 200,
  "code": "500",
  "message": "點數異動失敗"
}