Scenarios
- Before issuing the e-invoice, merchants can call this API to set or add e-invoice letter track, which is a 2 uppercase English letters given by local branch or office of National Taxation Bureau of MOF. If API request is successful, a TrackID will be returned, which should be saved for later activating the state in order to issue e-invoice.
- An invoice number always contain a letter track and a serial numbers of 8 digits. The numbers, which ranges between InvoiceStart and InvoiceEnd, could be viewed as a unit. Each letter track (i.e. InvoiceHeader, which is “字軌” in Chinese) can have more than one unit. For example, InvoiceStart: 10000000 to InvoiceEnd: 10000049 is a unit and 10000050-10000099 is another; the two units can share the same letter track/InvoiceHeader. For example, if the letter track is KK, the letter track number could be: KK10000000, KK10000099.
Special Notes :
- Before adding or setting the letter track (InvoiceHeader), be sure to double check its correctness to avoid any typo or mistakes.
- When the letter track number is set, the default state has not yet been activated. To activate it, please call the API (/UpdateInvoiceWordStatus) to do so, which is detailed in next chapter.
API URLs:
- Stage: https://einvoice-stage.ecpay.com.tw/B2BInvoice/AddInvoiceWordSetting
- Production: https://einvoice.ecpay.com.tw/B2BInvoice/AddInvoiceWordSetting
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
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
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.
InvoiceYear String(3)
Required
- The year of the e-invoice (in “Republic Era”)
- Only this year and next year can be set. 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”.
InvType String(2)
Required
- Type of letter track
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. 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).
InvoiceCategory String(1)
Required
- Category of e-invoice
Fixed value: 2: indicates this API specification (B2B, business-to-business).
InvoiceHeader String(2)
Required
- The letter track of the e-invoice
The e-invoice letter track is a 2 uppercase English letters, which is assigned by the the E-invoice Platform of MOF(e.g. KK or KG).
InvoiceStart String(8)
Required
- Starting number of each unit.
An 8-digit numbers, the last 2 should be 00 or 50
(e.g. 10000000 or 10000050).
InvoiceEnd String(8)
Required
- Ending number of each unit.
An 8-digit numbers, the last 2 should be 49 or 99
(e.g. 10000049 or 10000090).
Example
{
"MerchantID": "2000132",
"InvoiceTerm": "1",
"InvoiceYear": "109",
"InvType": "07",
"InvoiceCategory": "4",
"InvoiceHeader": "TW",
"InvoiceStart": "10000000",
"InvoiceEnd": "10000049"
}
Response format
- Content Type ：application/json
- HTTP Method ：POST
Response by ECPay (Json format)
PlatformID String(10)
MerchantID String(10)
RpHeader
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
- Please save this data in order to activate the letter track number.
Example
{
"RtnCode": 1,
"RtnMsg": "成功",
"TrackID": "1234567890"
}