票券作業 / 票券發行

應用場景

情境1：發行紙本、電子、或超商票券
- Step 1：在使用票券發行之前，必須先請特店在【廠商後台→切換到ECTicket專區→使用後核銷→商品管理】完成新增商品上架並取得商品編號。
- Step 2：串接綠界金流完成訂單付款，再以金流訂單對應的特店訂單編號進行票券發行。
情境2：發行純序號票券
- 此情境在票券發行完成後僅會取得一組序號，消費者不會取得任何形式的票券。
- 不需先上架商品，可直接指定商品名稱、商品面額進行票券發行。
- 若使用綠界金流服務，請先串接綠界金流完成訂單付款，再以金流訂單對應的特店訂單編號進行票券發行。

注意事項：

紙本票券於「票券發行API」呼叫當下就會立即執行發行
電子票券、超商票券與純序號則僅為接收票券發行資料，後續再以排程方式處理發行的作業，排程預計會在5分鐘內完成。
API Response回應的參數RtnCode都僅代表發行資料接收結果，請再呼叫「查詢票券發行結果API」確認是否發行成功。

API介接網址

測試環境：https://ecticket-stage.ecpay.com.tw/api/Ticket/Issue
正式環境：https://ecticket.ecpay.com.tw/api/Ticket/Issue

HTTPS傳輸協定

Accept：text/html
Content Type：application/json
HTTP Method：POST

特店Request參數說明 (JSON格式)

PlatformID String(10)
平台商或POS商編號

平台商或POS商在綠界的會員編號[MerchantID]

MerchantID String(10)
特店編號 必填

RqHeader Object
傳輸資料 必填

Timestamp Number
傳入時間 必填

請將傳輸時間轉換為時間戳(GMT+8)，綠界會利用此參數將當下的時間轉為Unix TimeStamp來驗證此次介接的時間區間。

注意事項：

驗證時間區間暫訂為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)
特店編號 必填

MerchantTradeNo String(25)
特店訂單編號

注意事項：

若訂單商品包含提貨券時，此欄位為必填；若否則此欄位必須為空不可填寫。
特店訂單編號應為唯一值，不可重覆
限英、數字

FreeTradeNo String(20)
贈品單號

注意事項：

若訂單商品皆為贈品券時，此欄位為必填；若否則此欄位必須為空不可填寫。
贈品單號應為唯一值，不可重覆
限英、數字

IssueType String(1)
出券類型 必填

1：超商票券
2：紙本票券
3：電子票券
4：純序號

PrintType String(1)
列印方式

1：綠界列印
2：廠商列印

注意事項：

當[IssueType]=2(紙本票券)時，此欄位為必填

IsImmediate String(1)
是否即期使用

1：即期，不須設定電子票券生效日[StartDate]，票券發行當下消費者可立即使用。
2：非即期，須設定電子票券生效日[StartDate]，生效日最早可設定發行日隔一天，常用於預售票情境。

注意事項：

當[IssueType]=3(電子票券)時，此欄位為必填
其他出券類型不需填寫此欄位，系統固定設定為即期。

RefundNotifyURL String(200)
退款結果主動通知URL

當提貨券訂單發生退款時，ECTicket Server將主動以Server POST方式通知退款金額等相關資訊。

注意事項：

URL Domain需事先與綠界申請開通防火牆
若需收到退款通知且訂單包含提貨券時，請填寫此參數才可收到通知。

UseStatusNotifyURL String(200)
核退主動通知URL

當訂單完成核銷或退貨時，ECTicket Server將主動以Server POST方式通知票券狀態異動資訊。

注意事項：

URL Domain需事先與綠界申請開通防火牆
若需收到退款通知且訂單包含提貨券時，請填寫此參數才可收到通知。

StoreID String(20)
分店編號

執行此筆票券發行的分店。當有傳入此參數時，系統會檢核分店是否存在且狀態為啟用中。

注意事項：

請先於綠界廠商後台建立分店資料，再傳入此分店編號。
※如何建立分店資料？請參考：ECTicket發行管理平台操作手冊
限英、數字，且不可使用全形
長度限制為 2~20 個字
當欄位為空值時，代表此筆為總店發行。

Operator String(10)
建立人員 必填

建立此筆票券發行人員，僅為歷程紀錄使用

注意事項：

限英、數字，且不可使用全形

CustomerName String(20)
購買人姓名

注意事項：

當[IssueType]=3(電子票券)時，此欄位為必填
當[IssueType]=2(紙本票券)時，若特店有寄送紙本票券給購買人的需求時，此欄位請務必填寫。
限純中文或純英文，中英文不可混用。
當欄位有填寫資料時，至少需帶入2個字元以上

CustomerPhone String(10)
購買人手機

注意事項：

當[IssueType]=3(電子票券)時，此欄位為必填
限數字、須為09開頭
僅接受國內手機號碼

CustomerEmail String(80)
購買人電子郵件信箱

注意事項：

當[IssueType]=1(超商票券)或3(電子票券)時，此欄位為必填

CustomerAddress String(100)
購買人地址

注意事項：

當[IssueType]=2(紙本票券)時，若特店有寄送紙本票券給購買人的需求，請填寫此欄位。

