Preparation Operations / Setting Letter Track

Application Scenarios

Before issuing the e-invoice, merchants can call this API to set or add an 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 contains a letter track and a serial number of 8 digits. The numbers, which range between InvoiceStart and InvoiceEnd, can 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/B2CInvoice/AddInvoiceWordSetting
Production: https://einvoice.ecpay.com.tw/B2CInvoice/AddInvoiceWordSetting

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 more than 10 minutes after the timestamp sent by merchants, this request will fail. Reference information is as follows：http://www.epochconverter.com/。
Merchants are advised to frequently synchronize their server time to the nearest time zone server.

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 first 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. The following lists the values representing 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 110^th 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: 1: indicates this API specification (B2C, business-to-customer).

ProductServiceId String(10)

The ID of Product-Service Types
This parameter must consist of English letters (A-Z, a-z) and numbers (0-9), and its length must be between 1 and 10 characters.
This parameter will only be processed when the internal backend switch is enabled; otherwise, this parameter will be ignored. To enable this feature, please contact your account representative.

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)
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
Respond with 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 first and then perform 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 indicating 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"
}

YAML

The provided YAML file is used to define the configuration, structure, operations, and infrastructure management information of the API, making it easier for developers to understand and use the API.

				
					openapi: 3.1.0
info:
  title: ECPay Track and Allocate Invoice Numbers Setting API
  version: 1.0.0
servers:
  - url: https://einvoice.ecpay.com.tw
    description: Production Environment
  - url: https://einvoice-stage.ecpay.com.tw
    description: Testing Environment
paths:
  /B2CInvoice/AddInvoiceWordSetting:
    post:
      summary: Track and Allocate Invoice Numbers Setting
      description: Set the track and allocate invoice numbers for the specified period.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - MerchantID
                - RqHeader
                - Data
              properties:
                PlatformID:
                  type: string
                  description: Platform identifier (optional)
                MerchantID:
                  type: string
                  description: Merchant identifier
                RqHeader:
                  type: object
                  properties:
                    Timestamp:
                      type: number
                      description: Timestamp of the request
                Data:
                  type: string
                  description: Encrypted data in JSON format
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  PlatformID:
                    type: string
                    description: Platform identifier
                  MerchantID:
                    type: string
                    description: Merchant identifier
                  RpHeader:
                    type: object
                    properties:
                      Timestamp:
                        type: number
                        description: Timestamp of the response
                  TransCode:
                    type: integer
                    description: Transmission code
                  TransMsg:
                    type: string
                    description: Transmission message
                  Data:
                    type: string
                    description: Encrypted data in JSON format
        '400':
          description: Invalid request
        '500':
          description: Server error
components:
  schemas:
    requestBody.Data:
      type: object
      properties:
        MerchantID:
          type: string
          description: Merchant identifier
        InvoiceTerm:
          type: integer
          description: Invoice term
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
        InvoiceYear:
          type: string
          description: Invoice year (in ROC year format)
        InvType:
          type: string
          description: Invoice type
          enum:
            - '07'
            - '08'
        InvoiceCategory:
          type: string
          description: Invoice category
          enum:
            - '1'
        InvoiceHeader:
          type: string
          description: Invoice track
        InvoiceStart:
          type: string
          description: Starting invoice number
        InvoiceEnd:
          type: string
          description: Ending invoice number
    responses.Data:
      type: object
      properties:
        RtnCode:
          type: integer
          description: Response code
        RtnMsg:
          type: string
          description: Response message
        TrackID:
          type: string
          description: Track number ID

Green World