Query Operation / Batch Query Product Information

Scenario

This API provides a batch query of product status, face value, and other information to confirm whether the product is currently available for ticket issuance.

API URLs

Stage: https://ecticket-stage.ecpay.com.tw/api/Ticket/BatchQueryItemInfo
Production: https://ecticket.ecpay.com.tw/api/Ticket/BatchQueryItemInfo

Message format

Accept：text/html
Content Type：application/json
HTTP Method：POST

Request (JSON format)

PlatformID String(10)

Platform ID

This is used by platform merchants and will be provided by ECPay.
For platform merchants, please populate with [MerchantID].
For general merchants, please set as null.

MerchantID String(10)
Required

Merchant ID (provided by ECPay)

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 and verify the time interval of this API call.

Special Note：

ECPay will verify the timestamp.If ECPay receives the request is more 10 minutes late than the timestamp, the transaction will be failed.
Merchants are suggested to synchronize the time of a computer on client- or server-side to another server or nearest reference time source.
For more details can be seen here; another online tool can be found here.

Data Object
Required

Payload of JSON that has been encrypted.

CheckMacValue String
Required

Checksum

Please refer to the Appendix Checksum Mechanism.

Request Example (JSON format)

				
					{
    "PlatformID": "3002599",
    "MerchantID": "2000132",
    "RqHeader": {
        "Timestamp": 1525168923
    },
    "Data": "…",
    "CheckMacValue": "…"
}

Message payload of Data (JSON format)

Special Note: Please urlencode the JSON string firstly and then do AES encryption.

MerchantID String(10)
Required

Merchant ID (provided by ECPay)

PageNum Int
Required

This API returns a fixed number of 20 data records per request. When the data exceeds 20 records, it needs to be queried in multiple requests to obtain all the data. This parameter can be used to specify the page number of the data to be returned.

For example, when [PageNum]=2, it means that the data on the second page will be returned, and the returned value will obtain the data records 21 to 40 of the goods information.

Special Note:

For the first query, please set the parameter [PageNum]=1, which will return the first page of data and the total number of records [TotalCount]. Based on the returned value of [TotalCount], you can determine how many subsequent API calls are needed.

ItemStatus String(1)
Required

The status of a product listing

0: out of stock
1: on the shelf
2: All

ItemList Object

This is a JSON format string that includes multiple pieces of product number.

ItemNo String(8)

Product number.

Data Example (JSON format)

				
					{
    "MerchantID": "2000132",
    "PageNum":2,
    "ItemStatus": "2",
    "ItemList":[
        {"ItemNo":"XA210005"},
        {"ItemNo":"XA210006"},
        {"ItemNo":"XA210007"},
        {"ItemNo":"XA210008"},
        {"ItemNo":"XA210009"},
        {"ItemNo":"XA210010"}
    ]
}

Response (JSON format)

PlatformID String(10)

Platform ID

MerchantID String(10)

Merchant ID

RpHeader Object

Response header

Timestamp Number

Unix timestamp

TransCode Int

Response codes to indicate whether the payload is successfully accepted.

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

Payload of JSON that has been encrypted.

CheckMacValue String

Checksum

Please refer to the Appendix Checksum Mechanism.

Response Example (JSON format)

				
					{
    "PlatformID": "3002599",
    "MerchantID": "2000132",
    "RpHeader": {
        "Timestamp": 1525169058
    },
    "TransCode": 1,
    "TransMsg": "",
    "Data": "…",
    "CheckMacValue": "…"  
}

Message payload of Data (JSON format)

RtnCode Int

Response codes to indicate whether the API is successfully executed or not.

1: API is successfully executed.
Others: failed.
For more details please see error codes.

RtnMsg String(200)

Response messages.

MerchantID String(10)

Merchant ID

TotalCount Int

The total number of products, which the merchant can use to determine the number of API calls needed.

Example

When the total count [TotalCount]=55, the merchant needs to make three API calls to retrieve all the product information. The [PageNum] values to be used in the API calls are 1, 2, and 3.

In the first API call, the merchant fetches data for page 1, which includes records 1-20.
In the second API call, the merchant fetches data for page 2, which includes records 21-40.
In the third API call, the merchant fetches data for page 3, which includes records 41-55.

Special Note:

If the specified page number exceeds the range of the total number of products, the response will directly indicate that no data is found.

ItemInfoList Object

This is a JSON format string that includes multiple pieces of product information.

ItemNo String(8)

Product number

ItemName String(20)

Product name

TicketType String(1)

Ticket type

1: Pickup voucher
2: Gift voucher

ItemAmount Int

Product face value

ItemStatus String(1)

The status of a product listing

0: out of stock
1: on the shelf

ModifyDate String(14)

The last modification time of this item.The format is: yyyymmdd hh:mm.

InstructionsList Object

This is a JSON format string that includes multiple pieces of ticket usage instruction data.

Message payload of InstructionsList (JSON format)

InstructionsList Object

This is a JSON format string that includes multiple pieces of ticket usage instruction data.

IssueType String(1)

Ticket issuing type.

1: Convenience store ticket
2: Paper ticket
3: Electronic ticket

Description String(100)

Return the ticket usage instructions for the specified ticket type based on the [IssueType].

Data Example(JSON format)

				
					{
    "RtnCode": 1,
    "RtnMsg": "Success",
    "MerchantID":"2000132",
    "TotalCount": 300,
    "ItemInfoList":[
        {
            "ItemNo":"VTMT5062",
            "ItemName":"Holiday meal voucher",
            "TicketType":"1",
            "ItemAmount":1200,
            "ItemStatus":"1",
            "ModifyDate":"20220801 15:30",
            "InstructionsList":[
                {
                    "IssueType":"1",
                    "Description":"Convenience store ticket instruction1"
                },
                {
                    "IssueType":"1",
                    "Description":"Convenience store ticket instruction2"
                },
                {
                    "IssueType":"2",
                    "Description":"Paper ticket instruction1"
                },
                {
                    "IssueType":"2",
                    "Description":"Paper ticket instruction2"
                },
                {
                    "IssueType":"3",
                    "Description":"Electronic ticket instruction1"
                },
                {
                    "IssueType":"3",
                    "Description":"Electronic ticket instruction2"
                }
            ]
        },
        {
            "ItemNo":"VTMT5081",
            "ItemName":"Holiday meal voucher",
            "TicketType":"1",
            "ItemAmount":1200,
            "ItemStatus":"1",
            "ModifyDate":"20220801 15:30",
            "InstructionsList":[
                {
                    "IssueType":"1",
                    "Description":"Convenience store ticket instruction1"
                },
                {
                    "IssueType":"2",
                    "Description":"Paper ticket instruction1"
                },
                {
                    "IssueType":"3",
                    "Description":"Electronic ticket instruction1"
                }
            ]
        }
    ]
}

Green World