價金保管-使用後核銷API技術文件

查詢作業 / 取得紙本票面資料

應用場景

  • 提供以特店訂單編號來取得紙本票券列印所需的資料，取得資料後再依綠界提供的票券版型套版並傳送至紙券列印機進行列印。

❗ 注意事項：

  • 此功能限已開通「廠商列印紙本票券」功能之特店使用，如欲開通請洽詢所屬業務。
  • 僅提供列印尚未使用的票券。
  • 建議使用頂尖票券列印機，並且設定紙張大小為9公分X 20.32公分

API介接網址

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

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]須擇一必填，且僅可填寫其中一項
  • 限英、數字

FreeTradeNo String(20)
贈品單號

❗ 注意事項：

  • 此欄位與[MerchantTradeNo]須擇一必填，且僅可填寫其中一項
  • 限英、數字

Operator String(10)
操作人員 必填

操作此筆取得紙本票面資料人員，僅為歷程紀錄使用

❗ 注意事項：

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

PageNum Int
回傳第幾頁資料結果

API固定每次回傳筆數為200筆，當資料超過200筆時，需分次查詢取得所有資料，此參數可指定回傳特定頁數的資料。
例如：當PageNum=2，表示回傳第2頁資料，回傳值將取得第201~400筆票券資料。

❗ 注意事項：

  • 首次查詢請固定帶入1，取得第1頁資料及總筆數[TotalCount]，依回傳結果[TotalCount]再決定後續需呼叫的次數。
  • 如未指定頁數，預設回傳第1頁。

Data參數範例(JSON格式)

				
					{
    "MerchantID": "2000132",
    "MerchantTradeNo": "CBX20220302153064851",
    "FreeTradeNo": "",
    "Operator": "LeoWang",
    "PageNum": 1
}

綠界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為成功，其餘為失敗

RtnMsg String(200)
回應訊息

MerchantID String(10)
特店編號

TotalCount Int
票券總張數

此筆訂單的票券總張數，特店可依此參數判斷需呼叫的次數。

  • 使用範例說明：
    當總張數 [TotalCount]=500時，特店需呼叫三次API以取得所有票券資訊 ，即 [PageNum]分別以1、2、3帶入，第一次呼叫取得第1頁1-200筆資料、第二次呼叫取得第2頁201-400筆、第三次呼叫取得第3頁401-500筆。

❗ 注意事項：

  • 若指定的頁數已超過總張數範圍，Response結果會直接回應查無資料。

TicketData Array[Object]
票券資料

JSON格式字串，資料內容為多筆票券明細

TicketNo String(16)
票券序號 

ItemName String(20)
商品名稱 

TicketType String(1)
票券類型 

  • 1：提貨券
  • 2：贈品券

TicketAmount String(9)
票券面額 

Instructions1 String(50)
使用說明1 

Instructions2 String(50)
使用說明2 

Instructions3 String(50)
使用說明3 

Instructions4 String(50)
使用說明4 

Instructions5 String(50)
使用說明5 

Instructions6 String(50)
使用說明6 

Instructions7 String(50)
使用說明7 

Instructions8 String(50)
使用說明8 

Instructions9 String(50)
使用說明9 

Instructions10 String(50)
使用說明10 

Instructions11 String(50)
使用說明11 

贈品券使用

ReturnPolicy String(34)
退貨權益 

提貨券使用

IssuingUnit String(47)
發行單位 

❗ 注意事項：

  • 因紙本票券版面限制，若特店設定的發行單位字串長度超過，將會自動擷取前47個字回傳。

PersonInCharge String(15)
負責人 

❗ 注意事項：

  • 因紙本票券版面限制，若特店設定的負責人字串長度超過，將會自動擷取前15個字回傳。

TaxIDNumber String(8)
統一編號 

CSHotline String(12)
客服電話 

Address String(49)
地址 

❗ 注意事項：

  • 因紙本票券版面限制，若特店設定的地址字串長度超過，將會自動擷取前49個字回傳。

EscrowAgent String(12)
履約保障機構

提貨券使用

EscrowDate String(21)
履約保障期間

提貨券使用，格式為：YYYY/MM/DD-YYYY/MM/DD

EffectiveDate String(21)
有效期間 

贈品券使用，格式為：YYYY/MM/DD-YYYY/MM/DD

TicketQRCode String(30)
票券QRCode 

QRCode URI內容為核銷頁短網址，需自行將此短網址轉為QRCode套印於紙本票券。

TicketBarcode String(18)
票券條碼 

條碼內容為核銷代碼，使用Code 128編碼規則產生

Data參數範例(JSON格式)

				
					{
    "RtnCode": 1,
    "RtnMsg": "成功",
    "MerchantID":"2000132",
    "TotalCount": 150,
    "TicketData":[
        {
            "TicketNo":"CB2SY20220302153",
            "ItemName":"五星級飯店SPA按摩券",
            "TicketType":"1",
            "TicketAmount":"999",
            "Instructions1":"使用說明1…",
            "Instructions2":"使用說明2…",
            "Instructions3":"使用說明3…",
            "Instructions4":"使用說明4…",
            "Instructions5":"使用說明5…",
            "Instructions6":"使用說明6…",
            "Instructions7":"使用說明7…",
            "Instructions8":"使用說明8…",
            "Instructions9":"使用說明9…",
            "Instructions10":"使用說明10…",
            "Instructions11":null,
            "ReturnPolicy":"退貨權益…",
            "IssuingUnit":"溫泉渡假酒店",
            "PersonInCharge":"野比哆啦",
            "TaxIDNumber":"12345678",
            "CSHotline":"0800000000",
            "Address":"台北市童話區幸福路168號",
            "EscrowAgent":"○○銀行信託",
            "EscrowDate":"2022/01/01-2022/12/31",
            "EffectiveDate":"",
            "TicketQRCode":"https://stage.ecticket.tw/6qUjyqgvar",
            "TicketBarcode":"AAAA12345678912345"
        },
        …
  ]
}

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

綠界官方網站