Skip to content

Get Ticket Info V2

Description

取得票劵資訊。支援兩種查詢模式： - 一般票券：id 為內部票券序號（TicketIsuse.tkno），走既有流程 - Ocard 票券（僅 member_source=OCARD + WPOS 站台）：id 為 Ocard coupon_list[].pos_code（= TicketBatch.ProdID），查 TicketBatch 回傳商品資訊

注意：Ocard + MajiPOS 或 Ocard + 外部 POS 情境回傳 400 Bad Request。

Resource

GET /v2/ticket/info

Authorization

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

Request Body Parameters

Name Type Description
id string 票券編號。一般票券：TicketIsuse.tkno；Ocard 票券：coupon_list[].pos_code（= TicketBatch.ProdID）
order_id string 訂單編號
(optional)
store_id string 門市代碼
(optional)
language string
(enum)		 語系
ALLOWED VALUES:
  • TRADITIONAL_CHINESE: 繁體中文
  • JAPANESE: 日語
  • KOREAN: 韓語
  • ENGLISH: 英語
  • FRENCH: 法語
  • INDONESIAN: 印尼語
  • THAI: 泰語
  • VIETNAMESE: 越南語
  • SPANISH: 西班牙語
  • GERMAN: 德語
  • RUSSIAN: 俄語
(optional)

Request

GET /v2/ticket/info?id=xxPkOwMnrV6J/EWqacTxYQ==&order_id=test21092200001

Response Body Parameters

Name Type Description
id string 票劵編號
product_id string 商品編號
product_name string 商品名稱
price integer 商品金額
redeem_product_id string 兌換商品編號
kind_id string 種類編號
kind_name string 種類名稱
kind_type string 種類屬性
ALLOWED VALUES:
  • GIFT_VOUCHER
  • SALE_EVENT_COUPON
  • ENTRANCE_TICKET
  • DISCOUNT_COUPON
  • CASH_COUPON
  • PRODUCT_SPECIFIC_COUPONS
product_ticket_type string 商品票券型態
ALLOWED VALUES:
  • PRODUCT_VOUCHER
  • PRODUCT_SPECIFIC_DISCOUNT_COUPON
  • PRODUCT_SPECIFIC_CASH_COUPON
(option)
available bool 是否可以使用票券
start_date string 有效起日
EXAMPLE "2020-01-01 12:00:00"
end_date string 有效迄日
EXAMPLE "2020-01-01 12:00:00"
message string 提示訊息
discount integer 折扣率/折價金額
假設此值為70
若為折價券、商品折價券，代表折價70元
若為折扣券、商品折扣券，代表打7折
(optional)
vip_id string 會員編號
ticket_status string 票券狀態
ALLOWED VALUES:
  • 0=建立
  • 1=銷售
  • 2=兌回
  • 3=黑名單
  • 4=銷毀
  • 5=領用
  • 6=公關
back_shop string 核銷門市編號
(optional)
back_date string 核銷日期
(optional)
decrypted_id string 票券明碼編號，公司有使用票券加密功能才回傳此參數
(optional)
gift_points integer 花費 Ocard 點數；point_gift 型票券時為點數數量，否則 0。僅 Ocard 流程回傳，非 Ocard 票券不含此欄位。
(optional)

Response kind_type

kind_type description
GIFT_VOUCHER 禮券
SALE_EVENT_COUPON 抵用券
ENTRANCE_TICKET 入場券
DISCOUNT_COUPON 折扣券
CASH_COUPON 折價券
PRODUCT_SPECIFIC_COUPONS 商品券

Response product_ticket_type

product_ticket_type description
PRODUCT_VOUCHER 商品提貨券
PRODUCT_SPECIFIC_DISCOUNT_COUPON 商品折扣券
PRODUCT_SPECIFIC_CASH_COUPON 商品折價券

Response

{
    "id": "wNcOYVd/uBrbnazAAK1ipQ==",
    "product_id": "A01001",
    "product_name": "90元折價券",
    "price": 90,
    "redeem_product_id": "",
    "kind_id": "T2",
    "kind_name": "折價券",
    "kind_type": "CASH_COUPON",
    "product_ticket_type": "PRODUCT_SPECIFIC",
    "start_date": "2021-09-15 15:26:59",
    "end_date": "2022-08-17 23:59:59",
    "available": true,
    "message": "",
    "discount": 90,
    "vip_id": "ABC001",
    "ticket_status": "2",
    "back_shop": "000030",
    "back_date": "2022-08-16 23:59:59"
}

Ocard 票券流程（member_source=OCARD + WPOS 站台）

當站台為 Ocard 且 POS 為 WPOS（siteinfo.enable_use_wise=1），且 id 在 TicketIsuse 找不到對應記錄時，系統執行以下流程：

  1. 以 id（= coupon_list[].pos_code）查詢 TicketBatch 取得票券基本資訊
  2. 呼叫 Ocard /checkRedeem API 驗證票券可用性
  3. 依驗證結果設定 available 與 message

票券基本資訊（kind_type / product_id 等）在任何情況下都會回傳，讓 KIOSK 可顯示票券名稱；available 欄位才是是否可使用的依據。

Ocard checkRedeem 驗證邏輯

Ocard response.code 處理 available
500 可用（同時檢查商品停售） true（停售時為 false）
305（token 過期） 自動重新認證後重試一次 重試成功→ true；失敗→ false
其他 code 不可用，記錄 log false
呼叫例外 不可用，記錄 log false

注意：票券不可用時，message 為固定的使用者友善訊息，不揭露 Ocard 原始錯誤內容。

product_id 回傳規則（SA v1.5 §4.4）

kind_type product_id 說明
DISCOUNT_COUPON (4) ProdID（pos_code 本身） 整單百分比折扣，無指定商品
CASH_COUPON (5) ProdID（pos_code 本身） 整單固定金額折抵，無指定商品
PRODUCT_SPECIFIC_COUPONS (6) RedeemProdID 兌換目標商品（需加入購物車）

Ocard 票券 Response 欄位

Ocard 流程與一般票券回傳欄位對齊，以下欄位因無 TicketIsuse 記錄而不回傳： ticket_status、back_shop、back_date、vip_id、decrypted_id

Response Example — Ocard 商品券（KindType=6，point_gift 型）

{
    "id": "0PM202512160001",
    "product_id": "REDEEM_PROD_001",
    "product_name": "提貨券A",
    "price": 0,
    "redeem_product_id": "REDEEM_PROD_001",
    "kind_id": "T6",
    "kind_name": "商品券",
    "kind_type": "PRODUCT_SPECIFIC_COUPONS",
    "product_ticket_type": "PRODUCT_VOUCHER",
    "start_date": "2025-01-01 00:00:00",
    "end_date": "2026-12-31 23:59:59",
    "available": true,
    "message": "",
    "gift_points": 100
}

Response Example — Ocard 折扣券（KindType=4，coupon 型）

{
    "id": "0PM202512160002",
    "product_id": "0PM202512160002",
    "product_name": "全單八折券",
    "price": 80,
    "redeem_product_id": "",
    "kind_id": "T4",
    "kind_name": "折扣券",
    "kind_type": "DISCOUNT_COUPON",
    "start_date": "2025-01-01 00:00:00",
    "end_date": "2026-12-31 23:59:59",
    "available": true,
    "message": "",
    "gift_points": 0
}

Error Response — Ocard + 非 WPOS 情境（400）

{
    "message": "Ocard 票券查詢僅支援 WPOS 情境"
}