查詢特定多筆發票

應用場景

特店可使用此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)
特店編號 必填

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:蝦皮

YAML

提供的 YAML 文件用於定義 API 的配置、結構、操作和基礎設施管理等資訊，方便開發人員理解和使用 API。

				
					openapi: 3.1.0
info:
  title: ECPay Query Multiple Invoices API
  version: 1.0.0
servers:
  - url: https://einvoice-stage.ecpay.com.tw
    description: Testing Environment
  - url: https://einvoice.ecpay.com.tw
    description: Production Environment
paths:
  /B2CInvoice/GetIssueList:
    post:
      summary: Query Multiple Invoices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - MerchantID
                - RqHeader
                - Data
              properties:
                PlatformID:
                  type: string
                  maxLength: 10
                  description: Platform ID for partnered platforms
                MerchantID:
                  type: string
                  maxLength: 10
                  description: Merchant ID
                RqHeader:
                  type: object
                  required:
                    - Timestamp
                  properties:
                    Timestamp:
                      type: integer
                      description: Unix timestamp (GMT+8)
                Data:
                  type: string
                  description: Encrypted data containing request details
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  PlatformID:
                    type: string
                    maxLength: 10
                    description: Platform ID for partnered platforms
                  MerchantID:
                    type: string
                    maxLength: 10
                    description: Merchant ID
                  RpHeader:
                    type: object
                    properties:
                      Timestamp:
                        type: integer
                        description: Unix timestamp (GMT+8)
                  TransCode:
                    type: integer
                    description: Transmission code
                  TransMsg:
                    type: string
                    maxLength: 200
                    description: Transmission message
                  Data:
                    type: string
                    description: Encrypted data containing response details
components:
  schemas:
    requestBody.Data:
      type: object
      required:
        - MerchantID
        - BeginDate
        - EndDate
        - NumPerPage
        - ShowingPage
      properties:
        MerchantID:
          type: string
          maxLength: 10
          description: Merchant ID
        BeginDate:
          type: string
          description: Start date for query in 'yyyy-MM-dd' or 'yyyy/MM/dd' format
        EndDate:
          type: string
          description: End date for query in 'yyyy-MM-dd' or 'yyyy/MM/dd' format
        NumPerPage:
          type: integer
          description: Number of records per page (max 200)
        ShowingPage:
          type: integer
          description: Page number to display
        DataType:
          type: integer
          description: Data return type (1= Json, 2= CSV)
        ChannelPartner:
          type: string
          maxLength: 1
          description: Channel partner ID
        Query_Award:
          type: string
          maxLength: 1
          description: Query for winning status (0= All, 1= Yes, 2= No)
        Query_Invalid:
          type: string
          maxLength: 1
          description: Query for invalid status (0= All, 1= Yes, 2= No)
        Query_Print:
          type: string
          maxLength: 1
          description: Query for print status (0= All, 1= Yes, 2= No, 3= Processed)
        Query_Upload:
          type: string
          maxLength: 1
          description: Query for upload status (0= All, 1= Uploaded, 2= Not uploaded, 3= Upload failed)
        Query_Identifier:
          type: string
          maxLength: 1
          description: Query for identifier (0= All, 1= Yes, 2= No)
        Query_TaxType:
          type: string
          maxLength: 1
          description: Query for tax type (0= All, 1= Taxable, 2= Zero tax, 3= Exempt, 4= Special tax rate, 9= Mixed)
        Query_Category:
          type: string
          maxLength: 1
          description: Query for invoice category (0= All, 1= B2C, 2= POS, 3= Offline)
        Query_Customer_Name:
          type: string
          maxLength: 60
          description: Query for customer name
        Query_Customer_Phone:
          type: string
          maxLength: 20
          description: Query for customer phone number
    responses.Data:
      type: object
      properties:
        RtnCode:
          type: integer
          description: Response code
        RtnMsg:
          type: string
          maxLength: 200
          description: Response message
        TotalCount:
          type: integer
          description: Total number of records
        ShowingPage:
          type: integer
          description: Displayed page number
        InvoiceData:
          type: array
          items:
            type: object
            properties:
              IIS_Number:
                type: string
                maxLength: 10
                description: Invoice number
              IIS_Relate_Number:
                type: string
                maxLength: 30
                description: Merchant-defined unique number
              ChannelPartner:
                type: string
                maxLength: 1
                description: Channel partner ID
              IIS_Identifier:
                type: string
                maxLength: 10
                description: Buyer identifier
              IIS_Clearance_Mark:
                type: string
                maxLength: 1
                description: Clearance mark
              IIS_Category:
                type: string
                maxLength: 10
                description: Invoice category
              IIS_Tax_Type:
                type: string
                maxLength: 1
                description: Tax type
              IIS_Tax_Rate:
                type: number
                description: Tax rate
              IIS_Tax_Amount:
                type: number
                description: Tax amount
              IIS_Sales_Amount:
                type: number
                description: Sales amount
              IIS_Create_Date:
                type: string
                description: Invoice creation date in 'yyyy-MM-dd HH:mm:ss' or 'yyyy/MM/dd HH:mm:ss' format
              IIS_Issue_Status:
                type: string
                maxLength: 1
                description: Invoice issue status
              IIS_Invalid_Status:
                type: string
                maxLength: 1
                description: Invoice invalidation status
              IIS_Upload_Status:
                type: string
                maxLength: 1
                description: Invoice upload status
              IIS_Upload_Date:
                type: string
                description: Invoice upload date in 'yyyy-MM-dd' or 'yyyy/MM/dd' format
              IIS_Turnkey_Status:
                type: string
                maxLength: 1
                description: Turnkey status
              IIS_Remain_Allowance_Amt:
                type: number
                description: Remaining allowance amount
              IIS_Print_Flag:
                type: string
                maxLength: 1
                description: Print flag
              IIS_Award_Flag:
                type: string
                maxLength: 1
                description: Award flag
              IIS_Award_Type:
                type: string
                maxLength: 2
                description: Award type
              IIS_Carrier_Type:
                type: string
                maxLength: 1
                description: Carrier type
              IIS_Carrier_Num:
                type: string
                maxLength: 64
                description: Carrier number
              IIS_Love_Code:
                type: string
                maxLength: 7
                description: Donation code

綠界官方網站