應用場景
提供可使用此API執行票券核銷或取消核銷作業
API介接網址
- 測試環境:https://ecticket-stage.ecpay.com.tw/api/Ticket/WriteOff
- 正式環境:https://ecticket.ecpay.com.tw/api/Ticket/WriteOff
HTTPS傳輸協定
- Accept:text/html
- Content Type:application/json
- HTTP Method:POST
特店Request參數說明 (JSON格式)
PlatformID String(10)
平台商編號
平台商在綠界的會員編號[MerchantID]
MerchantID String(10)
特店編號 必填
RqHeader Object
傳輸資料 必填
Timestamp Number
傳入時間 必填
注意事項:
- 驗證時間區間暫訂為10分鐘內有效,若超過此驗證時間則此次訂單將無法建立,參考資料:http://www.epochconverter.com/。
- 合作特店須進行主機「時間校正」,避免主機產生時差,延伸API無法正常運作。
Data String
加密資料 必填
回傳相關資料,此為加密過JSON格式的資料。加密方法說明
CheckMacValue String
檢查碼 必填
請參考附錄檢查碼機制進行計算
特店Request參數範例 (JSON格式)
{
"PlatformID": "3002599",
"MerchantID": "2000132",
"RqHeader": {
"Timestamp": 1525168923
},
"Data": "…",
"CheckMacValue": "…"
}
Data參數說明(JSON格式)
注意事項:請在加密前對參數值進行 URLEncode
MerchantID String(10)
特店編號 必填
WriteOffNo String(18)
核銷代碼 必填
每張票券會有一組專屬核銷代碼,掃描消費者出示的票券Barcode取得
Action String(1)
執行動作 必填
- 1:核銷
- 2:取消核銷
注意事項:
- 贈品券不可取消核銷
CancelReason String(50)
取消核銷原因
執行動作為取消核銷時(Action=2),可帶入取消核銷原因
StoreID String(20)
分店編號
執行此筆票券核銷/取消核銷的分店。當有傳入此參數時,系統會檢核分店是否存在且狀態為啟用中,並判斷是否具備核銷/取消核銷權限,如不需權限控管請勿填寫。
注意事項:
- 請先於綠界廠商後台建立分店資料,再傳入此分店編號。
※如何建立分店資料?請參考:ECTicket發行管理平台操作手冊 - 限英、數字,且不可使用全形
- 長度限制為 2~20 個字
- 當欄位為空值時,代表此筆為總店發行。
Operator String(10)
建立人員 必填
操作此筆票券核銷/取消核銷人員,僅為歷程紀錄使用
注意事項:
- 限英、數字,且不可使用全形
Data參數範例(JSON格式)
{
"MerchantID": "2000132",
"WriteOffNo":"LEU4loiSZ9TDTWAtxL",
"Action":"1",
"CancelReason":"",
"StoreID":"TP30116",
"Operator":"LeoWang"
}
綠界Response參數說明 (JSON格式)
PlatformID String(10)
平台商編號
MerchantID String(10)
特店編號
RpHeader Object
回傳資料
Timestamp Number
回傳時間
時間戳 Unix timestamp
TransCode Int
回傳代碼
1 代表 API 傳輸資料 (PlatformID, MerchantID, RqHeader, Data) 接收成功,實際的API執行結果狀態請參考 RtnCode 參數
TransMsg String(200)
回傳訊息
Data String
加密資料
此參數為加密過的 JSON 格式資料。加密方法說明
CheckMacValue String
檢查碼
請參考附錄檢查碼機制進行計算
綠界Response參數範例 (JSON格式)
{
"PlatformID": "3002599",
"MerchantID": "2000132",
"RpHeader": {
"Timestamp": 1525169058
},
"TransCode": 1,
"TransMsg": "",
"Data": "…",
"CheckMacValue": "…"
}
Data參數說明(JSON格式)
RtnCode Int
回應代碼
1為成功,其餘為失敗
RtnMsg String(200)
回應訊息
Data參數範例(JSON格式)
{
"RtnCode": 1,
"RtnMsg": "成功"
}
注意事項:
- 如欲取消核銷,須於核銷當日23:59前執行,系統將於核銷隔日00:00進行票務更新作業。