B2C電子發票API技術文件

發票查詢／查詢折讓明細

應用場景

可使用此API查詢已開立折讓之發票資訊，但不包含消費者尚未同意之線上折讓單

API介接網址

  • 測試環境：https://einvoice-stage.ecpay.com.tw/B2CInvoice/GetAllowanceList
  • 正式環境：https://einvoice.ecpay.com.tw/B2CInvoice/GetAllowanceList

HTTPS傳輸協定

  • Content Type ：application/json
  • HTTP Method ：POST

特店傳入參數(Json格式)

PlatformID String(10)
特約合作平台商代號

  • 這個參數是專為與綠界簽約的指定平台商所設計，只有在申請開通後才能使用。
  • 如果您是一般廠商，請在介接時將此參數欄位保留為空。
  • 對於平台商，在使用時需要在MerchantID(特店編號)欄位中填入與您已經完成綁定子廠商的MerchantID(特定編號)。
    請注意，只能使用已綁定的子廠商編號，以避免操作失敗。綁定作業請洽所屬業務。

MerchantID String(10)
特店編號 必填

  1. 測試環境合作特店編號
  2. 正式環境金鑰取得

RqHeader Object
傳入資料 必填

Timestamp Number
傳入時間 必填

請將傳輸時間轉換為時間戳(GMT+8)，綠界會利用此參數將當下的時間轉為Unix TimeStamp來驗證此次介接的時間區間。

❗ 注意事項：

  • 驗證時間區間暫訂為 10 分鐘內有效，若超過此驗證時間則此次訂單將無法建立，參考資料：http://www.epochconverter.com/。
  • 合作特店須進行主機「時間校正」，避免主機產生時差，導致API無法正常運作。

Data String
加密資料 必填

此為加密過JSON格式的資料。加密方法說明

特店傳入參數範例(Json格式)

				
					{
    "MerchantID": "2000132",
    "RqHeader": {
        "Timestamp": 1525168923
    },
    "Data": "加密資料"
}

Data參數說明(Json格式) : 請先將Json字串進行urlencode後再進行AES加密

MerchantID String(10)
特店編號 必填

SearchType String(1)
查詢方式 必填

0: 折讓編號 查詢
1: 發票號碼+發票開立日期 查詢
2: 發票號碼+發票折讓日期 查詢

AllowanceNo String(16)
折讓編號

  • 當查詢方式[SearchType]=0時，此參數必填
  • 其他值時，此參數無效

InvoiceNo String(10)
發票號碼

  • 當查詢方式[SearchType]=1或2時，此參數必填
  • 其他值時，此參數無效

Date String(10)
日期

1.當查詢方式[SearchType]=1時，請傳入發票開立日期
2.當查詢方式[SearchType]=2時，請傳入發票折讓日期
3.格式為「yyyy-MM-dd」或「yyyy/MM/dd」 

Data參數範例(Json格式)

				
					{
  "MerchantID": 2000132,
  "SearchType": "0",
  "AllowanceNo": "2019091719477262"
}

綠界回傳參數格式

  • Content Type ：application/json
  • HTTP Method ：POST

綠界回傳參數(Json格式)

PlatformID String(10)
特約合作平台商代號

MerchantID String(10)
特店編號 

RpHeader Object
回傳資料 

Timestamp Number
回傳時間

Unix timestamp(GMT+8)

TransCode Int
回傳代碼 

1 代表 API 傳輸資料(MerchantID, RqHeader, Data)接收成功，實際的 API 執行結果狀態請參考 RtnCode。

TransMsg String(200)
回傳訊息 

Data String
加密資料 

回傳相關資料，此為加密過JSON格式的資料。加密方法說明

綠界回傳參數範例

				
					{
    "MerchantID": "2000132",
    "RpHeader": {
        "Timestamp": 1525169058
    },
    "TransCode": 1,
    "TransMsg": "",
    "Data": "加密資料"
}

Data參數說明(Json格式) : 請先將Data進行AES解密後再做urldecode

RtnCode Int
回應代碼

1 代表 API 執行成功，其餘代碼均為失敗。

RtnMsg String(200)
回應訊息

AllowanceInfo Array
折讓資訊列表

