Application Scenarios
This API provides the function of searching for an e-invoice that has been cancelled (invalidated)
API URLs:
- Stage: https://einvoice-stage.ecpay.com.tw/B2CInvoice/GetInvalid
- Production: https://einvoice.ecpay.com.tw/B2CInvoice/GetInvalid
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 do AES encryption
MerchantID String(10)
Required
RelateNumber String(30)
Required
- Unique ID of the e-invoice which is defined by the merchant itself.
- Fix length: 30
Special notes : special characters are not acceptable.
InvoiceNo String(10)
Required
- Number of e-invoice
- Fix length: 10
InvoiceDate String(10)
Required
- Date of e-invoice created
- The format: yyyy-MM-dd
Example
{
"MerchantID": 2000132,
"RelateNumber": "123456789",
"InvoiceNo": "UV11100016",
"InvoiceDate": "2018-10-28"
}
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.
ChannelPartner String(1)
1:Shopee
IIS_Mer_ID String(10)
merchant ID
II_Date String(20)
- Invalidation Time
- Format is “yyyy-MM-dd HH:mm:ss”
II_Upload_Status String(1)
- Upload status
- 1: Upload complete
0: Not yet uploaded
II_Upload_Date String(20)
- Upload time
- Format is “yyyy-MM-dd HH:mm:ss”
Reason String(20)
- Invalidation Reason
- Will be output in the form of URL Encode coding
- The parameter shall be exempted when calculating the check digit
II_Seller_Identifier String(10)
Seller Tax ID
II_Buyer_Identifier String(10)
- Buyer Tax ID
- 0000000000 implies that there is no Tax ID
Example
{
"RtnCode": 1,
"RtnMsg": "查詢成功,
"ChannelPartner": "",
"IIS_Mer_ID": "2000132",
"II_Invoice_No": "UV11100018",
"II_Date": "2019-09-17 20:00:50",
"II_Upload_Status": "0",
"II_Upload_Date": "",
"Reason": "Invalid_Reason",
"II_Seller_Identifier": "11456006",
"II_Buyer_Identifier": "0000000000"
}
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 Query Invalid Invoice Details API
version: 1.0.0
servers:
- url: https://einvoice-stage.ecpay.com.tw
description: Testing Environment
- url: https://einvoice.ecpay.com.tw
description: Production Environment
paths:
/B2CInvoice/GetInvalid:
post:
summary: Query Invalid Invoice Details
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- MerchantID
- RqHeader
- Data
properties:
PlatformID:
type: string
maxLength: 10
description: Platform ID for partnered platforms
MerchantID:
type: string
maxLength: 10
description: Merchant ID
RqHeader:
type: object
required:
- Timestamp
properties:
Timestamp:
type: integer
description: Unix timestamp (GMT+8)
Data:
type: string
description: Encrypted data containing request details
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
properties:
PlatformID:
type: string
maxLength: 10
description: Platform ID for partnered platforms
MerchantID:
type: string
maxLength: 10
description: Merchant ID
RpHeader:
type: object
properties:
Timestamp:
type: integer
description: Unix timestamp (GMT+8)
TransCode:
type: integer
description: Transmission code
TransMsg:
type: string
maxLength: 200
description: Transmission message
Data:
type: string
description: Encrypted data containing response details
components:
schemas:
requestBody.Data:
type: object
required:
- MerchantID
- RelateNumber
- InvoiceNo
- InvoiceDate
properties:
MerchantID:
type: string
maxLength: 10
description: Merchant ID
RelateNumber:
type: string
maxLength: 30
description: Merchant-defined unique number
InvoiceNo:
type: string
maxLength: 10
description: Invoice number
InvoiceDate:
type: string
description: Invoice issue date in 'yyyy-MM-dd' or 'yyyy/MM/dd' format
responses.Data:
type: object
properties:
RtnCode:
type: integer
description: Response code
RtnMsg:
type: string
maxLength: 200
description: Response message
ChannelPartner:
type: string
maxLength: 1
description: Channel partner ID
IIS_Mer_ID:
type: string
maxLength: 10
description: Merchant ID
II_Invoice_No:
type: string
maxLength: 10
description: Invoice number
II_Date:
type: string
description: Invalid date in 'yyyy-MM-dd HH:mm:ss' format
II_Upload_Status:
type: string
maxLength: 1
description: Upload status
II_Upload_Date:
type: string
description: Upload date in 'yyyy-MM-dd HH:mm:ss' format
Reason:
type: string
maxLength: 20
description: Invalid reason
II_Seller_Identifier:
type: string
maxLength: 10
description: Seller identifier
II_Buyer_Identifier:
type: string
maxLength: 10
description: Buyer identifier