Preparation Operations / Searching the State of Letter Track Numbers

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 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’s 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 perform 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”.

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

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)

InvoiceHeader
The e-invoice letter track is 2 uppercase English letters, which are assigned by 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

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
Response 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 perform AES decryption on the Data first 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 indicating whether the API is successfully executed or not.

InvoiceInfo Array[Object]

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

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.

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",
        "ProductServiceId": "A001",
        "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
    }
}

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 Number Inquiry 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/GetInvoiceWordSetting:
    post:
      summary: Track Number Inquiry
      description: Query the status and usage of track numbers.
      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
        InvoiceYear:
          type: string
          description: Invoice year (in ROC year format)
        InvoiceTerm:
          type: integer
          description: Invoice term
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
        UseStatus:
          type: integer
          description: Track number usage status
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
        InvoiceCategory:
          type: integer
          description: Invoice category
          enum:
            - 1
        InvType:
          type: string
          description: Invoice type
          enum:
            - '07'
            - '08'
        InvoiceHeader:
          type: string
          description: Invoice track name
    responses.Data:
      type: object
      properties:
        RtnCode:
          type: integer
          description: Response code
        RtnMsg:
          type: string
          description: Response message
        InvoiceInfo:
          type: array
          items:
            type: object
            properties:
              TrackID:
                type: string
                description: Track number ID
              InvoiceYear:
                type: string
                description: Invoice year (in ROC year format)
              InvoiceTerm:
                type: integer
                description: Invoice term
              InvoiceCategory:
                type: integer
                description: Invoice category
              InvType:
                type: string
                description: Invoice type
              InvoiceHeader:
                type: string
                description: Invoice track name
              InvoiceStart:
                type: string
                description: Starting invoice number
              InvoiceEnd:
                type: string
                description: Ending invoice number
              InvoiceNo:
                type: string
                description: Currently used number
              UseStatus:
                type: integer
                description: Track number usage status

Green World