B2C電子發票API技術文件

查詢特定多筆發票

應用場景

特店可使用此API查詢各種類別多筆發票資訊，綠界提供Json/CSV格式回傳。

應用流程

此API採用分頁顯示的回傳機制，查詢結果會依照開立發票的時間由新到舊(e.g: 2022/10/12, 2022/10/01, 2022/09/01, 2022/07/06…)進行排序，以下說明API呼叫步驟程序：

Step1. 執行第一次API呼叫，設定每頁回傳筆數-[NumPerPage]及設定顯示的頁數-[ShowingPage，固定帶1]，即取得綠界回應的資料總筆數-[TotalCount]。

Step2. 根據Step1取得的資料總筆數-[TotalCount]，以及所需的分頁筆數來決定API的查詢次數

例如：當TotalCount=300，分頁需求為每頁100筆，則需呼叫3次取回所有資料(如下表所示)

API 呼叫 [ShowingPage] 參數值 [NumPerPage] 參數值
第一次
1
100
第二次
2
100
第三次
3
100

API介接網址

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

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)
特店編號 必填

BeginDate String(10)
查詢起始日期 必填

  • 要查詢的發票開立開始日期
  • 格式為「yyyy-MM-dd」or「yyyy/MM/dd」

EndDate String(10)
查詢結束日期 必填

  • 要查詢的發票開立結束日期
  • 格式為「yyyy-MM-dd」or「yyyy/MM/dd」

NumPerPage Int
單頁顯示筆數 必填

❗ 注意事項：單頁上限為200筆。為了保證系統效能和響應速度，建議每頁的顯示筆數不要超過30筆。

ShowingPage Int
顯示的頁數 必填

❗ 注意事項：查詢結果資料，會根據第一次開立發票的時間，按時間序較新排列至較舊的

DataType Int
回傳資料類型

1：Json(預設)
2：CSV

ChannelPartner String(1)
通路商編號

1:蝦皮
其餘數值忽略無效

Query_Award String(1)
中獎

0：全部(預設)
1：是
2：否

Query_Invalid String(1)
作廢

0：全部(預設)
1：是
2：否

Query_Print String(1)
索取紙本

0：全部(預設)
1：要
2：不要
3：已處理

Query_Upload String(1)
上傳狀態

0：全部(預設)
1：已上傳
2：未上傳
3：上傳失效

Query_Identifier String(1)
發票開立統編

0：全部(預設)
1：是
2：否

Query_TaxType String(1) 
課稅別

0：全部(預設)
1：應稅
2：零稅
3：免稅
4：特種稅率
9：混合稅率

Query_Category String(1) 
發票類別

0：全部(預設)
1：B2C
2：POS
3：離線

Query_Customer_Name String(60)
買受人姓名

Query_Customer_Phone String(20)
買受人手機號碼

Data參數範例(Json格式)

				
					{
   "MerchantID": "2000132",
   "BeginDate": "2018-10-28",
   "EndDate": "2018-11-10",
   "NumPerPage": "200",
   "ShowingPage": "2",
   "DataType": "1"
}

綠界回傳參數格式

  • 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)
回應訊息

TotalCount Number
總筆數

ShowingPage Int
顯示的頁數

InvoiceData Array[Object]
發票資料

IIS_Number String(10)
發票號碼

IIS_Relate_Number String(30)
特店自訂編號

ChannelPartner String(1)
通路商編號

1:蝦皮

IIS_Identifier String(10)
買方統編

0000000000代表沒有統編

IIS_Clearance_Mark String(1)
通關方式

❗ 注意事項：

只有零稅率才會回傳以下資料
1：非經海關出口
2：經海關出口

IIS_Category String(10)
發票類別

B2B：表示開立發票時有含統編
B2C：表示開立發票時沒有含統編

IIS_Tax_Type String(1)
課稅別

1：應稅
2：零稅率
3：免稅
4：應稅(特種稅率)
9：若為混合應稅與免稅或零稅率

IIS_Tax_Rate Number
稅率

