Searching Operations / Searching multiple E-invoice

Application Scenarios

The Merchant can use this API to query various types of e-invoice information, and ECPay provides the return in Json/CSV format.

Application Flow

This API uses a paginated response mechanism to display results and the results will be sorted according to the time of invoicing from new to old (e.g: 2022/10/12, 2022/10/01, 2022/09/01, 2022/07/06…)
The following describes the procedure of the API call step.
Step1. Execute the first API call, first set the number of pages returned per page – [NumPerPage] and the number of pages displayed – [ShowingPage, fixed with 1] to get the total number of data – [TotalCount] returned by the ECPay.
Step2. determine the number of API queries based on the total number of data – [TotalCount] obtained in Step1, and the number of paging required
For example, when TotalCount=300, and the paging requirement is 100 items per page, then you need to call 3 times to retrieve all the data (as shown in the table below)

Sequence of API calls	The value of [ShowingPage]	The value of [NumPerPage]
First Time	1	100
Second Time	2	100
Third Time	3	100

API URLs:

Stage：https://einvoice-stage.ecpay.com.tw/B2CInvoice/GetIssueList
Production：https://einvoice.ecpay.com.tw/B2CInvoice/GetIssueList

HTTPS format

Content Type ：application/json
HTTP Method ：POST

Request by Merchant (Json format)

PlatformID String(10)

This parameter is specifically designed for platform vendors collaborating with ECPay. It can only be utilized after applying for and activating the service.
If you are a general vendor, please leave the PlatformID empty.
When using this parameter, the MerchantID must be filled in with the specific store code bound to your PlatformID to prevent operation failures.
Please note that only the MerchantID of a bound sub-merchant can be used to avoid operational failures. For binding operations, please contact your business representative.

MerchantID String(10)
Required

RqHeader Object
Required

Request header

Timestamp Number
Required

Please convert the transmission time to a timestamp (GMT+8).
ECPay will use this parameter to convert the current time to Unix TimeStamp to verify the time interval of this connection.

Special Notes：

If ECPay receives the API call is more 10 minutes late than the timestamp sent by merchants, this request will be failed. Reference information is as follows：http://www.epochconverter.com/。
Merchants are suggested to frequently synchronize the time zone of server to another server of the nearest time zone.

Data String
Required

Message payload
This is the encrypted data in JSON format.
AES Encryption Description

Example

				
					{
    "MerchantID": "2000132",
    "RqHeader": {
        "Timestamp": 1525168923
    },
    "Data": "..."
}

Message payload of Data(Json format) : please urlencode the JSON string firstly and then do AES encryption

MerchantID String(10)
Required

BeginDate String(10)
Required

Beginning date to be queried
The format is “yyyy-MM-dd” or “yyyy/MM/dd”

EndDate String(10)
Required

Ending date to be queried
The format is “yyyy-MM-dd” or “yyyy/MM/dd”

NumPerPage Int
Required

The number of items per page

Special Notes : The maximum number of items displayed on a single page is 200

ShowingPage Int
Required

Number of pages to be displayed

Special Notes : The result data will be arranged in chronological order from newer to older according to when the invoice was first issued.

DataType Int

Types of Data Returned
1：Json (Default)
2：CSV

ChannelPartner String(1)

The rest of the values are ignored.

Query_Award String(1)

Winning or not
0：All (Default)
1：Y
2：N

Query_Invalid String(1)

Invalid or not
0：All (Default)
1：Y
2：N

Query_Print String(1)

Whether to request a paper invoice
0：All (Default)
1：Y
2：N
3：Processed

Query_Upload String(1)

Upload Status
0：Upload Status
1：Uploaded
2：Not uploaded
3：Upload failure

Query_Identifier String(1)

Whether to issuing with the Tax ID number (VAT number).

0：All (Default)
1：Y
2：N

Query_TaxType String(1)

The Type of the tax
0：All (Default)
1: Should be taxed
2: Tax rate is zero
3: Duty Free
4: Special tax
9: Combined tax

Query_Category String(1)

Type of e-invoice
0：All (Default)
1：B2C
2：POS
3：Off-line

Query_Customer_Name String(60)

Consumer Name

