1. Message service access
Xportcn KA client
  • English version
    • API Reference
      • Basics
        • Get user address information
        • Address added and updated
      • Warehouse logistics
        • Please refer to the estimated overseas freight
        • Order overseas freight preview
        • Create international logistics orders
        • Update domestic logistics information
      • KA
        • Interface description flowchart
        • AlibabaProduct
          • AlibabaProductKeywordsQuery
          • AlibabaProductImageQuery
          • AlibabaProductCategory
          • AlibabaProductDetail
          • AlibabaProductFreightEstimateGet
          • AlibabaProductPoolList
        • AlibabaOrderController
          • Order list
          • Order Preview (The preview interface needs to be called before creating an order)
          • Create an order
          • Get order details
        • AfterSale
          • Find the reason for a refund return (to create a refund return)
          • Upload refund receipt
          • Create a refund return request
          • Buyer submits refund information
          • List of logistics companies - All logistics companies
        • TaoProduct
          • TaoBaoProductDetail
          • TaoBaoProductKeywordsQuery
          • TaoBaoProductImageQuery
        • TaoOrder
          • TaoBaoOrderRender
          • TaoBaoOrderCreate
          • TaoBaoOrderList
      • wms
        • Package forecasting
        • package inbound
        • package update
    • Product Documentation
      • Announcement
      • Summarize
      • Beginner's guide
        • Become a developer
        • Obtain the Access Key and Access key
        • Start development
      • API tutorial
        • Development manual
        • Error code
      • Message service access
        • Message access manual
      • Account test
        • 1688 Test account
      • Q&A
        • Merchandise store search screening
  1. Message service access

Message access manual

Access Instructions#

The message service is an active push service launched by the Xport developer platform to improve efficiency, and the push content is currently only open to order-related messages. Based on this push service, the application no longer needs polling API to obtain distribution data, but only needs the open platform to actively push business content to the developer when the business data corresponding to the message changes, and the developer only needs to subscribe to the message in advance and analyze the message content. It should be noted that since the order of messages cannot be guaranteed, some messages need to be synchronized with the OpenAPI query interface. Message access can effectively reduce API call frequency and reduce system pressure.

Subscribe Steps#

Location: Open Platform Application Console - Messaging Service
Steps: Developers can configure a callback URL on the open platform to receive message requests
Login to the Xport Open platform as a developer;
Select the console;
Select the message service;
Enter the callback address and select Verify. If the HTTP 200 status code is returned, the verification is successful.
Select Save.
20260206222456.jpg

Message format#

