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

Scenario 1 : search by RelateNumber

Message payload of Data (JSON format): please urlencode the JSON string first 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 first 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
Respond with 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 first and then perform 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 indicating 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"
}

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 Invoice Details 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/GetIssue:
    post:
      summary: Query Invoice Details
      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
        - RelateNumber
        - InvoiceNo
        - InvoiceDate
      properties:
        MerchantID:
          type: string
          maxLength: 10
          description: Merchant ID
        InvoiceNo:
          type: string
          description: Invoice number
        InvoiceDate:
          type: string
          format: date
          description: Invoice date (yyyy-MM-dd or yyyy/MM/dd)
        RelateNumber:
          type: string
          maxLength: 30
          description: Unique merchant number
    responses.Data:
      type: object
      properties:
        RtnCode:
          type: integer
          description: Response code
        RtnMsg:
          type: string
          maxLength: 200
          description: Response message
        IIS_Mer_ID:
          type: string
          maxLength: 10
          description: Merchant ID
        ChannelPartner:
          type: string
          maxLength: 1
          description: Channel partner ID
        IIS_Number:
          type: string
          maxLength: 10
          description: Invoice number
        IIS_Relate_Number:
          type: string
          maxLength: 30
          description: Merchant-defined unique number
        IIS_Customer_ID:
          type: string
          maxLength: 20
          description: Customer ID
        IIS_Identifier:
          type: string
          maxLength: 10
          description: Customer identifier
        IIS_Customer_Name:
          type: string
          maxLength: 60
          description: Customer name
        IIS_Customer_Addr:
          type: string
          maxLength: 100
          description: Customer address
        IIS_Customer_Phone:
          type: string
          maxLength: 20
          description: Customer phone
        IIS_Customer_Email:
          type: string
          maxLength: 80
          description: Customer email
        IIS_Clearance_Mark:
          type: string
          maxLength: 1
          description: Clearance mark
        IIS_Type:
          type: string
          maxLength: 2
          description: Invoice type
        IIS_Category:
          type: string
          maxLength: 10
          description: Invoice category
        IIS_Tax_Type:
          type: string
          maxLength: 1
          description: Tax type
        SpecialTaxType:
          type: integer
          description: Special 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_Check_Number:
          type: string
          maxLength: 4
          description: Check number
        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
        IIS_IP:
          type: string
          maxLength: 20
          description: Invoice issuance IP
        IIS_Create_Date:
          type: string
          description: Invoice creation date
        IIS_Issue_Status:
          type: string
          maxLength: 1
          description: Invoice issuance 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
        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
        Items:
          type: array
          items:
            type: object
            required:
              - ItemSeq
              - ItemName
              - ItemCount
              - ItemWord
              - ItemPrice
              - ItemAmount
            properties:
              ItemSeq:
                type: integer
                description: Item sequence number
              ItemName:
                type: string
                maxLength: 100
                description: Item name
              ItemCount:
                type: number
                description: Item quantity
              ItemWord:
                type: string
                maxLength: 6
                description: Item unit
              ItemPrice:
                type: number
                description: Item unit price
              ItemTaxType:
                type: string
                maxLength: 1
                description: Item tax type
              ItemAmount:
                type: number
                description: Item total amount
              ItemRemark:
                type: string
                maxLength: 40
                description: Item remark
        IIS_Random_Number:
          type: string
          maxLength: 4
          description: Random number
        InvoiceRemark:
          type: string
          maxLength: 200
          description: Invoice remark
        PosBarCode:
          type: string
          description: Barcode for electronic invoice
        QRCode_Left:
          type: string
          description: Left QR code for electronic invoice
        QRCode_Right:
          type: string
          description: Right QR code for electronic invoice

Green World