小數點2位

IIS_Tax_Amount Number
稅金

  • 當發票有統編時，才會回傳稅金
  • 當發票沒有統編時，稅金包含在發票金額內，不拆算稅金，故回傳值為0
  • 支援整數11位

IIS_Sales_Amount Number
發票金額

支援整數12位

IIS_Create_Date String(20)
發票開立時間

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

IIS_Issue_Status String(1)
發票開立狀態

1：發票開立
0：發票註銷

IIS_Invalid_Status String(1)
發票作廢狀態

1：已作廢時
0：未作廢

IIS_Upload_Status String(1)
發票上傳狀態

1：已上傳
0：未上傳

IIS_Upload_Date String(20)
發票上傳時間

格式為「yyyy-MM-dd」或 「yyyy/MM/dd 」

IIS_Turnkey_Status String(1)
發票上傳後接收狀態

C：成功
E：失敗
G：處理中(待財政部回覆狀態)
P：處理中(上傳財政部中)

IIS_Remain_Allowance_Amt Number
折讓剩餘金額

支援整數12位

IIS_Print_Flag String(1)
列印旗標

1：列印
0：不列印

IIS_Award_Flag String(1)
中獎旗標

  • 空值：未對獎、不可對獎（如：捐贈之發票）
    0：未中獎
    1：已中獎
    X：有統編之發票

IIS_Award_Type String(2)
中獎種類

12：雲端發票獎800元
11：雲端發票獎500元
10：雲端發票獎100萬元
9：雲端發票獎2000元
8：特別獎 一千萬　
7：特獎 二百萬元
1：頭獎 二十萬元
2：二獎 四萬元
3：三獎 一萬元
4：四獎 四千元
5：五獎 一千元
6：六獎 二百元
0：未中獎

IIS_Carrier_Type String(1)
載具類別

空值：無載具
1：為綠界電子發票載具
2：為消費者自然人憑證
3：為消費者手機條碼

IIS_Carrier_Num String(64)
載具編號

  • 空值：無載具
    綠界電子發票載具時，為客戶電子信箱或客戶手機號碼擇一(以客戶電子信箱優先)，請注意，綠界會重新編碼後產出綠界載具編號。
  • 消費者使用載具為自然人憑證，格式應為2碼大寫英文字母加上14碼數字(長度共16碼)
  • 消費者使用載具為手機條碼時，目前總長度共為8碼，格式應為第1碼「/」加上由7碼數字及大寫英文字母及+-符號所組成。

IIS_Love_Code String(7)
捐款單位捐贈碼

財政部 – 查詢受捐贈機關或團體捐贈碼

https://www.einvoice.nat.gov.tw/APMEMBERVAN/XcaOrgPreserveCodeQuery/XcaOrgPreserveCodeQuery

