應用場景
特店於商品建立後，若需異動票券商品內容，可透過本 API 依商品編號（ProductNo）更新既有商品資料，包含商品圖片、商品名稱、商品面額、商品上下架狀態（ItemStatus），以及重新設定消費者使用票券前應知悉的使用須知（InstructionsList）。
API 介接網址
- 測試環境：https://ecticket-stage.ecpay.com.tw/api/Ticket/Updateproducts
- 正式環境：https://ecticket.ecpay.com.tw/api/Ticket/Updateproducts
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)
特店編號 必填
ProductNo String(8)
商品編號 必填
MerchantProductNo String(13)
廠商貨號
- 限1~13碼英數字
ItemStatus String(1)
商品狀態
- 0：已下架
- 1：上架中
TicketType String(1)
票券類型
- 1：提貨券
- 2：贈品券
ItemName String(20)
商品名稱
- 長度需為 4～20 個字
- 僅接受中文、半形英文字母及半形數字；英文單字間如需分隔，請使用底線（_），不接受空白字元
ItemAmount Int
商品面額
依票券類型（TicketType）不同，此參數須符合以下規範：
- 提貨券：須為大於 0 的整數，且最多 9 位數。
- 贈品券：固定傳入 0。
InstructionsList Array[Object]
使用說明列表
注意事項：
- 若有帶入 InstructionsList，則物件內的 IssueType 與 Description 皆為必填欄位。
- 如有帶入資料，會移除原本所有設定並新增此次設定。例如：原本設定 3 筆說明，此次修改僅帶 2 筆，則系統會將原本 3 筆說明移除後，再新增此次帶入的資料。
IssueType String(1)
發行類型 必填
- 2：紙本票券
- 3：電子票券
Description String(100)
使用說明內容 必填
- 依 IssueType 不同，有以下限制：
- IssueType = 2（紙本票券）：每項內容長度上限 50 字元，最多 10 項，至少需傳入 1 項。
- IssueType = 3（電子票券）：每項內容長度上限 100 字元，最多 6 項，至少需傳入 1 項。
- 共同限制：內容不得包含全形英文字母及全形數字。
Data加密前資料範例(JSON格式)
{
"MerchantID":"2000132",
"ProductNo":"20240001",
"MerchantProductNo":"A123456789012",
"ItemStatus":"1",
"TicketType":"1",
"ItemName":"商品名稱",
"ItemAmount":100,
"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)
回應訊息
Data加密前資料範例(JSON格式)
{
"RtnCode":1,
"RtnMsg":"成功"
}
注意事項：
- 限制說明：商品建立後，如已產生發行紀錄，以下欄位將不可再進行修改：
- 廠商貨號 [MerchantProductNo]
- 商品狀態 [ItemStatus]
- 票券類型 [TicketType]
- 商品名稱 [ItemName]
- 商品面額 [ItemAmount]
- 商品圖片 [ProductImg]
- 使用說明 [InstructionsList]
- 修改 API 時，若欄位無需更新，請勿帶入該參數或傳入 null（若 API 支援）。系統僅更新有帶入且符合格式規範的參數；即使帶入的值為空字串 (“”) 或其他合法值，系統仍會視為更新指示，並以該值覆寫原有資料。請確認欲更新的欄位後再傳送參數。