Query_Customer_Phone String(20)

Consumer cell phone number

Example

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

Response format

Content Type ：application/json
HTTP Method ：POST

Response by ECPay (Json format)

PlatformID String(10)

MerchantID String(10)
Required

RpHeader Object

Response header

Timestamp Number

Unix timestamp(GMT+8)

TransCode Int

Response code to indicate whether the payload is successfully accepted
Possible values:
1: Payload (i.e. MerchantID, RqHeader, and Data) is successfully accepted by ECPay.
Others: failed.

TransMsg String(200)

Response message to indicate whether the payload is successfully accepted

Data String

Message payload
Responde relevant data, this is the encrypted JSON format data。
AES Encryption Description

Example

				
					{
    "MerchantID": "2000132",
    "RpHeader": {
        "Timestamp": 1525169058
    },
    "TransCode": 1,
    "TransMsg": "",
    "Data": "..."
}

Message payload of Data(Json format): please do AES decryption to the Data firstly and then do urldecode.

RtnCode Int

Return codes to indicate whether the API is successfully executed or not.
Possible values:
1: API is successfully executed.
Others: failed.

RtnMsg String(200)

Return messages to indicate whether the API is successfully executed or not.

TotalCount Number

Number of total data

ShowingPage Int

Number of pages to be displayed

InvoiceData Array[Object]

Invoice information

IIS_Number String(10)

E-Invoice number

IIS_Relate_Number String(30)

Fix length: 30

ChannelPartner String(1)

1:Shopee

IIS_Identifier String(10)

Buyer Tax ID
0000000000 implies that there is no Tax ID

IIS_Clearance_Mark String(1)

Clearance Method
Only zero tax will return the following information
1: Export not via custom
2: Export via custom

IIS_Category String(10)

Invoice category
B2B: Indicates that the invoice is issued with Tax ID.
B2C: Indicates that the invoice is issued without Tax ID.

IIS_Tax_Type String(1)

Tax category
1: Should be taxed
2: Tax rate is zero
3: Duty Free
4: Special tax computation
9: If it is combined tax rate, zero tax or duty free

IIS_Tax_Rate Number

Tax rate
Up to 2 decimal places

IIS_Tax_Amount Int

Tax
Tax will be returned when the invoice has Tax ID.
When the invoice is not issued with Tax ID, tax is included in the invoice amount and not calculated separately, so the return value is 0.

IIS_Sales_Amount Int

E-Invoice amount

IIS_Create_Date String(20)

E-Invoice issuance time
Format is “yyyy-MM-dd HH:mm:ss”

IIS_Issue_Status String(1)

E-Invoice Issuance status
1: E-Invoice Issued
0: E-Invoice invalidated

IIS_Invalid_Status String(1)

E-Invoice invalidation status
1: Have been invalidated
0: Not yet invalidated

IIS_Upload_Status String(1)

E-Invoice upload status
1: Upload complete
0: Not yet uploaded

IIS_Upload_Date String(20)

E-Invoice upload time
Format is “yyyy-MM-dd HH:mm:ss”

IIS_Turnkey_Status String(1)

Reception status after E-Invoice uploaded
C: Success
E: Failure
G: Under processing (awaiting Ministry of Finance’s response)
P: Under processing (uploading to Ministry of Finance)

IIS_Remain_Allowance_Amt Int

Remaining amount of allowance

IIS_Print_Flag String(1)

Print flag
1: Print
0: Do not print

IIS_Award_Flag String(1)

Winning flag
Blank value: Did not check, cannot check (Such as: Donated E-Invoice)
0: Did not win
1: Won
X: E-Invoice with Tax ID

IIS_Award_Type String(2)

Type of winning lottery
Possible values:
12: Cloud E-Invoice Prize NTD 800
11: Cloud E-Invoice Prize NTD 500
10: Cloud E-Invoice Prize NTD 1 million
9: Cloud E-Invoice Prize NTD 2000
8: Bonus Prize NTD 10 million
7: Special Prize NTD 2 million
1: 1st Prize NTD 200000
2: 2nd Prize NTD 40000
3: 3rd Prize NTD 10000
4: 4th Prize NTD 4000
5: 5th Prize NTD 1000
6: 6th Prize NTD 200
0: Did not win

