Searching Operations / Search Allowance E-Invoices

Scenarios

Merchant(Business Entity) may use this API to query allowanced invoice information, including output invoices and input invoices, and Green World will reply to the results as a return parameter.
This will help Merchant(Business Entity) to integrate the inquiry mechanism for the allowanced invoice into the Merchant website and provide a quick inquiry service.

API URLs:

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

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

AllowanceNo String(16)
Required

Example

				
					{
    "MerchantID": "2000132",
    "AllowanceNo": "1909241702402030"
}

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

AllowanceNo String(16)

Green World Allowance Number

AllowanceNumber String(16)

The allowance number provided by the merchant

AllowanceType String(20)

Allowance Type

Buyer_Identifier String(8)

Buyer Identifie

Buyer_Name String(60)

Buyer Name

Buyer_Address String(100)

Buyer Address

Buyer_TelephoneNumber String(26)

Buyer Telephone Number

Buyer_EmailAddress String(80)

Buyer_EmailAddress

Seller_Identifier String(8)

Seller Name

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

Seller_Name String(60)

Seller Identifier

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

AllowanceDate String(20)

Allownace Date

TotalAmount Int

Total Allowance Amount(Untaxed)

TaxAmount Int

Tax Amount

IP String(15)

Allowance IP

Upload_Status String(1)

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

Invalid_Status String(1)

0:Not Canneled
1:Canceled

ExchangeStatus String(1)

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

Items Array[Object]

OriginalInvoiceNumber
String(10)

Original Invoice Number

OriginalInvoiceDate
String(20)

Original Invoice Date

The format is yyyy-mm-dd

OriginalSequenceNumber
String(3)

Original Sequence Number

OriginalDescription String(256)

Original Goods Name

InvoiceType String(2)

Invoice Alphanumeric Letters Type

07:General tax computation
08:Special tax computation

TaxType String(2)

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

AllowanceSequenceNumber String(3)

Allowance Sequence Number

Quantity Number

Goods Quantity

Unit String(6)

Goods Unit

UnitPrice Number

Goods UnitPrice

Tax Int

Goods Tax

Amount Number

Goods Amount

BalanceAmount Number

Allowance Amount

Remark String(200)

Example

				
					{
    "MerchantID": "2000132",
    "AllowanceNo": "1909241702402030",
    "AllowanceNumber": "1909241702402030",
    "AllowanceType": "2",
    "Buyer_Identifier": "23165448",
    "Buyer_Name": "Eric Lin",
    "Buyer_Address": "100Taipei",
    "Buyer_TelephoneNumber": "02-26551775",
    "Buyer_EmailAddress": "abc1234@gmail.com",
    "Seller_Identifier": "12345671",
    "Seller_Name": "Green World BETA Co.,Ltd",
    "AllowanceDate": "2019-09-24",
    "TotalAmount": 24,
    "TaxAmount": 1,
    "IP": 2130706433,
    "Upload_Status": "0",
    "Upload_Date": "2019-09-24",
    "ConfirmDate": "2019-09-25",
    "Invalid_Status": "0",
    "ExchangeStatus": "1",
    "Items": [
         {
            "OriginalInvoiceDate": "2019-09-24 00:00:00",
            "OriginalInvoiceNumber": "VG11000003",
            "OriginalSequenceNumber": 1,
            "OriginalDescription": "Package",
            "InvoiceType": "07",
            "TaxType": 1,
            "AllowanceSequenceNumber": 1,
            "Quantity": 2,
            "Unit": "piece",
            "UnitPrice": 12,
            "Tax": 1,
            "Amount": 24,
            "BalanceAmount": 0
        }
    ] ,
 "Remark": "" 
}

Green World