Data參數範例

				
					{
  "RtnCode": 1,
  "RtnMsg": "成功",
  "AllowanceInfo": [
  {…},
  {…}
    ]
}

AllowanceInfo參數說明(Json格式)

ChannelPartner String(1)
通路商編號

1:蝦皮

IA_Allow_No String(16)
折讓單號

長度固定為16碼

IA_Check_Send_Mail String(1)
折讓通知

S：簡訊
E：電子郵件
A：皆通知時
N：皆不通知

IA_Date String(20)
折讓時間

格式為「yyyy-MM-dd HH:mm:ss」

Items Array[Object]
商品

ItemSeq Int
商品序號

ItemName String(100)
商品名稱

ItemCount Number
商品數量

ItemWord String(6)
商品單位

ItemPrice Number
商品單價

支援整數10位，小數7位

ItemRateAmt Number
商品營業稅額

支援整數11位

ItemTaxType String(1)
商品課稅別

1：應稅
2：零稅率
3：免稅

❗ 注意事項：

  • 預設為空字串，當課稅類別[TaxType] = 9時，此欄位不可為空。
  • 課稅類別為混合稅率時，需含二筆或以上的商品課稅別[ItemTaxType]，且至少需有一筆商品課稅別為應稅及至少需有一筆商品課稅別為免稅或零稅率，即混稅發票只能
    1.應稅+免稅
    2.應稅+零稅率，
    免稅和零稅率發票不能同時開立。

ItemAmount Number
商品合計

  • 此為含稅小計金額
  • 支援整數12位，小數7位

IA_AP String(20)
折讓IP

IA_Identifier String(10)
買受人統編

0000000000代表沒有統編

IA_Invalid_Status String(1)
折讓作廢狀態

1：折讓單已作廢
0：折讓單未作廢

IA_Invoice_Issue_Date String(20)
發票開立時間

格式為「yyyy-MM-dd HH:mm:ss」

IA_Invoice_No String(10)
發票號碼

長度固定為10碼

IA_Mer_ID String(10)
特店代號

IA_Send_Mail String(100)
通知的MAIL

送出通知時，所送的Email

IA_Send_Phone String(100)
通知的手機號碼

送出通知時，所送的手機號碼

IA_Tax_Amount Number
營業稅額合計

支援整數11位

IA_Tax_Type String(1)
課稅別

1：應稅
2：零稅率
3：免稅
4：應稅(特種稅率)

IA_Total_Amount Number
金額合計(不含稅之進貨額)

支援整數12位

IA_Total_Tax_Amount Number
金額合計(含稅)

支援整數12位

IA_Upload_Date String(20)
上傳時間

格式為「yyyy-MM-dd HH:mm:ss」

IA_Upload_Status String(1)
折讓上傳狀態

1：已上傳
0：未上傳

IIS_Customer_Name String(60)
買受人姓名

回傳AllowanceInfo參數範例

				
					{
    "ChannelPartner": "",
    "IA_Allow_No": "2019091719477262",
    "IA_Check_Send_Mail": "E",
    "IA_Date": "2019-09-17 19:47:19",
    "IA_IP": "0",
    "IA_Identifier": "0000000000",
    "IA_Invalid_Status": "1",
    "IA_Invoice_Issue_Date": "2019-09-17 19:47:05",
    "IA_Invoice_No": "UV11100016",
    "IA_Mer_ID": "2000132",
    "IA_Send_Mail": "test@ecpay.com.tw",
    "IA_Send_Phone": "0912345678",
    "IA_Tax_Amount": 2,
    "IA_Tax_Type": "1",
    "IA_Total_Amount": 48,
    "IA_Total_Tax_Amount": 50,
    "IA_Upload_Date": "",
    "IA_Upload_Status": "0",
    "IIS_Customer_Name": "綠界科技股份有限公司",
    "Items": [
        {
            "ItemSeq": 1,
            "ItemName": "item01",
            "ItemCount": 1,
            "ItemWord": "件",
            "ItemPrice": 50,
            "ItemTaxType": "1",
            "ItemRateAmt": 2,
            "ItemAmount": 50
        }
    ]
}

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

綠界官方網站