IIS_Carrier_Type String(1)

Carrier type
1: A Green World E-Invoice carrier
2: Is customer’s citizen digital certificate
3: Is customer’s cellphone number
※If no carrier, then it is a blank value.

IIS_Carrier_Num String(64)

Carrier code
If no carrier, then it is blank value
If it is a ECPay E-Invoice carrier, then it is the merchant’s carrier Tax ID + custom code (RelateNumber)
If customer’s carrier is their citizen digital certificate, the format should be two 2 alphabet character in addition to 14 numerical digits (Total length of 16 unites)
If customer’s carrier is their cellphone number, then its total length should be 8 units, sequence format of 1 code slash “/” followed by a sequence of 7 numerical digits, cap-sized alphabets and +-. symbols.

IIS_Love_Code String(7)

Donation party Donation code
Ministry of Finance -Search for donated organization or group’s donation code
https://www.einvoice.nat.gov.tw/APMEMBERVAN/XcaOrgPreserveCodeQuery/XcaOrgPreserveCodeQuery

Example

				
					{
  "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 format (Chinese Only)

欄位名稱	型態	說明
總筆數	Number
顯示的頁數	Int
發票號碼	String
特店自訂編號	String
買方統編	String	0000000000 implies that there is no Tax ID
通關方式	String	Special notes : Only zero tax will return the following information 1: Export not via custom 2: Export via custom
發票類別	String	B2B: Indicates that the invoice is issued with Tax ID. B2C: Indicates that the invoice is issued without Tax ID
課稅別	String	1: Should be taxed 2: Tax rate is zero 3: Duty Free 4: Special tax computation 9: If it is combined tax rate, zero tax or duty free
稅率	Number	Up to 2 decimal places
稅金	Int	Tax will be returned when the invoice has Tax ID. When the invoice is not issued with Tax ID, tax is included in the invoice amount and not calculated separately, so the return value is 0.
發票金額	Int
發票開立時間	String	Format is “yyyy-MM-dd HH:mm:ss”
發票開立狀態	String	1: E-Invoice Issued 0: E-Invoice invalidated
發票作廢狀態	String	1: Have been invalidated 0: Not yet invalidated
發票上傳狀態	String	1: Upload complete 0: Not yet uploaded
發票上傳時間	String	Format is “yyyy-MM-dd HH:mm:ss”
發票上傳後接收狀態	String	C: Success E: Failure G: Under processing (awaiting Ministry of Finance’s response) P: Under processing (uploading to Ministry of Finance)
折讓剩餘金額	Int
中獎旗標	String	Blank value: Did not check, cannot check (Such as: Donated E-Invoice) 0: Did not win 1: Won X: E-Invoice with Tax ID
中獎種類	String	Possible values: 12: Cloud E-Invoice Prize NTD 800 11: Cloud E-Invoice Prize NTD 500 10: Cloud E-Invoice Prize NTD 1 million 9: Cloud E-Invoice Prize NTD 2000 8: Bonus Prize NTD 10 million 7: Special Prize NTD 2 million 1: 1st Prize NTD 200000 2: 2nd Prize NTD 40000 3: 3rd Prize NTD 10000 4: 4th Prize NTD 4000 5: 5th Prize NTD 1000 6: 6th Prize NTD 200 0: Did not win
列印旗標	String	1: Print 0: Do not print
載具類別	String	1: A Green World E-Invoice carrier 2: Is customer’s citizen digital certificate 3: Is customer’s cellphone number ※If no carrier, then it is a blank value.
載具編號	String	If no carrier, then it is blank value If it is a ECPay E-Invoice carrier, then it is the merchant’s carrier Tax ID + custom code (RelateNumber) If customer’s carrier is their citizen digital certificate, the format should be two 2 alphabet character in addition to 14 numerical digits (Total length of 16 unites) If customer’s carrier is their cellphone number, then its total length should be 8 units, sequence format of 1 code slash “/” followed by a sequence of 7 numerical digits, cap-sized alphabets and +-. symbols.
捐款單位捐贈碼	String	Ministry of Finance -Search for donated organization or group’s donation code LINK

Green World