消息文档

更新时间：2023/09/11 访问次数：432

一、消息接入
二、消息类目

一、消息接入

1.1 接入说明

消息服务是跨境分销开放平台为提高效率而推出的一种主动推送服务，推送内容包括账号授权、商品、订单、逆向等消息。基于该推送服务，应用获取分销数据不再需要轮询API，只需要在消息对应的业务数据发生变化时开放平台会主动推送业务内容给分销商，分销商仅需提前订阅该消息并可对该消息内容做解析。需要注意的点，由于消息无法保证有序性，部分消息需要在搭配OpenAPI 查询接口做数据同步。消息接入可以有效降低API的调用频率，降低系统压力。

1.2 订阅步骤

位置：开放平台应用控制台-应用详情-消息服务

步骤：开发者可在开放平台上配置一个回调 URL 来接收消息请求

以开发者身份登入淘宝全球开放平台；
选择 APP console（APP 控制台）；
选择应用列表右侧的 Manage（管理）；
选择 Message service（消息服务）；
填写回调地址，选择 Verify（验证），若返回 HTTP 200 状态码，则会提示验证成功；
从列表中选择需要订阅的消息；
选择 Save（保存）。

1.3 消息格式

消息模板JSON示例

{
  "seller_id": "2100004250000",
  "message_type": 11,
  "data": {
    "mp_id": "2048212708534489",
    "status": "ON"
  },
  "timestamp": 1686646893,
  "site": "taobao_hk"
}

模板字段说明

属性	类型	说明	示例描述
seller_id	String	分销商账号ID	如2100004250000
message_type	Number	消息类型	参考消息类目列表
data	String	具体推送的业务消息数据，json格式，字段说明，参考各个业务消息说明	如{"key1":"value1"}
timestamp	String	消息推送时间	1686646893
site	String	租户站点（可忽略）	taobao_hk

1.4 机制说明

回调地址

描述：开发者需提供消息接收通道，接收推送形式为 HTTPS POST 请求。

使用消息服务，需要准备一个接收消息的回调接口，请严格按以下要求执行：

请使用 HTTPS 协议的回调地址；
请使用 CA 签发的证书，需要 OV/EV 级；
收到消息后请返回 HTTP 200 状态码，确认签收消息。

重试及补偿

超过 200ms 服务端未收到 200 确认，服务端则认为消息推送失败；
失败后消息会在半个小时后重试推送，最大重试 12 次；
若系统中断超过 12 次重试，则请通过相关查询接口重新获取数据。

消息签名

描述：数据將使用明文传输，为安全起见，开放平台会对消息体做摘要签名处理，签名结果会放在POST请求头的

Authorization字段中，签名算法如下：

#请求签名参数
Base = "{your_app_key}" + "{message_body_you_receieved}"
Secret = "{your_app_Secret}"
#签名算法
HMAC-SHA256
#生成签名
Authorization = HEX_ENCODE(HMAC-SHA256(Base, Secret));

Java签名代码参考：

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
public class SignatureUtil {
    private static final String HMAC_SHA256 = "HmacSHA256";
    private static final Logger LOGGER = LoggerFactory.getLogger(SignatureUtil.class);
    /**
     * 产生基于Hmac-SHA256，并经过16进制编码的签名。
     * @param base {AppKey} + {messageBody}
     * @param secret {AppSecret}
     * E.g.: AppKey = 123456, AppSecret = 3412gyo124goi3124
     * 收到的消息体Json ：{"seller_id":"1234567", "message_type":0, "data":{...}..}
     *
     * base = "123456" + "{\"seller_id\":\"1234567\", \"message_type\":0, "data":{...}..}"
     * secret = 3412gyo124goi3124
     * signature = getSignature(base, secret);
     * signature =  f3d2ca947f16a50b577c036adecd18bec126ea19cadedd59816e255d3b6104ab
     * @return 签名
     */
    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) {
            LOGGER.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();
    }
}

