B2B E-Invoice API Document (Certification Mode)

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
  • The length must be exactly 16 characters
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(200)

 

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
  • Please provide an integer value between 1 and 999.
  • The product order must match the order of items on the original invoice.

OriginalDescription String(500)

Original Goods Name

InvoiceType String(2)

Invoice Alphanumeric Letters Type

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

TaxType Int

1: General Taxable
2: Zero Tax Rate
3: Tax-Exempt
4: Special Taxable

AllowanceSequenceNumber String(3)

Allowance Sequence Number

Quantity Number

  • Goods Quantity
  • Return up to 8 digits for the integer part and 7 digits for the decimal part.
Unit String(6)
  • Goods Unit
  • The product unit can be up to 6 characters.
UnitPrice Number
  • Goods UnitPrice
  • Return up to 10 digits for the integer part and 7 digits for the decimal part.

Tax Int

  • Goods Tax
  • Return an integer with up to 11 digits.
     
     

Amount Number

  • Goods Amount
  • Return up to 12 digits for the integer part and 7 digits for the decimal part.

BalanceAmount Int

  • Allowance Amount
  • Return an integer with up to 12 digits.
     
     
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": "" 
}

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

Green World