B2B E-Invoice API Document (Certification Mode)

Searching Operations / Search Issue E-invoices

Scenarios

  • Merchant(Business Entity) can use this API to query issued information, including output invoices and input invoices, and Green World will return the results in a parametric manner.
  • This approach helps Merchant to integrate the issuing inquiry mechanism into the Merchant’s website to provide a quick inquiry service.

API URLs:

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

HTTPS format

  • Content Type ：application/json
  • HTTP Method ：POST

Request by Merchant (Json format)

PlatformID String(10)

  • Platform merchant ID
  • This parameter is provided by ECPAY to the platform vendor for project cooperation, please bring in the MerchantID bound with the platform vendor.
  • Please leave empty for general vendor.
  • When the platform vendor uses the MerchantID field, it can only bring in the MerchantID that has been bound as a sub-store, otherwise it will cause a failure.

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

InvoiceCategory Int
Required

Possible values:

  • 0: Output E-Invoices (Search the invoice issued to the Counterparty from the Merchant).
  • 1: Input E-invoices (Search the invoice of the Counterparty to the Merchant)

InvoiceNumber String(10)
Required

Invoice Number

InvoiceDate String(20)
Required

Invoice Issue date

  • The format is yyyy-mm-dd

RelateNumber String(20)

  • Unique ID of the e-invoice which is defined by the merchant itself.

Example

				
					{
    "MerchantID": "2000132",
    "InvoiceCategory": 0,
    "InvoiceNumber": "SA37758327",
    "InvoiceDate": "2019-08-31",
    "RelateNumber": "2019081602"
}

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.

RtnData String

Example

				
					{
    "RtnCode": 1,
    "RtnMsg": "Success",
    "RtnData": "..."
}

Parameters in RtnData

MerchantID String(10)

Merchant ID

InvoiceNumber String(10)

E-Invoice number

InvoiceDate String(20)
The format is yyyy-mm-dd
RelateNumber String(20)
Buyer_Identifier String(8)
Buyer_Name String(60)

Buyer Name

  • Will be output in the form of URL Encode coding
Buyer_Address String(100)

Buyer address

  • Will be output in the form of URL Encode coding
Buyer_TelephoneNumber String(26)

Buyer Telephone

Buyer_EmailAddress String(80)
Buyer Email
Buyer_FacsimileNumber String(26)
Buyer Facsimile
Seller_Identifier String(8)
  • If [InvoiceCategory]=0, then this parameter has no value.

Seller_Name String(60)

Seller Name

  • Will be output in the form of URL Encode coding
  • If [InvoiceCategory]=0,then this parameter has no value.

Seller_Address String(100)

Seller address

  • Will be output in the form of URL Encode coding
  • If [InvoiceCategory]=0,then this parameter has no value.

Seller_TelephoneNumber String(26)

Seller Telephone
  • If [InvoiceCategory]=0,then this parameter has no value.

Seller_EmailAddress String(80)

Seller Email
  • If [InvoiceCategory]=0,then this parameter has no value.

Seller_FacsimileNumber String(26)

Seller Facsimile
  • If [InvoiceCategory]=0,then this parameter has no value.
CustomsClearanceMark String(1)

Clearance Method

  • 1:Non-Customs exports
  • 2:Export through Customs
InvoiceType String(1)

Invoice category

  • 07:General tax computation
  • 08:Special tax computation
TaxType Int

Tax Type

  • 1.If [InvoiceType] = 07(General tax computation), then
    please enter 1(Regular Tax)、2(Zero-tax-rate)或3(Tax Free)
  • 2.If[InvoiceType] = 08(Special tax computation), then please enter 4(Special Tax)

TaxRate Number

Tax Rate
  • 1. If [TaxType] = 1(Regular Tax), The parameter is not required (the system will give 0.05)
  • 2. If [TaxType] = 2(Zero-tax-rate), The parameter is not required (the system will give 0)
  • 3. If [TaxType] = 3(Tax Free), The parameter is not required (the system will give 0)
  • 4. If [TaxType] = 4(Special Tax), The parameter is not required (the system will give 0.01~0.99)

SalesAmount Int

Sales Amount
  • 1. Please enter an integer and cannot be $0.
  • 2. Equal to the value that [ItemAmount] summed and rounded to the integer
