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 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

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

YAML

The provided YAML file is used to define the configuration, structure, operations, and infrastructure management information of the API, making it easier for developers to understand and use the 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

Green World