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.

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.

Message format

messageType: indicates the message type
messageBody: indicates the message body
messagePlatform: Message channel 1：1688 platform
timestamp: Message push time

messageType	messageBody
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.

Message access manual

Access Instructions#

Subscribe Steps#

Message format#

Mechanism description#

Callback address#

Retry and compensation#

Message signature#

Handling Suggestions#