TaxAmount Int

Tax Amount

TotalAmount Int

Total Amount

  • 1. Please enter an integer and cannot be $0.
  • 2. Equal to the value that [ItemAmount] summed and rounded to the
    integer.
IP String(15)
Issue IP

Create_Date String(20)

E-Invoice issuance time

  • Format is “yyyy-MM-dd HH:mm:ss”.

Issue_Status String(1)

E-Invoice Issuance status

  • 1: E-Invoice Issued
  • 0: E-Invoice invalidated

Invalid_Status String(1)

E-Invoice invalidation status

  • 1: Have been invalidated
  • 0: Not yet invalidated

Upload_Status String(1)

E-Invoice upload status

  • If [InvoiceCategory]=1, then this parameter has no value.
  • 0:Not Uploaded
  • 1:Uploaded
  • 2:Upload Failed

Upload_Date String(20)

E-Invoice upload time

  • Format is “yyyy-MM-dd HH:mm:ss”.
  • If [InvoiceCategory]=1, then this parameter has no value.
ConfirmDate String(20)

Confirm Date

  • 1. The format is yyyy-mm-dd
  • 2. If not set, then this parameter has no value.
ExchangeMode String(1)

Invoice Mode

  • 0:Certification mode
  • 1:Exchange mode
ExchangeStatus String(1)

Invoice Confirm Status

  • If this parameter has no value, it is not set.
  • 0:Not Confirmed
  • 1:Confirmed
BalanceAmount Number

Remaining Allowance Amount

MainRemark String(200)

Invoice Remark

RandomNumber String(4)

Random Number

ItemsArray[Object]

ItemSeq Int

Item Sequence Number

  • 1. Please enter an integer value of 1~999.
  • 2. Sequence number cannot be duplicated

ItemName String(256)

Item Name

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

  • Supports up to 8-digits integer and 7-digits decimal
  • Display the price before tax consistently
ItemTax Int

Tax of individual item/product

  • 1. Only integer acceptable.
  • 2. If this parameter has value, the difference between [ItemTax] and B (B = [ItemAmount]*[TaxRate] after being rounded) should not be larger than 1.

❗ Special notes : 

  1. 1. This field is only for validating the [TaxAmount]. ECPay will not upload to Ministry of Finance.
  2. 2. If it is special tax, please populate this parameter with 0.

ItemAmount Number

Merchandise total amount

  • 1. Supports up to 12-digits integer and 7-digits decimal
  • 2. If set [ItemCount]*[ItemPrice] as A, then the difference between [ItemAmount] and the value of A after rounding must not be greater than 1.

ItemRemark String(200)

Item Remark

Example

				
					{
    "MerchantID": "2000132",
    "InvoiceDate": "2019-08-31",
    "RelateNumber": "2019081602",
    "Buyer_Identifier": "11456006",
    "Buyer_Name": "Eric Shop",
    "Buyer_Address": "200 Taipei",
    "Buyer_TelephoneNumber": "02-12344321",
    "Buyer_EmailAddress": "abc@sunup.net",
    "Buyer_FacsimileNumber": "",
    "CustomsClearanceMark": "",
    "InvoiceType": "07",
    "TaxType": 1,
    "TaxRate": 0.05,
    "SalesAmount": 952,
    "TaxAmount": 48,
    "TotalAmount": 1000,
    "IP": 2130706433,
    "CreateDate": "2019-09-03 13:57:07",   
    "Issue_Status": "1",
    "Invalid_Status": "0",
    "Upload_Status": "1",
    "Upload_Date": "2019-09-03 14:57:07",
    "ConfirmDate": "2019-09-03 15:57:07",
    "ExchangeStatus": "1",
    "ExchangeMode": "0",
    "BalanceAmount": 952,
    "MainRemark": "",
    "RandomNumber": "6686",
    "Items": 
    [
        {
            "ItemSeq": 1,
            "ItemName": "Phone Test",
            "ItemCount": 1,
            "ItemWord": "piece",
            "ItemPrice": 952,
            "ItemAmount": 952,
            "ItemTax": 48,
            "ItemRemark": ""
        }
    ]
}

Copyright © Green World FinTech Service Co., Ltd. All rights reserved.

Green World