消息示例如下：

POST /example/uri HTTP/1.1
#HTTP请求头
Host: www.example.com
Content-Type: application/json
Content-Length: 1238
#开放平台摘要签名
Authorization: 34f7b258df045d4ed9341850ca85b866f34828fd7d51862f11137216294a894c
#HTTP请求Body
{
  "seller_id": "2100004250000", # 分销商ID
  "message_type": 18, # 消息类型
  "data": {
    "mp_id": "2048212708534489", # 供销商品ID
    "action": "BIND" # 操作类型，铺货绑定
  },
  "timestamp": 1686647231, # 推送时间
  "site": "taobao_hk" # 站点，可忽略
}

1.5 处理建议

在收到消息之后，验证签名防止外部攻击，签名方法参考1.3，签名时切勿对原始消息体进行相应转换和修改！否则签名比对就会不一致。
由于开放平台有接口响应时间限制（200ms以内），可在收到消息后存储至异步队列进行业务的处理，同时返回 HTTP 200 状态码。

二、消息类目

2.1 商品类消息

旧消息已不再维护，会逐步下线，请订阅新的商品类消息。

通过撞库接口获取到的商品不会收到此类消息。

接口列表：/batch/src/products/check、/product/get、/product/recommend

该消息无法保证开发者收到消息的顺序性，所以请收到该消息后通过“商品详情API”进行反查，再做相关业务处理。

接口列表：/product/details/query

2.1.1 选品铺货消息

消息类型

message_type：18

触发场景

分销商或平台运营，在跨境供销平台铺货/取消铺货。

消息示例

{
  "seller_id": "2100004250000",
  "message_type": 18,
  "data": {
    "mp_id": "2048212708534489",
    "action": "BIND"
  },
  "timestamp": 1686647231,
  "site": "taobao_hk"
}

业务字段说明

属性

类型

说明

示例描述

mp_id

String

供货平台商品ID

如2048196206207634

action

String

操作类型

"BIND"：铺货

"UNBIND"：取消铺货

2.1.2 商品状态变更

消息类型

message_type：11

触发场景

已铺货商品上下架/删除

消息示例

{
  "seller_id": "2100004250000",
  "message_type": 11,
  "data": {
    "mp_id": "2048212708534489",
    "status": "ON"
  },
  "timestamp": 1686646893,
  "site": "taobao_hk"
}

业务字段说明

属性

类型

说明

示例描述

mp_id

String

供销平台商品ID

如2048196206207634

status

String

商品状态

status="ON" 上架(可售)

status="OFF" 下架(不可售)

status="DELETED" 已删除(不可售)

2.1.3 商品信息变更

消息类型

message_type：13

触发场景

已铺货商品信息编辑发布，包含商品标题、详描、商品图片等，会触发此类消息推送。

消息示例

{
  "seller_id": "2100004250000",
  "message_type": 13,
  "data": {
    "mp_id": "2048196206207634",
    "update_fields": [
      "ITEM_IMG"
    ]
  },
  "timestamp": 1686646939,
  "site": "taobao_hk"
}

业务字段说明

属性

类型

说明

示例描述

mp_id

String

供货平台商品ID

如2048196206207634

update_fields

String[]

商品更新的字段列表

"ITEM_TITLE" 商品标题

"ITEM_DESC" 商品详描

"ITEM_IMG" 商品图片

2.1.4 商品价格变更

消息类型

message_type：15

触发场景

已铺货商品价格修改

消息示例

{
  "seller_id": "2100004250000",
  "message_type": 15,
  "data": {
    "mp_id": "2048195498077245",
    "distributor_id": "2100004250000"
  },
  "timestamp": 1686646990,
  "site": "taobao_hk"
}

业务字段说明

属性	类型	说明	示例描述
mp_id	String	供货平台商品ID	如2048196206207634
distributor_id	String	分销商账号ID	"2100004250000"

2.1.5 商品库存变更

