API Doc

# 5.Food Order Query Interface

# Brief Description

  • Brand parties can actively obtain order data through this interface, supporting time range queries and incremental order queries
  • Suitable for scenarios where order callback push fails or active order data retrieval is needed

# Interface Description

Feature Description
Time Range Query Supports querying order data by order creation time range
Incremental Order Query Query all new orders after a specified order number or receipt number as the starting point
Paginated Return When there are multiple records, returns are paginated with 15 records per page by default

# HTTP Request Information

# Request Method

  • POST

# Request URL

  • {domain}/open-api/order/list

# Request Header

Parameter Name Required Type Description
Content-Type Yes string application/json

# Request Body Parameters

Parameter Name Required Type Length Limit Example Description
param Yes string - - Parameter body
sign Yes string - 45eebd745dcf0b5f6d6f9fcde28cd9fe8116a892 Signature
storeKey Yes string - - Restaurant key
appId Yes string - - APPID

# param Parameters

Parameter Name Required Type Length Limit Example Description
startTime Conditionally required* string - 2024-01-01 00:00:00 Order creation start time, format: yyyy-MM-dd HH:mm:ss. Required for time range query
endTime Conditionally required* string - 2024-01-01 23:59:59 Order creation end time, format: yyyy-MM-dd HH:mm:ss. Required for time range query
orderInnerNo Conditionally required* string - CCP20220428011068111 Starting order number, query all new orders after this order. Required for incremental query by order number
receiptNo Conditionally required* string - INV202401010001 Starting receipt number, query all new orders after the order corresponding to this receipt. Required for incremental query by receipt number
pageNum No Integer - 1 Page number, starts from 1, defaults to 1 if not provided
pageSize No Integer - 15 Records per page, defaults to 15 if not provided, maximum 100

Query Rules:

  • Time Range Query: Pass startTime and endTime
  • Incremental Query by Order Number: Pass orderInnerNo
  • Incremental Query by Receipt Number: Pass receiptNo

# Response Parameters

Parameter Name Type Example Description
code int 10000 Status code Refer to list
message string success Status code information
data object - Order data

# data Parameter Description

Parameter Name Type Description
total Integer Total number of records
pageNum Integer Current page number
pageSize Integer Records per page
list Array Order list

# list Parameter Description

Parameter Name Required Type Length Limit Example Description
orderInnerNo Yes string - CCP20220428011068111 Order No
restaurantNo Yes string - dasddasd Restaurant No
branchIdentifier Yes string - dasddasd Third-party store identifier
orderSerialNumber Yes Integer - - Order serial number
channelCode No string - - Payment channel code
channelName No string - - Payment channel name
payProductType No Integer - - Payment product type: 0-Offline 1-PaymentLink 2-BillPayment 3-BankTransfer 4-QrStatic 5-QrDynamic 6-Cpm 7-Balance
discountAmount No Integer - - Merchant discount amount
fee No Integer - - Online payment handling fee
serviceFee No Integer - - Service fee
packageFee No Integer - - Packaging fee
deliveryFee No Integer - - Delivery fee
merchantDeliveryFee No Integer - - merchant Delivery Fee
realAmount Yes Integer - - Actual payment amount
totalAmount No Integer - - Total amount
orderStatus Yes Integer - - Order status 1-Pending acceptance 2-Accepted 3-Completed 4-Cancelled
paymentStatus Yes Integer - - Payment status 1-Unpaid 2-Paid 3-Payment failed 4-Refunding 5-Refunded 6-Refund pending 7-Refund failed 8-Cancel refund
customerNum No Integer - Number of diners
createTime Yes String - Order creation time Format: yyyy-MM-dd HH:mm:ss
completeTime No String - Order completion time Format: yyyy-MM-dd HH:mm:ss
paymentTime Yes String - Payment time Format: yyyy-MM-dd HH:mm:ss
refundTime No String - Refund time Format: yyyy-MM-dd HH:mm:ss
discountType No Integer - Discount type 1-pwd 2-Merchant custom discount 3-pwd discount-per person 4-sc discount-entire order 5-sc discount-per person 6-Coupon
receiptNo No string - 00000000000012 Invoice No
refundReceiptNo No string - 00000000000012 Refund invoice No
skuList Yes list - 1 Order dish data
remark No string - Remarks Remarks
lessVat No Integer - - Special discount tax-free amount
surcharge No Integer - - Surcharge

