票券作業 / 票券發行

應用場景

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

注意事項：

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

API介接網址

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

HTTPS傳輸協定

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

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

PlatformID String(10)
平台商編號

平台商在綠界的會員編號[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)
特店編號 必填

PaymentProvider String(1)
金流服務商 必填

此筆訂單交易使用的金流服務商

1：綠界金流
2：其他(非綠界交易或純贈品券)

注意事項：

請確實填寫正確的金流服務廠商，以避免撥款發生異常。
當金流服務商為綠界時，系統會檢核訂單金額與發行的商品總面額必須一致。

PaymentType String(1)
付款方式

此筆訂單交易的付款方式

1：信用卡
2：非信用卡

注意事項：

當[PaymentProvider]=1 (綠界金流)時，系統會自動撈取訂單實際付款方式寫入。
當[PaymentProvider]=2 (其他)且訂單商品包含提貨券時，此欄位為必填；若否則此欄位忽略不需填寫。

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(電子票券)時，此欄位為必填
其他出券類型不需填寫此欄位，系統固定設定為即期。

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",
    "PaymentProvider": "2",
    "PaymentType": "2",
    "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",
    "PaymentProvider": "2",
    "PaymentType": "2",
    "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",
    "PaymentProvider": "1",
    "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",
    "PaymentProvider": "2",
    "PaymentType": "2",
    "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)
平台商編號

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
        }  
    ]
}

綠界官方網站