消息类型

message_type：16

触发场景

已铺货商品库存发生变化时通知

消息示例

{
    "seller_id": "2100004250000",
    "message_type": 16,
    "data": {
        "mp_id": "2048212708534489",
    },
    "timestamp": 1686647024,
    "site": "taobao_hk"
}

业务字段说明

属性	类型	说明	示例描述
mp_id	String	供货平台商品ID	如2048196206207634

2.1.6 SKU状态变更

消息类型

message_type：14

触发场景

已铺货商品sku 编辑发布，包含sku新增/删除

消息示例

{
  "seller_id": "2100004250000",
  "message_type": 14,
  "data": {
    "mp_id": "2048212708534489",
    "sku_id": "4890015831257",
    "status": "ADDED"
  },
  "timestamp": 1686647153,
  "site": "taobao_hk"
}

业务字段说明

属性	类型	说明	示例描述
mp_id	String	供货平台商品ID	如2048212708534489
sku_id	String	供货平台商品sku_id	"4890015831257"
status	String	操作状态	"ADDED" 增加 "DELETED" 删除

2.1.7 SKU信息变更

消息类型

message_type：17

触发场景

已铺货商品sku编辑发布，包含sku图片或属性备注

消息示例

{
  "seller_id": "2100004250000",
  "message_type": 17,
  "data": {
    "mp_id": "2048212708534489",
    "skus": [
      {
        "sku_id": "4873649155289",
        "update_fields": [
          "SKU_IMG",
          "SKU_ALIAS"
        ]
      },
      {
        "sku_id": "4873649178841",
        "update_fields": [
          "SKU_IMG",
          "SKU_ALIAS"
        ]
      }
    ]
  },
  "timestamp": 1686647187,
  "site": "taobao_hk"
}

业务字段说明

属性

类型

说明

示例描述

mp_id

String

供货平台商品ID

如2048212708534489

skus

Object[]

sku_id: 供货商品skuId

update_fields: sku更新的字段信息

update_fields 字段列表

"SKU_IMG"：SKU图片

"SKU_ALIAS"：SKU属性备注

2.2 交易类消息

该消息无法保证开发者接收的有序性，所以请收到该消息后通过“订单查询接口”进行反查，再做相关业务处理。

接口列表：/purchase/orders/query

2.2.1 订单状态变更

消息类型

message_type：3

触发场景

跨境供销平台采购单状态变更，仅包含订单状态变更推送：待支付、待发货、已发货、已关闭

消息示例

{
  "seller_id": "2100000927014",
  "message_type": 3,
  "data": {
    "business_time": 1650939687564,
    "outer_purchase_id": "FY20220426002",
    "purchase_id": 200002638011,
    "seller_id": 2100000927014,
    "sku_list": [
      {
        "item_id": 600123256363335000,
        "logistic_company_name": "顺丰速运",
        "logistic_number": "SF4548527307631",
        "order_line_no": "1",
        "sku_id": 4808332513272,
        "status": "WAIT_BUYER_CONFIRM_GOODS"
      }
    ],
    "status": "WAIT_SELLER_SEND_GOODS"
  },
  "timestamp": 1650939687,
  "site": "taobao_hk"
}

业务字段说明

属性	类型	说明	示例描述
business_time	Number	状态变更时间	如1650939687564
outer_purchase_id	String	ISV采购单号	FY20220426002
purchase_id	Number	供货平台采购主单ID	200002638011
seller_id	Number	分销商ID	2100000927014
sku_list	Object[]	"item_id": 供货平台商品Id "logistic_company_name": 物流公司名称 "logistic_number": 物流单号 "order_line_no": ISV采购子单号 "sku_id": 供货平台商品sku_id "status": 采购子单状态	子单商品列表
status	String	采购单状态	详情见如下status列表

采购单status的值：

