Skip to content

Check Tickets

Description

批次檢核票券在指定門市當下能不能使用，一次最多 20 張。

回傳只有「能不能用」與不能用的原因，不含兌換商品的內容；需要商品資料時請另外呼叫 Get Ticket Info。

檢核項目與 Get Ticket Info 一致，包含票券本身的狀態與效期、券種規則、可核銷的門市與品牌、抵用規則、兌換商品是否開放兌換，以及多菜單模式下該兌換商品在當下菜單是否開放販售。

「這張票不能用」不是錯誤，會以 200 加上 available = false 表示；400 只用於請求參數本身有問題。

Resource

POST /v2/ticket/check

Authorization

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

Request Body Parameters

Name Type Description
tickets List[string] 票券編號，一次最多 20 張
store_id string 門市編號
(optional) 未帶時以總店檢核，與 Get Ticket Info 相同
menu_id string 菜單編號
(optional) 未帶或帶 0 時不檢核餐期
order_id string 訂單編號
(optional) 整單折扣券、整單折價券與抵用券需要它才能完整檢核

Request

{
  "store_id": "TWD104",
  "menu_id": "M20260908094132703",
  "tickets": ["BA00013991", "BB00013983"]
}

Response Body Parameters

Name Type Description
tickets List[Ticket Result] 逐張的檢核結果

Response Body Parameters - Ticket Result

Name Type Description
ticket_id string 原樣回傳請求中送出的票券編號，可據此對應，不需依賴順序
available boolean 這張票現在能不能使用
message string 不能使用的原因；可以使用時為空字串

Response

{
  "tickets": [
    {
      "ticket_id": "BA00013991",
      "available": true,
      "message": ""
    },
    {
      "ticket_id": "BB00013983",
      "available": false,
      "message": "此商品此時段不販售"
    }
  ]
}

Error

Status Message Description
400 票券清單(tickets)不可為空 未帶 tickets 或帶空陣列
400 一次最多檢核 20 張票券 tickets 超過 20 張
400 欄位 {name} 錯誤 {reason} 其他欄位型別不符

Note

  • 單張票在檢核過程發生例外時，只有該張回 available = false、message = 票券系統異常，其餘票券的結果不受影響。
  • 查無該票券時同樣以 available = false、message = 查無票券資料 逐張回覆，不會讓整批請求失敗。
  • 兌換商品已停售或查不到時，該票回 available = false、message = 此商品未開放兌換。未帶 store_id 時不檢核這一項。
  • 未帶 store_id 時以總店檢核，限定門市才能核銷的票券因此可能得到與現場不符的結果；由門市裝置呼叫時請務必帶上。