查詢作業 / 查詢訂單資訊

應用場景

特店可使用廠商訂單編號或贈品單號，呼叫此API查詢訂單明細資料

API介接網址

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

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": "",
    "MerchantID": "2000132",
    "RqHeader": {
        "Timestamp": 1525168923
    },
    "Data": "…",
    "CheckMacValue": "…"
}

Data參數說明(JSON格式)

注意事項：請在加密前對參數值進行 URLEncode

MerchantID String(10)
特店編號 必填

MerchantTradeNo String(25)
特店訂單編號

注意事項：

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

FreeTradeNo String(20)
贈品單號

注意事項：

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

PageNum Int
回傳第幾頁資料結果

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

注意事項：

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

Data參數範例(JSON格式)

				
					{
    "MerchantID": "2000132",
    "MerchantTradeNo":"CBX20220302153064851",
    "FreeTradeNo": "",
    "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": "",
    "MerchantID": "2000132",
    "RpHeader": {
        "Timestamp": 1525169058
    },
    "TransCode": 1,
    "TransMsg": "",
    "Data": "…",
    "CheckMacValue": "…"  
}

Data參數說明(JSON格式)

RtnCode Int
回應代碼

1為成功，其餘為失敗

RtnMsg String(200)
回應訊息

MerchantID String(10)
特店編號

MerchantTradeNo String(25)
特店訂單編號

FreeTradeNo String(20)
贈品單號

TicketTradeNo String(16)
ECT訂單編號

由ECTicket系統提供的訂單編號

PaymentProvider String(1)
金流服務商

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

1：綠界金流

PaymentType String(1)
付款方式

此筆訂單交易的付款方式

1：信用卡

CreditTradeID Int
信用卡授權單號

Status Int
發行結果

1：發行成功
2：發行失敗
3：發行作業處理中

Remark String(100)
發行結果備註

當Status=2(發行失敗)時，會在此欄位說明發行失敗原因

IssueDate String(20)
發行日期

格式為：yyyy/mm/dd hh:mm:ss

IssueType String(1)
出券類型

1：超商票券
2：紙本票券
3：電子票券
4：純序號

PrintType String(1)
列印方式

紙本票券的列印方式

1：綠界列印
2：廠商列印
空字串代表非紙本票券

CustomerName String(20)
購買人姓名

CustomerPhone String(10)
購買人手機

CustomerEmail String(80)
購買人Email

EscrowExpiredDate String(8)
履約保障到期日

格式為：yyyymmdd

TotalCount Int
訂單序號總筆數

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

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

注意事項：

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

TradeAmount Int
訂單金額

RedeemCount Int
已核銷序號數量

RedeemAmount Int
已核銷總金額

RefundCount Int
已退貨序號數量

RefundAmount Int
已退貨總金額

TotalRefundFee Int
退貨手續費總金額

退款金額中已向消費者收取的退貨手續費總計

UnUsedCount Int
未使用序號數量

UnUsedAmount Int
未使用總金額

ExpiredCount Int
已失效票券數量

TicketList Array[Object]
票券序號清單

Data參數範例(JSON格式)

				
					{
    "RtnCode": 1,
    "RtnMsg": "成功"
    "MerchantID": "2000132",
    "MerchantTradeNo":"CBX20230302153064851",
    "FreeTradeNo":"",
    "TicketTradeNo":"2023061012345678",
    "CreditTradeID":12456789,
    "Status":1,
    "Remark":"",
    "IssueDate":"2023/06/10 10:35:21",
    "IssueType":"3",
    "PrintType":"",
    "CustomerName":"",
    "CustomerPhone":"",
    "CustomerEmail":"ABC123@gmail.com",
    "EscrowExpiredDate":"20231210",
    "TotalCount":500,
    "TradeAmount":9000,
    "RedeemCount":1,
    "RedeemAmount":3000,
    "RefundCount":2,
    "RefundAmount":600,
    "TotalRefundFee":80,
    "UnUsedCount":0,
    "UnUsedAmount":0,
    "ExpiredCount":0,
    "TicketList":[…]
}

TicketList參數說明(JSON格式)

TicketNo String(16)
票券序號

UseStatus Int
序號使用狀態

1：未使用，代表票券發行後尚未使用
2：已核銷，票券核銷使用後狀態即為已核銷
3：已退貨，票券執行退貨後狀態即為已退貨
4：已失效，代表贈品券已到期

ItemNo String(8)
商品編號

當[IssueType] 不等於4 (非純序號)時才會回傳。

ItemName String(20)
商品名稱

TicketType String(1)
票券類型

1：提貨券
2：贈品券

TicketAmount Int
票券面額

StartDate String(8)
票券生效日

票券生效日即票券可開始使用日期，格式為：yyyymmdd

WriteOffDate String(8)
核銷日期

票券執行核銷的時間，格式為：yyyymmdd hh:mm

RefundDate String(8)
退貨日期

票券執行退貨的時間，格式為：yyyymmdd hh:mm

ExpiredDate String(8)
贈品券到期日

格式為：yyyymmdd

WriteOffNo String(18)
核銷代碼

當[IssueType] =4 (純序號)時才會回傳。

TicketList參數範例(JSON格式)

				
					[
    {
        "TicketNo": "CX12345600001",
        "UseStatus": 2,
        "ItemNo": "T00358",
        "ItemName": "平日住宿券",
        "TicketType": "1",
        "TicketAmount": 1200,
        "StartDate": "20230501",
        "WriteOffDate": "20230601",
        "RefundDate": "",
        "ExpiredDate": "",
        "WriteOffNo": ""
    },
    {
        "TicketNo": "CX12345600002",
        "UseStatus": 2,
        "ItemNo": "T00358",
        "ItemName": "平日住宿券",
        "TicketType": "1",
        "TicketAmount": 1200,
        "StartDate": "20230501",
        "WriteOffDate": "20230622",
        "RefundDate": "",
        "ExpiredDate": "",
        "WriteOffNo": ""
    },
    {
        "TicketNo": "CX12345600003",
        "UseStatus": 1,
        "ItemNo": "T00358",
        "ItemName":"平日住宿券",
        "TicketType":"1",        
        "TicketAmount": 1200,
        "StartDate":"20230501",
        "WriteOffDate":"",
        "RefundDate":"",
        "ExpiredDate":"",
        "WriteOffNo":""
    },
    {
        "TicketNo": "CX12345600004",
        "UseStatus": 1,
        "ItemNo": "T00358",
        "ItemName": "平日住宿券",
        "TicketType": "1",
        "TicketAmount": 1200,
        "StartDate": "20230501",
        "WriteOffDate": "",
        "RefundDate": "",
        "ExpiredDate": "",
        "WriteOffNo": ""
    }
]

綠界官方網站