# skuList Parameter Description

Parameter Name Required Type Length Limit Example Description
categoryNo Yes string - Category no Category no
categoryName No string - Category name Category name
productNo Yes string - Dish no Dish no
productName No string - Dish name Dish name
variant Yes int - 1 Whether multiple specifications 1. Yes 2. No
skuNo No string - no SKU code
skuName Yes string - name SKU name
count Yes integer - 1 User purchase quantity
price Yes integer - 100 Dish amount (Unit: cent)
optionAmount Yes integer - 10 Option additional amount
optionList No list - - Option collection

# optionList Parameter Description

Parameter Name Required Type Length Limit Example Description
optionNo No string - no option no
optionName No string - mingcheng option name
optionItemList No list - - option item details

# optionItemList Parameter Description

Parameter Name Required Type Length Limit Example Description
optionItemNo No string - no option item no
optionItemName No list - item name option item name
price No integer - 100 Price (Unit: cent)

# Time Range Query - Request Example

{
  "appId": "123456",
   "storeKey": "12332",
  "sign": "abcdef",
  "param": "{\"startTime\":\"2024-01-01 00:00:00\",\"endTime\":\"2024-01-01 23:59:59\",\"pageNum\":1,\"pageSize\":15}"
}

# Incremental Query by Order Number - Request Example

{
  "appId": "123456",
  "restaurantKey": "12332",
  "sign": "abcdef",
  "param": "{\"orderInnerNo\":\"CCP20220428011068111\",\"restaurantNo\":\"dasddasd\",\"pageNum\":1,\"pageSize\":15}"
}

# Incremental Query by Receipt Number - Request Example

{
  "appId": "123456",
  "restaurantKey": "12332",
  "sign": "abcdef",
  "param": "{\"receiptNo\":\"INV202401010001\",\"restaurantNo\":\"dasddasd\",\"pageNum\":1,\"pageSize\":15}"
}

# Response Example

# code Refer to this list

# Successful Response Example (Time Range Query)

{
  "code": 10000,
  "message": "success",
  "data": {
    "total": 45,
    "pageNum": 1,
    "pageSize": 15,
    "list": [
      {
        "orderInnerNo": "CCP20220428011068111",
        "restaurantNo": "dasddasd",
        "branchIdentifier": "dasddasd",
        "orderSerialNumber": 1001,
        "discountAmount": 100,
        "fee": 50,
        "serviceFee": 30,
        "packageFee": 20,
        "deliveryFee": 0,
        "realAmount": 10000,
        "totalAmount": 10200,
        "orderStatus": 3,
        "paymentStatus": 2,
        "customerNum": 4,
        "createTime": "2024-01-01 12:00:00",
        "completeTime": "2024-01-01 13:00:00",
        "paymentTime": "2024-01-01 12:05:00",
        "refundTime": null,
        "discountType": 1,
        "receiptNo": "INV202401010001",
        "skuList": [
          {
            "categoryNo": "cat001",
            "categoryName": "Sichuan Cuisine",
            "productNo": "prod001",
            "productName": "Kung Pao Chicken",
            "variant": 1,
            "skuNo": "sku001",
            "skuName": "Large",
            "count": 2,
            "price": 3800,
            "optionAmount": 0,
            "optionList": []
          }
        ],
         "remark": "No spice",
         "lessVat": 100,
         "surcharge": 50
      }
    ]
  }
}

# Successful Response Example (Incremental Query by Order Number/Receipt Number)

