票券作業 / 票券發行

應用場景

  • 情境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
        }  
    ]
}

				
			

Copyright © Green World FinTech Service Co., Ltd. All rights reserved.

綠界官方網站