采购单状态	描述
BULIDING	采购单创建中
WAIT_BUYER_P	等待付款
WAIT_SELLER_SEND_GOODS	已付款，待发货
WAIT_BUYER_CONFIRM_GOODS	已付款，已发货
TRADE_CLOSED	交易关闭

2.2.2 订单改价变更

消息类型

message_type：8

触发场景

创建订单，客户联系淘宝卖家进行订单议价改价，商家改价成功，则会同步推送该消息给分销商，需要注意支

付后的订单不支持订单改价。

消息示例

{
  "seller_id": "2100000927014",
  "message_type": 8,
  "data": {
    "features": {},
    "salesOrderId": "500000-GSP2021031415594",
    "salesSellerId": 2100000927014,
    "purchaseMarket": "PANAMA",
    "purchaseOrderId": 200002372069,
    "purchaseOrderPriceDTO": {
      "purchaseCurrency": "CNY",
      "purchaseTotalFee": 1,
      "purchaseProductFee": 1,
      "purchaseShippingFee": 0
    },
    "purchaseOrderLinePriceChangeMessageDTOList": [
      {
        "features": {},
        "salesOrderLineIdList": [
          "1"
        ],
        "purchaseOrderLineId": 200002372070,
        "purchaseOrderItemPriceDTO": {
          "purchaseCurrency": "CNY",
          "purchaseTotalFee": 1,
          "purchaseProductFee": 1,
          "purchaseProductUnitFee": 1,
          "purchaseShippingFee": 0
        },
        "bizFeatures": {}
      }
    ],
    "actionTime": 1647306796326,
    "bizFeatures": {
      "appKey": "500000",
      "orderSource": "taobao",
      "purchase_warehouse_address": "{\"city\":\"广州市\",\"country\":\"中国\",\"detailAddress\":\"落潭镇长腰岭村第三经济合作社长兴工业路3号派亚物流\",\"district\":\"白云区\",\"divisionId\":\"440111108\",\"mobile\":\"18500176747\",\"name\":\"李澳洲\",\"phone\":\"\",\"state\":\"广东省\"}",
      "sellerOrderNumber": "-"
    }
  },
  "timestamp": 1647306796,
  "site": "taobao_hk"
}

业务字段说明

属性	类型	说明	示例描述
salesOrderId	String	ISV采购单号	如“500000-GSP2021031415594”
salesSellerId	Number	分销商ID	2100000927014
purchaseOrderId	Number	供货平台采购主单ID	200002372069
purchaseOrderLineId	Number	供货平台采购子单ID	200002372070

改价注意事项

当创建完后订单，觉得有可能改价的，联系淘宝卖家进行订单改价，支付后的订单不支持订单改价。
有一些商品有业务特定的规则，因此并不是所有的商品都支持改价。
有的订单淘宝关单时间很短(如30分钟)，如果超时未支付，此时在下单的时候系统会进行风控拦截(改价后订单已经关闭了，重新生成了一个新的订单)，此时还需要重新联系淘宝卖家对新的订单进行改价。如果在操作过程中有其它任何问题都可以直接咨询相关技术负责人。

2.3 履约类消息（跨境物流渠道专用）

下单收货地址在国内的无需订阅该类消息

2.3.1 禁限运信息回传消息

消息类型

message_type：19

触发场景

若包裹为禁限运商品类型（如液体、纯电等）将无法正常履约，则会发出禁限运信息消息通知分销商，需要分销商走逆向流程完结此单。

消息示例

