Searching Operations / Searching E-invoice

Application Scenarios

This API provides the function of searching a particular e-invoice. Merchants can search either by RelateNumber or by InvoiceNo.
If you have a large number of inquiries, we recommend using Searching multiple E-invoice。

API URLs:

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

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": "..."
}

Scenario 1 : search by RelateNumber

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

MerchantID String(10)
Required

RelateNumber String(30)
Required

Unique ID of the e-invoice which is defined by the merchant itself.
Fix length: 30

Example

				
					{
   "MerchantID": 2000132,
   "RelateNumber": "20181028000000020",
}

Scenario 2 : search by InvoiceNo and InvoiceDate

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

MerchantID String(10)
Required

InvoiceNo String(10)
Required

Number of e-invoice

InvoiceDate String(10)
Required

Date of e-invoice created
The format: yyyy-MM-dd

Example

				
					{
   "MerchantID": 2000132,
   "InvoiceNo": "AA123456",
   "InvoiceDate": "2018-10-28"
}

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.

IIS_Mer_ID String(10)

Merchant ID

ChannelPartner String(1)

1:Shopee

IIS_Number String(10)

E-Invoice number

IIS_Relate_Number String(30)

Unique ID of the e-invoice
Fix length: 30

IIS_Customer_ID String(20)

Customer code

IIS_Identifier String(10)

Buyer Tax ID
0000000000 implies that there is no Tax ID

IIS_Customer_Name String(60)

Customer name
Will be output in the form of URL Encode coding

IIS_Customer_Addr String(100)

Customer address
Will be output in the form of URL Encode coding

IIS_Customer_Phone String(20)

Customer Phone Number

IIS_Customer_Email String(80)

Customer E-mail

IIS_Clearance_Mark String(1)

Clearance Method
1: Export not via custom
2: Export via custom

IIS_Type String(2)

Invoice category
07: General tax amount calculation

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

SpecialTaxType String(1)

Special Tax Type
If [TaxType] is 1/2/9, please fill in 0.
If [TaxType] is 3, please fill in 8.
If [TaxType] is 4, and the parameter is required.
The parameter can fill in 1-8.
1：Saloons and tea rooms, coffee shops and bars offering companionship services：Tax rate is 25%.
2：Night clubs or restaurants providing entertaining show programs: Tax rate is 15%.
3：Banking businesses, insurance businesses, trust investment businesses, securities businesses, futures businesses, commercial paper businesses and pawn-broking businesses: Tax rate is 2%.
4：The sales amounts from reinsurance premiums shall be taxed at 1%.
5：Banking businesses, insurance businesses, trust investment businesses, securities businesses, futures businesses, commercial paper businesses and pawn-broking businesses: Tax rate is 5%
6：Core business revenues from the banking and insurance business of the banking and insurance industries (Applicable to sales after July 2014): Tax rate is 5%.
7：Core business revenues from the banking and insurance business of the banking and insurance industries (Applicable to sales after June 2014): Tax rate is 5%.
8：Duty free or non-output data.

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_Check_Number String(4)

E-Invoice check digit

Special notes : This parameter is deactivated, please ignore the return value of this parameter

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

IIS_IP String(20)

E-Invoice Issuance IP

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

Items Array[Object]

ItemSeq Int

Item Sequence Number

ItemName String(100)

Item Name
1.The parameter shall be exempted when calculating the check digit
2.Will be output in the form of URL Encode coding

ItemCount Number

Merchandise quantity
It could be up to 8 integers and 2 decimals after the decimal point.

ItemWord String(6)

Merchandise units
1.The parameter shall be exempted when calculating the check digit
2.Will be output in the form of URL Encode coding

ItemPrice Number

Merchandise price

ItemTaxType String(1)

Merchandise tax category
1: Should be taxed
2: Tax rate is zero
3: Duty Free

Special notes :

Preset is an empty string, when the tax category [TaxType] = 9, this parameter cannot be null.
When [TaxType]=9, [ItemTaxType] will need to discern the tax rate of each merchandise, amongst them should be at least 1 item that is 1(To be taxed) and another as 2(Duty Free) or 3(Tax rate is zero). Implying the combined tax rate E-Invoice can only be: 1|3(To be taxed and Duty Free) or 1|2(To be taxed and tax rate is zero).

ItemAmount Number

Merchandise total amount

ItemRemark String(40)

Merchandise notation explanation
If the parameter is not brought along or does not have value, the preset is blank
The parameter shall be exempted when calculating the check digit
Will be output in the form of URL Encode coding

InvoiceRemark String(200)

E-Invoice Notation
The parameter shall be exempted when calculating the check digit
Will be output in the form of URL Encode coding

Example

				
					{
    "IIS_Mer_ID": "2000132",
    "ChannelPartner": "",
    "IIS_Number": "UV11100012",
    "IIS_Relate_Number": "20181028000000020",
    "IIS_Customer_ID": "",
    "IIS_Identifier": "0000000000",
    "IIS_Customer_Name": "Name",
    "IIS_Customer_Addr": "Address",
    "IIS_Customer_Phone": "",
    "IIS_Customer_Email": "test@ecpay.com.tw",
    "IIS_Clearance_Mark": "",
    "IIS_Type": "07",
    "IIS_Category": "B2C",
    "IIS_Tax_Type": "1",
    "IIS_Tax_Rate":0.050,
    "IIS_Tax_Amount": 0,
    "IIS_Sales_Amount": 100,
    "IIS_Check_Number": "P",
    "IIS_Carrier_Type": "",
    "IIS_Carrier_Num": "",
    "IIS_Love_Code": "0",
    "IIS_IP": "0",
    "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_Print_Flag": "1",
    "IIS_Award_Flag": "",
    "IIS_Award_Type": "",
    "IIS_Random_Number": "6866",
    "IIS_Comment": "note",
    "QRCode_Left": "UV111000121080917686600000000000000640000000011456006Sxys2hDhHuVVGnbc7XhCOg==:**********:2:3:1:item01:1:50:",
    "QRCode_Right": "**item02:1:20",
    "PosBarCode": "10810UV111000126866",
    "Items": [
        {
            "ItemSeq": 1,
            "ItemName": "item01",
            "ItemCount": 1,
            "ItemWord": "test",
            "ItemPrice": 50,
            "ItemTaxType": "1",
            "ItemAmount": 50,
            "ItemRemark": "item01_desc"
        },
        {
            "ItemSeq": 2,
            "ItemName": "item02",
            "ItemCount": 1,
            "ItemWord": "test",
            "ItemPrice": 20,
            "ItemTaxType": "1",
            "ItemAmount": 20,
            "ItemRemark": "item02_desc"
        },
        {
            "ItemSeq": 3,
            "ItemName": "item03",
            "ItemCount": 3,
            "ItemWord": "test",
            "ItemPrice": 10,
            "ItemTaxType": "1",
            "ItemAmount": 30,
            "ItemRemark": "item03_desc"
        }
    ],
    "RtnCode": 1,
    "RtnMsg": "Success"
}

Green World