Application Scenarios
- This API provides the function of searching the state of Letter Track Numbers (i.e. TrackID, UseStatus).
API URLs:
- Stage: https://einvoice-stage.ecpay.com.tw/B2CInvoice/GetInvoiceWordSetting
- Production: https://einvoice.ecpay.com.tw/B2CInvoice/GetInvoiceWordSetting
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": "..."
}
Message payload of Data(Json format) : please urlencode the JSON string firstly and then do AES encryption
MerchantID String(10)
Required
InvoiceYear String(3)
Required
- The year of the e-invoice (in “Republic Era”)
- Only last year, this year and next year can be looked-up. The year is referred to the “Republic Era.” For example, the year “2021” is the 110th year of the Republic Era, so the value should be: “110”.
InvoiceTerm Int
Required
- Period of e-invoice
- Each period spans for two months, and the starting month is always odd month (i.e. January, March, May, July, September and November). So in total there are six periods. Following lists the values standing for each period.
Possible values:
1: Jan.-Feb.
2: Mar.-Apr.
3: May-Jun.
4: Jul.-Aug.
5: Sep.-Oct.
6: Nov.-Dec.
UseStatus Int
Required
- State of the letter track to be searched
- Values could be:
0: all
1: disabled
2: enabled
3: deactivated (not in use).
4: suspended.
5: pending review (i.e. the application is still pending)
6: review failed
InvoiceCategory String(1)
Required
- Category of e-invoice
- Fixed value: 1
indicates thie API specification (B2C)
InvType String(2)
- Type of letter track of e-invoice
In general, there are 2 types: one is general tax and the other is special tax, depending on which business your company belongs to.
Possible values:
07: general tax (common business or e-commerce, which shall be no less than 5 %).
08: special tax (i.e. for special food and beverage services enterprises, such as night clubs or restaurants providing entertaining show programs, saloons and tea rooms and bars offering companionship services).
InvoiceHeader String(2)
- InvoiceHeader
The e-invoice letter track is a 2 uppercase English letters, which is assigned by the the E-invoice Platform of MOF.
For example, KK or KG.
Example
{
"MerchantID": 2000132,
"InvoiceYear": "109",
"InvoiceTerm": 0,
"UseStatus": 1,
"InvoiceCategory": 1
}
Response format
- Content Type ：application/json
- HTTP Method ：POST
Response by ECPay (Json format)
PlatformID String(10)
MerchantID String(10)
Required
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.
TrackID String(10)
ID of the letter track numbers
InvoiceYear String(3)
The year of the e-invoice (in “Republic Era”)
InvoiceTerm Int
- Period of e-invoice
- Each period spans for two months, and the starting is an odd month (i.e. January, March, May, July, September and November). So in total there are six periods in a year. Following lists the value returned of each period.
1: Jan.-Feb.
2: Mar.-Apr.
3: May-Jun.
4: Jul.-Aug.
5: Sep.-Oct.
6: Nov.-Dec.
InvoiceCategory Int
- Category of e-invoice
- Fixed 1: B2C e-invoice
InvType String(2)
- Type of letter track of e-invoice
In general, there are 2 types: one is general tax and the other is special tax, depending on which business your company belongs to.
Possible values:
07: general tax (common business or e-commerce, which shall be no less than 5 %).
08: special tax (i.e. for special food and beverage services enterprises, such as night clubs or restaurants providing entertaining show programs, saloons and tea rooms and bars offering companionship services).
InvoiceHeader String(2)
The letter track of the e-invoice
InvoiceStart String(8)
Starting number of each unit
InvoiceEnd String(8)
Ending number of each unit
InvoiceNo String(8)
E-invoice numbers which are already been issued or used.
UseStatus Int
- State of the letter track to be searched
- Values could be:
0: all
1: disabled
2: enabled
3: deactivated (not in use).
4: suspended.
5: pending review (i.e. the application is still pending)
6: review failed
Example
{
"RtnCode": 1,
"RtnMsg": "Success"
"InvoiceInfo": {
"TrackID": "1234567890",
"InvoiceYear": "109",
"InvoiceTerm": 1,
"InvoiceCategory": 1,
"InvType": "07",
"InvoiceHeader": "AQ",
"InvoiceStart": "10000000",
"InvoiceEnd": "19999999",
"InvoiceNo": "12345678",
"UseStatus": 2
},{
"TrackID": "1234569870",
"InvoiceYear": "109",
"InvoiceTerm": 1,
"InvoiceCategory": 1,
"InvType": "07",
"InvoiceHeader": "AQ",
"InvoiceStart": "10000000",
"InvoiceEnd": "19999999",
"InvoiceNo": "12345678",
"UseStatus": 2
}
}