messageType: indicates the message type
messageBody: indicates the message body
messagePlatform: Message channel 1:1688 platform
timestamp: Message push time
20260206223507.jpg
messageTypemessageBody
ORDER_BUYER_VIEW_BUYER_STATUS{"messageType":"ORDER_BUYER_VIEW_BUYER_STATUS","messageBody":"xxxxxxx","messagePlatform":1,"retryCount":0,"developId":1173655621749179000,"channelType":0,"id":1523989}
For Example :
{
"messageType": "ORDER_BUYER_VIEW_BUYER_STATUS",
"messageBody": "{\"nativeLogistics\":{\"address\":\"凰岗村 凤鸣路117号F1档(0381-26778700469)咚咚国际店菜鸟驿站/不同订单分开发货,不放清单,好好包装\",\"area\":\"白云区\",\"areaCode\":\"440111\",\"city\":\"广州市\",\"contactPerson\":\"(0381-26778700469杨海微)\",\"mobile\":\"13544471959\",\"province\":\"广东省\",\"zip\":\"\",\"townCode\":\"440111014\",\"town\":\"石井街道\"},\"productItems\":[{\"itemAmount\":2698,\"name\":\"分频器高中低三路HiFi高保真音箱家用音响改装升级Crossov分音器\",\"price\":14.2,\"productID\":624317206959,\"productSnapshotUrl\":\"https://trade.1688.com/order/offer_snapshot.htm?order_entry_id=3291146761573134260\",\"quantity\":200,\"refund\":0,\"skuID\":4986335548892,\"status\":\"waitsellersend\",\"subItemID\":3291146761573134260,\"type\":\"common\",\"unit\":\"个\",\"productCargoNumber\":\"三分频\",\"skuInfos\":[{\"name\":\"产品规格\",\"value\":\"338端子款\"}],\"entryDiscount\":0,\"specId\":\"240a1c143046a6783c560b6c1f0981b2\",\"quantityFactor\":1,\"statusStr\":\"等待卖家发货\",\"logisticsStatus\":1,\"gmtCreate\":1773727917000,\"gmtModified\":1773743720000,\"gmtPayExpireTime\":\"2026-03-17 18:49:55\",\"subItemIDString\":\"3291146761573134260\",\"sharePostage\":37}],\"extAttributes\":[],\"baseInfo\":{\"businessType\":\"cb\",\"buyerID\":\"b2b-22183901360425ac43\",\"createTime\":1773727917000,\"id\":3291146761573134260,\"modifyTime\":1773743720000,\"payTime\":1773743720000,\"refund\":0,\"remark\":\"要全新,发货前好好检查好好包装,26778700469\",\"sellerID\":\"b2b-2927532373636ea\",\"shippingFee\":37,\"status\":\"waitsellersend\",\"totalAmount\":2735,\"discount\":0,\"tradeType\":\"50060\",\"refundPayment\":0,\"idOfStr\":\"3291146761573134260\",\"receiverInfo\":{\"toFullName\":\"(0381-26778700469杨海微)\",\"toDivisionCode\":\"440111\",\"toMobile\":\"13544471959\",\"toPost\":\"\",\"toTownCode\":\"440111014\",\"toArea\":\"广东省 广州市 白云区 石井街道 凰岗村 凤鸣路117号F1档(0381-26778700469)咚咚国际店菜鸟驿站/不同订单分开发货,不放清单,好好包装\"},\"buyerLoginId\":\"xportcn\",\"sellerLoginId\":\"美聆电子\",\"sumProductPayment\":2840,\"stepPayAll\":false,\"buyerFeedback\":\"要全新,发货前好好检查好好包装,26778700469\",\"overSeaOrder\":false,\"subBuyerLoginId\":\"xportcn:xdintl114\",\"sellerOrder\":false,\"flowTemplateCode\":\"assureTrade\",\"sellerContact\":{\"phone\":\"86-020-81798080\",\"imInPlatform\":\"美聆电子\",\"name\":\"洪坚\",\"mobile\":\"13332879005\",\"companyName\":\"广州市美聆电子有限公司\",\"shopName\":\"广州市美聆电子有限公司\"},\"newStepOrderList\":[{\"gmtStart\":1773727917000,\"gmtPay\":1773743721000,\"stepNo\":1,\"lastStep\":true,\"stepName\":\"全款交易\",\"activeStatus\":1,\"payStatus\":2,\"logisticsStatus\":1,\"payFee\":2735,\"paidFee\":2735,\"adjustFee\":0,\"discountFee\":142,\"postFee\":37,\"paidPostFee\":37}],\"closeOperateType\":\"\",\"couponFee\":0,\"tradeTypeDesc\":\"担保交易\",\"payChannelList\":[\"网商银行跨境直采\"],\"tradeTypeCode\":\"assureTrade\",\"payTimeout\":432000,\"payTimeoutType\":0,\"payChannelCodeList\":[\"CROSS_BORDER_MYBANK\"]},\"fromEncryptOrder\":false}",
"messagePlatform": 1,
"retryCount": 0,
"developId": 1173655621749179000,
"channelType": 0,
"id": 1523989
}

Mechanism description#

Callback address#

Description: Developers need to provide a message receiving channel, receiving push in the form of HTTPS POST requests.
To use the message service, you need to prepare a callback interface for receiving messages. Perform the following operations:
Use the HTTPS callback address.
After receiving the message, return the HTTP 200 status code to confirm the message signing.
The timeout period is 1000MS.

Retry and compensation#

If the message fails, it will be pushed again half an hour later, with a maximum of 5 retries.
If the system is interrupted for more than five times, obtain data again through related query interfaces.

Message signature#

Description: Data will be transmitted in plain text. For security reasons, the open platform will perform summary signature processing on the message body, and the signature result will be placed in the Authorization field of the POST request header. The signature algorithm is as follows:
#Request signature parameters
Base = "{messageBody}"
Secret = "{AccessSecret}"
#Signature algorithm
HMAC-SHA256
#Generate signature
Authorization = HEX_ENCODE(HMAC-SHA256(Base, Secret));
Java signature code reference:
public static String getSignature(String base, String secret) {
        try {
            Mac sha256Hmac = Mac.getInstance(HMAC_SHA256);
            SecretKeySpec secretKey = new SecretKeySpec(secret.getBytes(), HMAC_SHA256);
            sha256Hmac.init(secretKey);
            return byteArraytoHexString(sha256Hmac.doFinal(base.getBytes()));
        } catch (Exception e) {
            log.error("Failed to generate signature");
        }
        return null;
    }

    /**
     * 十六进制Encode
     *
     * @param bytes
     * @return
     */
    private static String byteArraytoHexString(byte[] bytes) {
        if (bytes == null) {
            return null;
        }
        StringBuilder sb = new StringBuilder();
        String stmp;
        for (byte aByte : bytes) {
            stmp = Integer.toHexString(aByte & 0XFF);
            if (stmp.length() == 1) {
                sb.append('0');
            }
            sb.append(stmp);
        }
        return sb.toString().toLowerCase();
    }

Handling Suggestions#

After receiving the message, verify the signature to prevent external attacks, and do not convert or modify the original message body when signing! Otherwise, signature matching will be inconsistent.
Note: messageBody is a string.
Because the interface response time is limited (within 1000ms), the message can be stored in the asynchronous queue for service processing.
Modified at 2026-03-17 10:45:19
Previous
Error code
Next
Account test
Built with