Wixtar Member Points History

Description

Wixtar 全通路會員中介平台 - 會員點數歷程查詢 API。提供外部平台透過全通路 API 中介層發送點數歷程查詢請求至 Wixtar 會員平台 (GET /v1/public/members/points/history)。支援以會員編號 (vip_id)、手機號碼 (mobile)、外部平台與卡號組合 (external_platform + external_card_no) 或身分綁定組合 (identity_type + identity_value) 查詢會員之點數增減記錄、異動原因與時間。

Resource

GET /v1/member/wixtar/points/history

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

Name	Type	Description
sdate	string	查詢起始日期 (格式: YYYY-MM-DD)
edate	string	查詢結束日期 (格式: YYYY-MM-DD)
vip_id	string	(optional) 會員編號 (查找鍵之一)
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 所屬品牌)
point_type	string	(optional) 點數類型 (1=一般點數, 2=活動點數)

Request Example

GET /v1/member/wixtar/points/history?vip_id=CM00000001&sdate=2026-06-01&edate=2026-06-30 HTTP/1.1
Host: localhost:5000
Authorization: Bearer <omniplatform_token>
X-Member-Center-Token: <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
items	Items[]	點數異動明細列表

Response Body Parameters - Items

Name	Type	Description
brand_id	string	品牌編號
shop_id	string	門市編號
source_id	string	來源單號
input_date	string	單據日期（YYYY-MM-DD HH:mm:ss）
deadline	string	點數到期日（YYYY-MM-DD HH:mm:ss）
point_type	string	點數類型：1=銷售新增(+)；2=銷退減少(-)；3=兌換點數(-)；4=兌換銷退(+)；5=點數轉出(-)；6=點數轉入(+)；7=活動扣點(-)；8=活動贈點(+)；A=人工扣點(-)；B=人工加點(+)；Y=點數歸零加點(+)；Z=點數歸零扣點(-)
points	integer	異動點數
amount	number	消費金額
total_valid_points	integer	異動後有效點數快照
point_memo	string	點數備註

Response Example - Http Code = 200

{
  "status": 200,
  "code": "000000",
  "message": "Success",
  "data": {
    "items": [
      {
        "brand_id": "24436074",
        "shop_id": "S001",
        "source_id": "POS20260604001",
        "input_date": "2026-06-04 09:15:23",
        "deadline": "2027-06-03 00:00:00",
        "point_type": "1",
        "points": 15,
        "amount": 300.0,
        "total_valid_points": 500,
        "point_memo": "交易累點"
      }
    ]
  }
}

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

{
  "status": 200,
  "code": "400",
  "message": "缺少必填欄位：sdate（欄位代號：sdate）；缺少必填欄位：edate（欄位代號：edate）",
  "data": {
    "errors_zh": [
      "缺少必填欄位：sdate（欄位代號：sdate）",
      "缺少必填欄位：edate（欄位代號：edate）"
    ],
    "errors": [
      {
        "type": "missing",
        "loc": [
          "query",
          "sdate"
        ],
        "msg": "Field required",
        "input": {}
      },
      {
        "type": "missing",
        "loc": [
          "query",
          "edate"
        ],
        "msg": "Field required",
        "input": {}
      }
    ]
  }
}

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 point_type不合法

{
  "status": 200,
  "code": "400",
  "message": "point_type 不合法，合法值為：1, 2, 3, 4, 5, 6, 7, 8, A, B, Y, Z"
}

Response Example 錯誤回應 - 400 identity查詢需帶brand_id

{
  "status": 200,
  "code": "400",
  "message": "identity 查詢需帶 brand_id 或使用集團 Token"
}

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

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

Response Example 錯誤回應 - 500 查詢點數歷程失敗

{
  "status": 200,
  "code": "500",
  "message": "查詢點數歷程失敗"
}