{
    "seller_id":"2100000927014",
    "message_type":19,
    "data":{
    "outerPurchaseId":"xxxx",
    "purchaseId":200020416005,
    "purchaseLines":[
    {
        "logisticNumbers":[
            {
            "consignTime":1690968022000,
            "lpNumber":"LP00590951846613",
            "trackingNumber":"4201111192612909900774583257396847"
            }   
        ],
        "purchaseLineId":200020416006,
        "supplyChainServiceOrderIds":[
        {
            "detailErrorCode":"COSMETICS",
            "detailErrorMessage":"化妆品",
            "errorCode":"B-12-10-110",
            "errorMessage":"禁限运拦截",
            "price":{
                "amount":1,
                "currency":"CNY"
            },
            "serviceId":354,
            "serviceName":"###巴拿马物流测试商品-测试请不要拍-2",
            "serviceType":"LOGISTICS",
            "ssoOrderItemId":3459590786750736161,
            "status":"CANCELLED"
        },
        {
            "detailErrorCode":"COSMETICS",
            "detailErrorMessage":"化妆品",
            "errorCode":"B-12-10-110",
            "errorMessage":"禁限运拦截",
            "price":{
                "amount":1,
                "currency":"CNY"
            },
            "serviceId":356,
            "serviceName":"【仓库作业】巴拿马测试请不要拍",
            "serviceType":"QUALITY_INSPECTION",
            "ssoOrderItemId":3459590786751736161,
            "status":"CANCELLED"
        },
        {
            "detailErrorCode":"COSMETICS",
            "detailErrorMessage":"化妆品",
            "errorCode":"B-12-10-110",
            "errorMessage":"禁限运拦截",
            "price":{
                "amount":1,
                "currency":"CNY"
            },
            "serviceId":357,
            "serviceName":"【高级质检】巴拿马测试请不要拍",
            "serviceType":"ADVANCED_QUALITY_INSPECTION",
            "ssoOrderItemId":3459590786752736161,
            "status":"CANCELLED"
        }
    ]
     }
 ],
"sellerId":2100000927014
},
    "timestamp":1693380050,
    "site":"taobao_hk"
}

消息体data字段数据结构明细如下：

属性	类型	说明
sellerId	Number	分销商ID
purchaseId	Number	采购主单id
outerPurchaseId	Number	ISV采购单号
purchaseLines	List<PurchaseLine>	采购子单列表

PurchaseLine结构如下：

属性	类型	说明
purchaseLineId	Number	采购子单号
supplyChainServiceOrderIds	List<SupplyChainServiceOrder>	物流服务订单列表
logisticNumbers	List<PackageInfo>	国际物流编号

SupplyChainServiceOrder结构如下：

属性	类型	说明
ssoOrderItemId	Number	物流服务子订单id
serviceType	String	物流服务类型
status	String	物流服务订单状态
serviceId	Long	服务id
serviceName	String	服务名称
price	Money	价格
errorMessage	String	错误信息
errorCode	String	错误码
detailErrorCode	String	详细错误码
detailErrorMessage	String	详细错误信息

PackageInfo结构如下：

属性	类型	说明
consignTime	Long	发货时间
trackingNumber	String	国际运单号
lpNumber	String	LP单号

2.3.2 国际物流服务二次路由（运单号变更）

消息类型

message_type：20

触发场景

在国际履约过程存在特殊商品会路由到其他可运渠道，此时国际物流单号变更，则会发出二次路由消息通知分销商，分销商需要查询供应链物流订单更新国际物流单号。

消息示例

{
    "seller_id":"2100000927014",
    "message_type":20,
    "data":{
    "outerPurchaseId":"xxxx",
    "purchaseId":200020416005,
    "purchaseLines":[
    {
        "logisticNumbers":[
            {
            "consignTime":1690968022000,
            "lpNumber":"LP00590951846613",
            "trackingNumber":"4201111192612909900774583257396847"
            }   
        ],
        "purchaseLineId":200020416006,
        "supplyChainServiceOrderIds":[
        {
            "price":{
                "amount":1,
                "currency":"CNY"
            },
            "serviceId":354,
            "serviceName":"###巴拿马物流测试商品-测试请不要拍-2",
            "serviceType":"LOGISTICS",
            "ssoOrderItemId":3459590786750736161,
            "status":"WAREHOUSE_OUTBOUND"
        },
        {
            "price":{
                "amount":1,
                "currency":"CNY"
            },
            "serviceId":356,
            "serviceName":"【仓库作业】巴拿马测试请不要拍",
            "serviceType":"QUALITY_INSPECTION",
            "ssoOrderItemId":3459590786751736161,
            "status":"WAREHOUSE_OUTBOUND"
        },
        {
            "price":{
                "amount":1,
                "currency":"CNY"
            },
            "serviceId":357,
            "serviceName":"【高级质检】巴拿马测试请不要拍",
            "serviceType":"ADVANCED_QUALITY_INSPECTION",
            "ssoOrderItemId":3459590786752736161,
            "status":"WAREHOUSE_OUTBOUND"
        }
    ]
     }
 ],
"sellerId":2100000927014
},
    "timestamp":1693380050,
    "site":"taobao_hk"
}