Data參數範例

				
					{
  "RtnCode": 1,
  "RtnMsg": "查詢成功",
  "TotalCount": 10000,
  "ShowingPage": 2,
  "InvoiceData": [
         {
          "IIS_Number": "UV11100012",
          "IIS_Relate_Number": "20181028000000020",
          "ChannelPartner": "",
          "IIS_Identifier": "0000000000",
    	  "IIS_Clearance_Mark": "",
    	  "IIS_Category": "B2C",
    	  "IIS_Tax_Type": "1",
    	  "IIS_Tax_Rate":0.05,
    	  "IIS_Tax_Amount": 0,
    	  "IIS_Sales_Amount": 100,
    	  "IIS_Create_Date": "2019-09-17 17:17:31",
    	  "IIS_Issue_Status": "1",
    	  "IIS_Invalid_Status": "0",
    	  "IIS_Upload_Status": "0",
    	  "IIS_Upload_Date": "",
    	  "IIS_Turnkey_Status": "",
    	  "IIS_Remain_Allowance_Amt": 0,
          "IIS_Award_Flag": "",
          "IIS_Award_Type": "11",
          "IIS_ Print_Flag ": "1",
          "IIS_ Carrier_Type ": "",
          "IIS_ Carrier_Num ": "",
          "IIS_ Love_Code ": "1234562"
      },
     {
          "IIS_Number": "UV11100012",
          "IIS_Relate_Number": "20181028000000020",
          "ChannelPartner": "",
    	  "IIS_Identifier": "0000000000",
    	  "IIS_Clearance_Mark": "",
    	  "IIS_Category": "B2C",
    	  "IIS_Tax_Type": "1",
    	  "IIS_Tax_Rate":0.050,
    	  "IIS_Tax_Amount": 0,
    	  "IIS_Sales_Amount": 100,
    	  "IIS_Create_Date": "2019-09-17 17:17:31",
    	  "IIS_Issue_Status": "1",
    	  "IIS_Invalid_Status": "0",
    	  "IIS_Upload_Status": "0",
    	  "IIS_Upload_Date": "",
    	  "IIS_Turnkey_Status": "",
    	  "IIS_Remain_Allowance_Amt": 0,
          "IIS_Award_Flag": "",
          "IIS_Award_Type": "11",
          "IIS_ Print_Flag ": "1",
          "IIS_ Carrier_Type ": "",
          "IIS_ Carrier_Num ": "",
          "IIS_ Love_Code ": "1234562"
       }
    ]
}

回傳CSV檔案格式說明

欄位名稱 型態 說明
總筆數
Number
顯示的頁數
Int
發票號碼
String
特店自訂編號
String
買方統編
String
0000000000代表沒有統編
通關方式
String

注意事項：
只有零稅率才會回傳以下資料
1：非經海關出口
2：經海關出口
發票類別
String

B2B：表示開立發票時有含統編
B2C：表示開立發票時沒有含統編
課稅別
String

1：應稅
2：零稅率
3：免稅
4：應稅(特種稅率)
9：若為混合應稅與免稅或零稅率
稅率
Number
小數點2位
稅金
Int
當發票有統編時，才會回傳稅金 當發票沒有統編時，稅金包含在發票金額內，不拆算稅金，故回傳值為0，支援整數11位
發票金額
Int
支援整數12位
發票開立時間
String
格式為「yyyy-MM-dd HH:mm:ss」
發票開立狀態
String

1：發票開立
0：發票註銷
發票作廢狀態
String

1：已作廢
0：未作廢
發票上傳狀態
String

1：已上傳
0：未上傳
發票上傳時間
String
格式為「yyyy-MM-dd HH:mm:ss」
發票上傳後接收狀態
String

C：成功
E：失敗
G：處理中(待財政部回覆狀態)
P：處理中(上傳財政部中)
折讓剩餘金額
Int
支援整數12位
中獎旗標
String

空值：未對獎、不可對獎（如：捐贈之發票）
0：未中獎
1：已中獎
X：有統編之發票
中獎種類
String

12：雲端發票獎800元
11：雲端發票獎500元
10：雲端發票獎100萬元
9：雲端發票獎2000元
8：特別獎 一千萬　
7：特獎 二百萬元
1：頭獎 二十萬元
2：二獎 四萬元
3：三獎 一萬元
4：四獎 四千元
5：五獎 一千元
6：六獎 二百元
0：未中獎
列印旗標
String

1：列印
0：不列印
載具類別
String

※無載具，為空值。

1. 為綠界電子發票載具
2. 為消費者自然人憑證
3. 為消費者手機條碼
載具編號
String

※無載具，為空值。

1. 綠界電子發票載具時，為客戶電子信箱或客戶手機號碼擇一(以客戶電子信箱優先) (RelateNumber)
2. 消費者使用載具為自然人憑證，格式應為2碼大寫英文字母加上14碼數字(長度共16碼)
3. 消費者使用載具為手機條碼時，目前總長度共為8碼，格式應為第1碼「/」加上由7碼數字及大寫英文字母及+-符號所組成。
捐款單位捐贈碼
String

財政部 - 查詢受捐贈機關或團體捐贈碼
通路商編號
String

1:蝦皮

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

綠界官方網站