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/B2BInvoice/GetIssueList
Production：https://einvoice.ecpay.com.tw/B2BInvoice/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 more than 10 minutes after the timestamp sent by merchants, this request will fail. Reference information is as follows：http://www.epochconverter.com/。
Merchants are advised to frequently synchronize their server’s time to the nearest time zone server.

Data String
Required

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

Example

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

Respond with relevant data, this is the encrypted JSON format data

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

DateType Int
Required

1: Invoice Date
2: Record Date

InvoiceType Int
Required

1: By Invoice Number
2: By Invoice Number Range

InvoiceCategory Int

0：Output Invoices
1：Input Invoices

InvoiceNumber String(10)

This field is required when InvoiceType = 1.

InvoiceStart String(10)

This field is required when InvoiceType = 2.

InvoiceEnd String(10)

This field is required when InvoiceType = 2.

RelateNumber String(50)

SendMethod String(1)

Invoice Delivery Type
0: All (Default)
1: Exchange
2: Certification

InvStatus String(1)

Invoice Issuance Status

0: All (Default)
1: Issued
2: Invalidated
3: Rejected

UploadStatus String(1)

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

ApprovalStatus String(1)

Buyer Confirmation Status
0: All (Default)
1: Confirmed
2: Not Confirmed

CustomerIdentifier String(8)

Buyer Unified Business No.

CustomerName String(60)

Buyer Name

SellerIdentifier String(8)

Seller Unified Business No.

SellerName String(60)

Seller Name

Example

				
					{
   "MerchantID": "2000132",
   "BeginDate": "2025-10-28",
   "EndDate": "2025-11-10",
   "NumPerPage": 200,
   "ShowingPage": 2,
   "DataType": 1,
   "InvoiceType":1,
   "InvoiceCategory":1,
   "InvoiceNumber":"AB12345678"
}

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

InvoiceNumber String(10)

E-Invoice number

RelateNumber String(50)

Fix length: 50

TaxType Int

1: Regular Tax
2: Zero-tax-rate
3: Tax Free
4: Special Tax
9: Mixed Taxable and Zero-rated

TotalAmount Number

E-Invoice amount

TaxAmount Number

BalanceAmount Number

Remaining Allowance Amount

TaxRate Number

TaxRate Number

Buyer_Identifier String(8)

Buyer Unified Business No.

Buyer_Name String(60)

Buyer_Address String(100)

Buyer_TelephoneNumber String(26)

Buyer_EmailAddress String(200)

Buyer_FacsimileNumber String(26)

InvoiceDate String(10)

Invoice Issue Date
Format: “yyyy-MM-dd” or “yyyy/MM/dd”

Upload_Date String(20)

Invoice Upload Time.
If InvoiceCategory = 1, this parameter has no value.

Upload_Status String(1)

Invoice Upload Status

If InvoiceCategory = 1, this parameter has no value.

0: Not Uploaded
1: Uploaded
2: Upload Failed

Issue_Status String(1)

Invoice Issuance Status

0: E-Invoice Invalidated
1: E-Invoice Issued

CustomsClearanceMark String(1)

Note：

This data will only be returned when the tax rate is Zero-tax-rate.

1: Non-Customs exports
2: Export through Customs

ZeroTaxRateReason String(2)

Starting from January 1, 2026, when the tax category [TaxType] is 2 (zero-rated), this field is mandatory or must be configured in the merchant’s backend for the system to retrieve the data correctly. Otherwise, the invoice issuance will fail. The valid values are as follows:
71: (Item 1) Exported goods
72: (Item 2) Export-related services or services provided domestically but used abroad
73: (Item 3) Sales by duty-free shops established in accordance with the law to transit or outbound passengers
74: (Item 4) Sales of goods or services to enterprises in bonded zones for operational use
75: (Item 5) International transportation services. However, for foreign transportation enterprises operating international transport services within the Republic of China, such services are limited to those granted reciprocal treatment or tax exemption by their home countries
76: (Item 6) Vessels, aircraft, and deep-sea fishing boats used for international transportation
77: (Item 7) Sales of goods or repair services for vessels, aircraft, and deep-sea fishing boats used for international transportation
78: (Item 8) Sales by bonded zone enterprises to taxable zone enterprises where the goods are directly exported without entering the taxable zone
79: (Item 9) Sales by bonded zone enterprises to taxable zone enterprises where the goods are stored in Free Trade Zone enterprises or customs-controlled bonded warehouses/logistics centers for export purposes

CustomerNumber String(20)

RandomNumber String(4)

MainRemark String(200)

ExchangeMode String(1)

0: Certification Mode — ECPay will upload your invoice data to the Ministry of Finance. This applies only to output invoices.
※ The Value-Added Center is unable to receive e-invoices issued to you by other business entities.

1: Exchange Mode — ECPay will upload the invoice data to the Ministry of Finance’s e-invoice transmission software for the counterparty business entity to confirm and receive.

ExchangeStatus String(1)

Invoice Confirm Status

If this parameter has no value, it is not set.

0: Not Confirmed
1: Confirmed

Seller_Identifier String(8)