Preparation Operations / Searching Application Results of Letter Track Numbers

Application Scenarios

Before issuing or creating the e-invoice, it is regulated by Taiwanese regulations that every merchant or company should apply for the letter track numbers (in Chinese, it is called “字軌”). Normally, if without value-adding centers, merchants or business corporates should complete many applications to the E-Platform of MOF, including uploading the e-invoice to the E-Platform, applying for the transmission software (i.e. the Turnkey), applying for the certificates…etc. With ECPay as a value-adding center, merchants can authorize to ECPay to handle these cumbersome applications.
When testing the API and if the API call is successful, merchants can see the result of letter track numbers assigned by the E-invoice Platform, which is a list of InvoiceInfo. Following details the data of API request and response.

Special Notes :

If no result in return, possible reasons might be that you have not yet commissioned or authorized to ECPay to do the application for the letter track numbers, or the application is still in the process.

API URLs:

Stage: https://einvoice-stage.ecpay.com.tw/B2CInvoice/GetGovInvoiceWordSetting
Production: https://einvoice.ecpay.com.tw/B2CInvoice/GetGovInvoiceWordSetting

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 110^th year of the Republic Era, so the value should be: “110”.

Example

				
					{
    "MerchantID": "2000132",
    "InvoiceYear": "110"
}

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.
For more details please see errors.

RtnMsg String(200)

Return messages to indicate whether the API is successfully executed or not.

InvoiceInfo Array[Object]

List of the e-invoice numbers in units.

InvoiceTerm Int

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.

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

InvoiceStart String(8)

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)

Ending number of each unit.
An 8-digit numbers, the last 2 should be 49 or 99
(e.g. 10000049 or 10000090).

Special Notes：

Since on ECPay’s Stage there is no real application to the Platform, the InvoiceEnd in response of API request is dummy data only. On ECPay’s Production, InvoiceEnd will be the real data.

Number Int

The unit of e-invoice numbers.
Each unit contains 50 e-invoice numbers, which are assigned by the MOF.

Example

				
					{
    "RtnCode": 1,
    "RtnMsg": "成功",
    "InvoiceInfo": [
      {
        "InvoiceTerm": 1,
        "InvType": "07",
        "InvoiceHeader": "KK",
        "InvoiceStart": "10000000",
        "InvoiceEnd": "10000049",
        "Number": 1
      }
    ]
}

Green World