Skip to content

Sync Transaction Value Added Data

Description

同步交易加值資料。

NEW POS 交易結束後，會來呼叫此 API 將會員該筆交易的加值資料(點數、集章、儲值) 同步到 WISE，進行核銷或返還。

Resource

POST /v1/order/sync_transaction_value_added_data

Authorization

採用 OAuth 2.0 Bearer Token，詳細使用流程請參考 Auth Login。

Request Body Parameters

Name Type Description
store_id string 門市編號
input_date string 交易日期，格式範例: 2024-05-16 17:29:11
id string 交易編號
sale_type string
(enum)		 交易類型
ALLOWED VALUES:
  • SALE: 銷售
  • SALE_RETURN: 銷退
returned_id string 被退貨單號
(optional)
modified_user_id string 異動人員編號
vip_id string 會員編號
(optional)
type string
(enum)		 傳送類型
ALLOWED VALUES:
  • IMMEDIATE: 即時
  • RETRY: 補傳
points Point[] 點數資料
(optional)

Request Body Parameters - Point

Name Type Description
type string 點數異動類型
ALLOWED VALUES:
  • NEW_CONSUMPTION: 消費新增
  • SALES_RETURN_REDUCTION: 銷退返還
  • EXCHANGE: 點數兌換
  • EXCHANGE_SELL_BACK: 點數兌換銷退
  • TRANSFER_OUT: 點數轉出
  • TRANSFER_IN: 點數轉入
  • ACTIVITY_DEDUCTION_POINTS: 活動扣點
  • ACTIVITY_ACCUMULATED_POINTS: 活動累點
  • ZERO: 點數歸零
point integer 點數
create_date string 建立日期，格式範例: 2024-05-16 17:29:11
create_user string 建立人員編號

Request

{
  "store_id": "000030",
  "input_date": "2020-01-01 20:00:00",
  "id": "0000302024051500001",
  "sale_type": "SALE",
  "modified_user_id":"admin",
  "vip_id": "VIP007",
  "type": "IMMEDIATE",
  "points": [
    {
      "type": "NEW_CONSUMPTION",
      "point": 20,
      "create_date": "2020-01-01 20:00:00",
      "create_user": "admin123"
    },
    {
      "type": "EXCHANGE",
      "point": 72,
      "create_date": "2020-01-01 20:00:00",
      "create_user": "admin123"
    }
  ]
}

Response Body Parameters

Name Type Description
vip_id string 會員編號
vip_group_id string 會員群組編號
vip_group_name string 會員群組名稱
points integer 會員持有點數

Response

Status-Code: 200 OK 

{
  "vip_id": "VIP007",
  "vip_group_id": "A",
  "vip_group_name": "A級會員",
  "points": 998
}

Response

Status-Code: 400 Bad Request 

{
  "code": "VipAppService 回傳的錯誤代碼",
  "message": "VipAppService 回傳的錯誤訊息"
}

Response Error Code

Status-Code code message 說明
400 OAB0001 缺少必填欄位 會員編號 啟用每日額度規則的公司，在銷售方向且實際要折抵點數（EXCHANGE）時未帶 vip_id。沒有點數異動的交易（純現金、訪客）與退貨方向皆不需要帶；其他公司完全不受影響
400 OAB4408 本日額度不足 本次新增。與「點數不足」不同：點數不足是持有點數用完，額度不足是今日可用的份用完但持有點數還有
429 OAB0025 正在處理中，請稍後再試 本次新增。同一會員有另一筆折抵正在處理中。屬暫時狀態，稍後重試即可，不是業務失敗
400 OAB9999 未知錯誤 既有。結果不確定，點數可能已扣。不要自行重送，請提示使用者稍後確認交易狀態。註：點數已折抵成功、僅後續內部處理失敗的情況不會回這個錯誤，一律回 200

其餘沿用 VipAppService 回傳的錯誤代碼。

Notes

每日額度卡控（僅套用於已設定每日額度規則的公司）

  • 銷售方向（sale_type = SALE、點數類型 EXCHANGE）會先檢查當日可用額度，不足時回 OAB4408 且不會扣點。
  • 請求的折抵點數不得超過當日剩餘額度。可用額度請由取得會員資料的 API 讀取 daily_last_points。
  • 重送今天已折抵成功的同一筆交易不會被判額度不足。 例如第一次呼叫在呼叫端逾時、但實際上已折抵成功，以相同請求（相同 id、input_date、vip_id 與點數）重送時，會回 200 並帶回目前的會員點數，不會重複扣點，也不會再佔用一次額度。第一筆仍在處理中時重送會回 OAB0025，稍後再試即可。
  • 重送必須帶與第一次完全相同的 input_date 與 vip_id。 沿用同一個 id 但 input_date 不同時會被視為另一筆折抵而再扣一次點數；vip_id 不同時不視為重送，會依該會員的額度判斷並扣點，但這筆不會計入該會員的當日額度。交易編號不可重複使用。
  • 銷退方向（SALE_RETURN、EXCHANGE_SELL_BACK）不檢查額度，並會回補該筆交易佔用的當日額度。
  • 只有在折抵當日辦理的銷退才會退還點數。 每日額度不回溯調整，點數同理：原交易的折抵不是發生在今天時，本 API 仍回 200，但不會退還點數、也不會有額度回補，回應內容為說明訊息而非會員點數資料。跨日之後才要退還點數的情況請走人工處理。
  • 銷退時 returned_id 必須帶原交易編號，且 id 應為新的退貨單號。未帶 returned_id 時的兩種後果都不會反映在回應上（仍回 200）：
  • id 帶新的退貨單號：當日額度不會回補（回補是以原交易編號為鍵）。
  • id 沿用原交易編號：點數不會退回，但當日額度會回補。
  • 銷退是以原交易編號整筆沖銷，不是按本次送出的點數金額。因此交易編號不可重複使用，否則銷退會一併沖銷同編號下的其他折抵紀錄。
  • 未設定每日額度規則的公司（包含所有既有客戶）行為完全不變。

併發

同一會員同時發生多筆折抵時會序列化處理，避免兩筆都通過額度檢查而超扣。被擋下的請求回 OAB0025。此機制只套用於已設定每日額度規則的公司。