Wixtar Member Vouchers Reverse

Description

Wixtar 全通路會員中介平台 - 票券反核銷 API。提供外部平台發送票券反核銷請求至 Wixtar 會員平台 (POST /v1/public/members/vouchers/reverse)。

業務與運算邏輯

1. 反核銷狀態恢復：僅允許反核銷狀態為已使用 (status=2) 的票券。反核銷成功後，票券將還原回復為核銷前之初始或可用狀態（如 status=1 正常未用、status=5 可使用或 status=6 處理中）。
2. 單號追蹤：必須帶入本次退貨/反核銷單號 reverse_sale_id (長度 1..40)；並提供原銷貨單號 original_sale_id 或原核銷請求識別碼 original_request_id 至少其中一個。
3. 反核銷時間 (reverse_at)：格式為 YYYY-MM-DD HH:MM:SS；未帶入預設取系統當前時間。

Resource

POST /v1/member/wixtar/vouchers/reverse

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)
reverse_sale_id	string	(必填) 退貨/反核銷單號 (長度 1..40)
tk_nos	array of string	(必填) 欲反核銷之票券號碼清單 (至少一筆，不可為空陣列)
original_sale_id	string	(條件必填) 原銷貨單號 (與 original_request_id 至少需提供其中一個)
original_request_id	string	(條件必填) 原核銷請求識別碼 (與 original_sale_id 至少需提供其中一個)
reverse_at	string	(optional) 反核銷時間 (YYYY-MM-DD HH:MM:SS，未帶預設取系統時間)
brand_id	string	(optional) 品牌編號 (未帶自動取 token_brand_id)

Request Example

{
  "request_id": "550e8400-e29b-41d4-a716-446655440006",
  "vip_id": "CM00000001",
  "original_sale_id": "POS20260622001",
  "reverse_sale_id": "RTN20260622001",
  "tk_nos": [
    "TK00000001",
    "TK00000002"
  ],
  "reverse_at": "2026-06-22 11: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
items	Items[]	各票券反核銷結果

Response Body Parameters - Items

Name	Type	Description
tk_no	string	票券號碼
status	string	反核銷後票券狀態（恢復為核銷前的原始狀態；1=銷售；5=領用；6=公關）

Response Example - Http Code = 200

{
  "status": 200,
  "code": "000000",
  "message": "Success",
  "data": {
    "items": [
      {
        "tk_no": "TK00000001",
        "status": "5"
      },
      {
        "tk_no": "TK00000002",
        "status": "1"
      }
    ]
  }
}

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

{
  "status": 200,
  "code": "400",
  "message": "缺少必填欄位：request_id（欄位代號：request_id）；缺少必填欄位：vip_id（欄位代號：vip_id）；缺少必填欄位：tk_nos（欄位代號：tk_nos）；缺少必填欄位：reverse_sale_id（欄位代號：reverse_sale_id）",
  "data": {
    "errors_zh": [
      "缺少必填欄位：request_id（欄位代號：request_id）",
      "缺少必填欄位：vip_id（欄位代號：vip_id）",
      "缺少必填欄位：tk_nos（欄位代號：tk_nos）",
      "缺少必填欄位：reverse_sale_id（欄位代號：reverse_sale_id）"
    ],
    "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",
          "tk_nos"
        ],
        "msg": "Field required",
        "input": {}
      },
      {
        "type": "missing",
        "loc": [
          "body",
          "reverse_sale_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 original_request_id或original_sale_id至少填一

{
  "status": 200,
  "code": "400",
  "message": "original_request_id 或 original_sale_id 至少填一"
}

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

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

Response Example 錯誤回應 - 403 無品牌操作權限

{
  "status": 200,
  "code": "403",
  "message": "無 24436074 品牌操作權限，不允許異動"
}

Response Example 錯誤回應 - 404 票券不屬於此會員或查無此票券

{
  "status": 200,
  "code": "404",
  "message": "票券不屬於此會員或查無此票券：TK00000099"
}

Response Example 錯誤回應 - 403 無操作此票券的品牌權限

{
  "status": 200,
  "code": "403",
  "message": "無操作此票券的品牌權限：TK00000001"
}

Response Example 錯誤回應 - 400 票券狀態不可反核銷

{
  "status": 200,
  "code": "400",
  "message": "票券狀態不可反核銷：TK00000001"
}

Response Example 錯誤回應 - 400 並發衝突

{
  "status": 200,
  "code": "400",
  "message": "票券狀態不可反核銷（並發衝突，請重試）"
}

Response Example 錯誤回應 - 500 票券反核銷失敗

{
  "status": 200,
  "code": "500",
  "message": "票券反核銷失敗"
}