TicketInfo Array[Object]
票券資料

此為JSON格式字串，包含多筆的票券資料

ItemNo String(8)
商品編號 必填

注意事項：

當[IssueType] 不等於4 (非純序號)時，此欄位為必填。
限英、數字
單筆訂單，商品編號不可重複

ItemName String(20)
商品名稱

注意事項：

當[IssueType]=4(純序號)時，此欄位為必填
長度限制4-20個字
限半形中、英、數字，以及特殊符號()_/，。$%-

TicketPrice Int
商品面額

注意事項：

當[IssueType]=4(純序號)時，此欄位為必填
面額限制0~999,999,999元

TicketAmount Int
票券發行張數 必填

注意事項：

當[IssueType]=1(超商票券)時，單筆訂單加總限制最多發行8張
當[IssueType] 非「超商票券」時，單筆訂單加總限制最多發行100張

StartDate String(8)
票券生效日

票券生效日即票券可開始使用日期，格式為：yyyymmdd

注意事項：

當[IsImmediate]=1 (即期)時，此欄位固定為票券發行當天的日期
[IsImmediate]=2 (非即期)時，此欄位為必填，須大於票券發行當天的日期

ExpireDate String(8)
贈品券到期日期

格式為：yyyymmdd

注意事項：

當商品為贈品券時，此欄位才需填寫且為必填
日期不可小於票券生效日[StartDate]

Data參數範例(JSON格式)

Copy

{
    "MerchantID": "2000132",
    "MerchantTradeNo": "CBX20220302153064851",
    "IssueType": "1",
    "UseStatusNotifyURL": "http://www.happybuy123.com.tw/notifyurl",
    "Operator": "AngelaChan",
    "CustomerEmail": "abc@gmail.com",
    "TicketInfo": [
         {
            "ItemNo": "VQT04959",  
            "TicketAmount": 4           
         },
         {
            "ItemNo": "VNS21400",  
            "TicketAmount": 4           
         }
    ]
}

Copy

{
    "MerchantID": "2000132",
    "MerchantTradeNo": "CBX20220302153064851",
    "IssueType": "2",
    "PrintType": "2",
    "UseStatusNotifyURL": "http://www.happybuy123.com.tw/notifyurl",
    "Operator": "AngelaChan",
    "CustomerName": "王珊珊",
    "TicketInfo": [
         {
            "ItemNo": "VQT04959",  
            "TicketAmount": 10           
         },
         {
            "ItemNo": "VNS21400",  
            "TicketAmount": 10           
         }
    ]
}

Copy

{
    "MerchantID": "2000132",
    "MerchantTradeNo": "CBX20220302153064851",
    "IssueType": "3",
    "IsImmediate": "2",
    "Operator": "AngelaChan",
    "CustomerName": "王珊珊",
    "CustomerPhone": "0912345678",
    "CustomerEmail": "abc@gmail.com",
    "TicketInfo": [
         {
            "ItemNo": "VQT04959",  
            "TicketAmount": 8,
            "StartDate": "20240101"           
         },
         {
            "ItemNo": "VNS21400",  
            "TicketAmount": 6,
            "StartDate": "20240101"           
         }
    ]
}

Copy

{
    "MerchantID": "2000132",
    "MerchantTradeNo": "CBX20220302153064851",
    "IssueType": "4",
    "UseStatusNotifyURL": "http://www.happybuy123.com.tw/notifyurl",
    "Operator": "AngelaChan",    
    "TicketInfo": [
         {
            "ItemName": "五星渡假飯店假日住宿券",  
            "TicketPrice": 6600,
            "TicketAmount": 2           
         },
         {
            "ItemName": "SPA課程體驗券",  
            "TicketPrice": 3200,
            "TicketAmount": 4           
         }
    ]
}

綠界Response參數說明 (JSON格式)

PlatformID String(10)
平台商或POS商編號

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為票券發行資料接收成功，其餘為失敗

注意事項：

此回應代碼僅代表資料接收結果，後續會再以排程處理票券發行作業，實際票券發行結果請呼叫[查詢票券發行結果API]確認。

RtnMsg String(200)
回應訊息

MerchantTradeNo String(25)
特店訂單編號

FreeTradeNo String(20)
贈品單號

TicketTradeNo String(16)
票券訂單編號

TicketData Array[Object]
票券資料

此為JSON格式字串，包含多筆的票券資料

ItemNo String(8)
商品編號

當[IssueType] 不等於4 (非純序號)時才會回傳。

TicketAmount Int
票券發行張數

ItemName String(20)
商品名稱

當[IssueType]=4(純序號)時才會回傳。

TicketPrice Int
商品面額

當[IssueType]=4(純序號)時才會回傳。

Data參數範例(JSON格式)

				
					{
    "RtnCode": 1,
    "RtnMsg": "發送完成",
    "MerchantTradeNo":"CBX20220302153064851",
    "FreeTradeNo": "",
    "TicketTradeNo":"2022030215301234",
    "TicketData":[
        {
            "ItemNo":"BR103218",
            "TicketAmount":3
        },
        {
            "ItemNo":"CK851236",
            "TicketAmount":5
        }  
    ]
}

綠界官方網站