{
  "code": 10000,
  "message": "success",
  "data": {
    "total": 38,
    "pageNum": 1,
    "pageSize": 15,
    "list": [
      {
        "orderInnerNo": "CCP20220428011068112",
        "restaurantNo": "dasddasd",
        "branchIdentifier": "dasddasd",
        "orderSerialNumber": 1002,
        "discountAmount": 0,
        "fee": 50,
        "serviceFee": 30,
        "packageFee": 20,
        "deliveryFee": 0,
        "realAmount": 8500,
        "totalAmount": 8600,
        "orderStatus": 3,
        "paymentStatus": 2,
        "customerNum": 2,
        "createTime": "2024-01-01 13:30:00",
        "completeTime": "2024-01-01 14:15:00",
        "paymentTime": "2024-01-01 13:35:00",
        "refundTime": null,
        "discountType": null,
        "receiptNo": "INV202401010002",
        "skuList": [
          {
            "categoryNo": "cat002",
            "categoryName": "Hunan Cuisine",
            "productNo": "prod002",
            "productName": "Yu-Shiang Shredded Pork",
            "variant": 2,
            "skuNo": "sku002",
            "skuName": "Standard",
            "count": 1,
            "price": 3200,
            "optionAmount": 0,
            "optionList": []
          }
        ],
        "remark": ""
      },
      {
        "orderInnerNo": "CCP20220428011068113",
        "restaurantNo": "dasddasd",
        "branchIdentifier": "dasddasd",
        "orderSerialNumber": 1003,
        "discountAmount": 200,
        "fee": 50,
        "serviceFee": 30,
        "packageFee": 40,
        "deliveryFee": 500,
        "realAmount": 15200,
        "totalAmount": 16020,
        "orderStatus": 3,
        "paymentStatus": 2,
        "customerNum": 6,
        "createTime": "2024-01-01 14:00:00",
        "completeTime": "2024-01-01 15:10:00",
        "paymentTime": "2024-01-01 14:05:00",
        "refundTime": null,
        "discountType": 2,
        "receiptNo": "INV202401010003",
        "skuList": [
          {
            "categoryNo": "cat001",
            "categoryName": "Sichuan Cuisine",
            "productNo": "prod001",
            "productName": "Kung Pao Chicken",
            "variant": 1,
            "skuNo": "sku001",
            "skuName": "Large",
            "count": 1,
            "price": 3800,
            "optionAmount": 0,
            "optionList": []
          },
          {
            "categoryNo": "cat003",
            "categoryName": "Cantonese Cuisine",
            "productNo": "prod003",
            "productName": "Braised Pork Ribs",
            "variant": 1,
            "skuNo": "sku003",
            "skuName": "Large",
            "count": 2,
            "price": 5800,
            "optionAmount": 200,
            "optionList": [
              {
                "optionNo": "opt001",
                "optionName": "Flavor",
                "optionItemList": [
                  {
                    "optionItemNo": "item001",
                    "optionItemName": "Mild Spicy",
                    "price": 200
                  }
                ]
              }
            ]
          }
        ],
         "remark": "Less salt",
         "lessVat": 200,
         "surcharge": 80
      }
    ]
  }
}

# Response Example

# Code Refer to this list

# Response Parameters

Parameter Name Type Example Description
code int 10000 Status Code Refer to List
message string success Status Code Information
data boolean - Successful Or Not
{
  "code": 10000,
  "message": "success",
  "data": true
}

# Failed Response Example

{
  "code": 21000,
  "message": "Service error, please contact administrator",
  "data": null
}

# Notes

  1. Query Frequency Limit: It is recommended that the query interval be no less than 10 seconds to avoid frequent requests
  2. Time Range Limit: A single time range query should not exceed 30 days
  3. Pagination Recommendation: It is recommended to query all paginated data in order to avoid missing orders
  4. Data Timeliness: Order data may have a delay of up to 5 minutes
  5. Signature Verification: All requests must be signature-verified to ensure data security
  6. HTTPS: It is recommended to use HTTPS protocol to ensure data transmission security
  7. Log Recording: It is recommended to record logs of all query requests to facilitate troubleshooting
  8. Incremental Query Description: When querying by order number or receipt number, the specified order number is used as the starting point, and all new orders generated after it are returned, sorted by creation time in ascending order, supporting pagination. If there are no new orders, an empty list is returned

# Usage Scenarios

  1. Order Callback Push Failure: When order callback push fails 4 times, order data can be actively obtained through this interface
  2. Data Reconciliation: Regularly query order data by time range for reconciliation with the merchant system
  3. Incremental Synchronization: Brand parties record the last processed order number or receipt number, and periodically obtain subsequent new orders through incremental queries to maintain data synchronization
  4. Historical Data Synchronization: Batch query historical order data by time range

← 6.Food Order Push Interface →