應用場景
特店於電子票券服務中，可透過本 API 建立新的票券商品，設定商品名稱、商品面額等基本資訊，並可同時指定該商品可於哪些門市（特店）進行核銷（AuthorizeList），以及設定消費者於使用票券前應知悉的使用須知或注意事項（InstructionsList）。此設計適用於連鎖品牌總部統一建立票券商品、再授權旗下多間分店核銷的情境，亦可依商品類型附加不同的使用說明內容，滿足多店點、多商品類型的票券發行與管理需求。
API 介接網址
- 測試環境：https://ecticket-stage.ecpay.com.tw/api/Ticket/Addproducts
- 正式環境：https://ecticket.ecpay.com.tw/api/Ticket/Addproducts
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無法正常運作。
ProductImg String
商品圖片
- 商品圖片的 Base64 編碼字串，請先將商品圖片轉換為 Base64 格式後傳入
- 格式：JPEG／JPG／PNG，大小 ≤ 5MB，建議尺寸 800×800px
Data Object
加密資料 必填
CheckMacValue String
驗證碼 必填
請參考附錄檢查碼機制進行計算
特店Request參數範例(JSON格式)
{
"PlatformID": "3002599",
"MerchantID": "2000132",
"RqHeader": {
"Timestamp": 1525168923
},
"ProductImg":"Base64字串",
"Data": "…",
"CheckMacValue": "…"
}
Data參數說明(Json格式)
注意事項：請在加密前對參數值進行 URLEncode
MerchantID String(10)
特店編號 必填
MerchantProductNo String(13)
廠商貨號 必填
- 限1~13碼英數字
TicketType String(1)
票券類型 必填
- 1：提貨券
- 2：贈品券
ItemName String(20)
商品名稱 必填
- 長度需為 4～20 個字
- 僅接受中文、半形英文字母及半形數字；英文單字間如需分隔，請使用底線（_），不接受空白字元
ItemAmount Int
商品面額 必填
依票券類型（TicketType）不同，此參數須符合以下規範：
- 提貨券：須為大於 0 的整數，且最多 9 位數。
- 贈品券：固定傳入 0。
AuthorizeList Array[Object]
權限設定列表
注意事項：
- 權限設定列表為可選參數，若不帶入，則商品將無任何核銷／退貨權限設定，僅能由商品建立者核銷／退貨。
- 若有帶入 AuthorizeList，則物件內的 Type 與 StoreIDs 皆為必填欄位。
Type String(1)
權限類型 必填
- 1：跨店核銷權限
- 2：分店核銷權限
- 3：分店退貨權限
StoreIDs Array[String]
特店編號列表 必填
依 Type 傳入對應的編號：
- Type = 1（可跨店核銷）：請傳入會員編號（MID）
- Type = 2（可核銷分店）：請傳入分店編號
- Type = 3（可退貨分店）：請傳入分店編號
InstructionsList Array[Object]
使用說明列表 必填
IssueType String(1)
發行類型 必填
- 2：紙本票券
- 3：電子票券
Description String(100)
使用說明內容 必填
- 依 IssueType 不同，有以下限制：
- IssueType = 2（紙本票券）：每項內容長度上限 50 字元，最多 10 項，至少需傳入 1 項。
- IssueType = 3（電子票券）：每項內容長度上限 100 字元，最多 6 項，至少需傳入 1 項。
- 共同限制：內容不得包含全形英文字母及全形數字。
Data加密前資料範例(JSON格式)
{
"MerchantID":"2000132",
"MerchantProductNo": "A123456789012",
"TicketType":"1",
"ItemName":"商品名稱",
"ItemAmount":100,
"AuthorizeList":[
{"Type":"1","StoreIDs":[2000132,2000133]},
{"Type":"2","StoreIDs":[1234567,1234568]},
{"Type":"3","StoreIDs":[1234567]}
],
"InstructionsList":[
{"IssueType":"2","Description":"請於有效期限內使用"},
{"IssueType":"2","Description":"此票券僅限於指定門市使用"}
]
}
特店Response參數說明(JSON格式)
PlatformID String(10)
平台商編號
平台商在綠界的會員編號 [MerchantID]
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)
回應訊息
ProductNo String(8)
商品編號
MerchantProductNo String(13)
廠商貨號
Data加密前資料範例(JSON格式)
{
"RtnCode":1,
"RtnMsg":"成功",
"ProductNo":"20240001",
"MerchantProductNo":"A123456789012"
}
注意事項：
- 商品新增成功後，狀態預設為「上架」，可透過「修改商品資訊」API 調整上架／下架狀態。
- 新增成功後回傳
ProductNo，後續修改商品、查詢商品狀態皆以此為識別。