消息体data字段数据结构明细如下：

属性	类型	说明
sellerId	Number	分销商ID
purchaseId	Number	采购主单id
outerPurchaseId	Number	ISV采购单号
purchaseLines	List<PurchaseLine>	采购子单列表

PurchaseLine结构如下：

属性	类型	说明
purchaseLineId	Number	采购子单号
supplyChainServiceOrderIds	List<SupplyChainServiceOrder>	物流服务订单列表
logisticNumbers	List<PackageInfo>	国际物流编号

SupplyChainServiceOrder结构如下：

属性	类型	说明
ssoOrderItemId	Number	物流服务子订单id
serviceType	String	物流服务类型
status	String	物流服务订单状态
serviceId	Long	服务id
serviceName	String	服务名称
price	Money	价格

PackageInfo结构如下：

属性	类型	说明
consignTime	Long	发货时间
trackingNumber	String	国际运单号
lpNumber	String	LP单号

2.4 逆向类消息

该消息无法保证开发者接收的有序性，所以请收到该消息后通过“逆向单详情接口”进行反查，再做相关业务处理。

接口列表：/order/refund/query

2.4.1 逆向单/留言同步消息

消息类型

message_type：9

触发场景

逆向单状态发生变更时，如卖家同意退款/退货等动作，都会触发消息通知分销商，其次留言有新增(卖家留

言)或更新(留言图片覆盖)也会发送留言变更消息给分销商，分销商需要拿到对应消息，做逆向单同步、或留言

同步，保持与供销平台数据一致性。

消息示例

{
  "seller_id": "2100000927014",
  "message_type": 9,
  "data": {
     "sellerId": 2100000927014,
     "messageType": 2, 
     "refundId": 110000312001, 
     "businessTime": 1652266980661, 
     "purchaseOrderId": 2608284132117736161
  },
  "timestamp": 1652266980,
  "site": "taobao_hk"
}

业务字段说明

属性	类型	说明	示例描述
sellerId	Number	分销商ID	2100000927014
messageType	Number	逆向消息类型，区别于"message_type"	1 逆向单同步 2 留言同步
refundId	Number	逆向单ID	110000312001
businessTime	Number	消息发送时间戳	1652266980
purchaseOrderId	Number	淘宝主单ID	2608284132117736161

FAQ

关于此文档暂时还没有FAQ

有用(0) 我要提问

淘宝开放平台

Taobao Global Open Platform

消息文档

一、消息接入

1.1 接入说明

1.2 订阅步骤

1.3 消息格式

1.4 机制说明

1.5 处理建议

二、消息类目

2.1 商品类消息

2.1.1 选品铺货消息

2.1.2 商品状态变更

2.1.3 商品信息变更

2.1.4 商品价格变更

2.1.5 商品库存变更

2.1.6 SKU状态变更

2.1.7 SKU信息变更

2.2 交易类消息

2.2.1 订单状态变更

2.2.2 订单改价变更

2.3 履约类消息（跨境物流渠道专用）

2.3.1 禁限运信息回传消息

2.3.2 国际物流服务二次路由（运单号变更）

2.4 逆向类消息

2.4.1 逆向单/留言同步消息

FAQ