为方便蜂巢开放平台与开发者网站（系统）进行高效的数据对接，蜂巢开放平台建议开发者通过消息通知模式接入，此模式将使日订单在百万级的处理效率大大提高。

1. 消息业务说明

当买家对订单进行付款后，将推送买家已付款（即待卖家发货）的消息通知开发者。目前的消息事件有：

消息topic 消息说明 第三方系统订单状态变更 第三方系统退款状态变更
tb_push_wait_seller_send_trade 买家已付款 ，即等待卖家发货 在第三方系统首次收到此订单。
tb_push_success_trade 买家已确认收货，即交易成功 订单状态改为：TRADE_FINISHED（交易成功 ）
tb_tradememo_modified_with_trade 交易备注修改消息 ，附带订单信息，可设置推送规则。 未设置规则，默认推送。
tb_refund_refundcreated 订单退款创建消息 退款状态改为：WAIT_SELLER_AGREE(买家已经申请退款，等待卖家同意) 。
tb_refund_refundclosed 订单退款关闭消息 退款状态改为：CLOSED(退款关闭)
tb_refund_refundsuccess 订单退款成功消息 退款状态改为： SUCCESS(退款成功)。
tb_fuwu_seller_orderpaid 卖家订购智能发货服务
tb_trade_tradesellership 卖家发货消息 订单状态改为： WAIT_BUYER_CONFIRM_GOODS(等待买家确认收货,即:卖家已发货);
tb_push_paid_trade_with_buyermessage 根据买家留言推送待发货订单， 可设置推送规则，未设置规则，默认不推送 在第三方系统首次收到此订单。
tb_push_close_trade 订单关闭消息，比如卖家同意退款后或是买家超时未付款等可能导致订单被关闭 订单状态改为：TRADE_CLOSED(付款以后用户退款成功，交易自动关闭);
tb_push_trade_address_changed 淘宝修改交易收货地址消息
tb_refund_buyer_return_goods 淘宝买家退货给卖家消息 退款状态改为：WAIT_SELLER_CONFIRM_GOODS（买家已经退货，等待卖家确认收货）。
tb_refund_buyer_modify_agreement 淘宝买家修改退款协议消息
tb_refund_seller_refuse_agreement 淘宝卖家拒绝退款协议消息 退款状态改为：SELLER_REFUSE_BUYER（卖家拒绝退款）
tb_refund_seller_agree_agreement 淘宝卖家同意退款协议消息 退款状态改为：WAIT_BUYER_RETURN_GOODS（卖家已经同意退款，等待买家退货）
tb_alibaba_invoice_apply 淘宝电子发票开票申请消息
tb_fenxiao_fxorderpaid 淘宝采购单付款消息
taobao_refund_TaobaoIntervened 淘宝介入退款消息
taobao_refund_TaobaoInterApplied 申请淘宝介入消息
taobao_refund_RefundCreateMessage 发表退款留言消息

说明：

  1. 如果第三方系统只是简要的更新订单状态或订单退款状态，根据消息事件中的tid（主订单号）,oid(子订单号）可参照上表中罗列的订单状态或退款状态更新。
  2. 如果想全面、完整的订单状态或退款状态，根据消息事件中的tid（主订单号）可用调用“获取订单详情”获取，（推荐）。
  3. 退款的详细内容，比如买家上传的图片或是内容，可调用“获取单笔退款详情”接口获取相关信息。

订单交易状态(status)

  1. TRADE_NO_CREATE_PAY(没有创建支付宝交易)
  2. WAIT_BUYER_PAY(等待买家付款)
  3. SELLER_CONSIGNED_PART(卖家部分发货)
  4. WAIT_SELLER_SEND_GOODS(等待卖家发货,即:买家已付款)
  5. WAIT_BUYER_CONFIRM_GOODS(等待买家确认收货,即:卖家已发货)
  6. TRADE_BUYER_SIGNED(买家已签收,货到付款专用)
  7. TRADE_FINISHED(交易成功)
  8. TRADE_CLOSED(交易关闭， 付款以后用户退款成功，交易自动关闭)
  9. TRADE_CLOSED_BY_TAOBAO(交易关闭，付款以前，卖家或买家主动关闭交易)
  10. PAY_PENDING(国际信用卡支付付款确认中)
  11. WAIT_PRE_AUTH_CONFIRM(0元购合约中)
  12. PAID_FORBID_CONSIGN(拼团中订单或者发货强管控的订单，已付款但禁止发货)

订单退款状态(refund_status)

  1. WAIT_SELLER_AGREE(买家已经申请退款，等待卖家同意)

  2. WAIT_BUYER_RETURN_GOODS(卖家已经同意退款，等待买家退货)

  3. WAIT_SELLER_CONFIRM_GOODS(买家已经退货，等待卖家确认收货)

  4. SELLER_REFUSE_BUYER(卖家拒绝退款)

  5. CLOSED(退款关闭)

  6. SUCCESS(退款成功)

  7. NO_REFUND（无退款），订单退款状态的初始状态。

​

注意：上表不同的消息topic是不同的权限接口，需要开通后才有。

1.1 等待卖家发货消息通知

当买家在淘宝上进行订单付款后，开发者的WebSocket客户端将收到订单的相关信息：

{
    "uuid": "20201010221640251138", // 消息标识
    "code": 0,    // 成功为0，非0为失败
    "msg": "success",  // 如果code非0时，msg有具体的出错原因
    "topic": "tb_push_wait_seller_send_trade", // 消息类型
    "data":  {

    "trade_source": "taobao", // 订单来源，taobao表示淘宝,pdd表示拼多多
    "seller_nick": "我是卖家",//  淘宝或pdd的商家账号
     "oaid": "1h12M4LqkhUkt1ibEk6VyZv2gRsECYSQayzH33CwBP1s3CmkVyx1m4SItNJ6ZhgUibyzr9RA",
    "tid": 1379298204916565830,  // 订单号
    "buyer_nick": "我是买家",  // 买家昵称
    "buyer_message": "",  // 买家留言
    "adjust_fee": "0.00", // 卖家手工调整金额，精确到2位小数
    "buyer_email": "abc@163.com",
    "receiver_state": "上海",
    "receiver_city": "上海市",
    "receiver_district": "浦东新区",
    "receiver_town": "陆家嘴街道",
    "receiver_address": "陆家嘴街道东方路2200号215室",
    "receiver_name": "李先生",
    "receiver_mobile": "13816157211",
    "alipay_no": "2020112022001164275735283081",
    "receiver_zip": "200120", // 邮编
    "price": "5.00", //商品价格
    "discount_fee": "0.00", // 优惠金额
    "total_fee": "5.00",  // 商品金额（商品价格乘以数量的总金额）
    "payment": "5.00", // 实付金额
    "post_fee": "0.00", // 邮费
    "pay_time": "2020-11-20 12:17:38", //付款时间
    "created": "2020-11-20 12:17:33",  //订单创建时间
    "status": "WAIT_SELLER_SEND_GOODS", // 订单状态
    "seller_memo": "",  // 卖家备注
    "seller_flag": 0,  // 卖家旗帜
    "pic_path": "https://img.alicdn.com/bao/uploaded/i2/661153176/TB23bWverBmpuFjSZFuXXaG_XXa_!!661153176.jpg",
    "orders": [
        {
            "num_iid": 544876335798,
            "title": "联华超市提取货券xx",
            "price": "5.00",  //商品价格 
            "num": 1, // 购买数量
            "payment": "5.00", //  实付金额
            "outer_iid": "lianhua007",  // 商家外部编码(可与商家外部系统对接)
            "outer_sku_id": "white36", //外部网店自己定义的Sku编号
            "pic_path": "https://img.alicdn.com/bao/uploaded/i2/661153176/TB23bWverBmpuFjSZFuXXaG_XXa_!!661153176.jpg",
            "refund_status": "NO_REFUND", // 退款状态
            "sku_properties_name": "尺码:36;颜色:white", // SKU的值
            "discount_fee": "0.00", // 优惠金额
            "adjust_fee": "0.00"  // 卖家手工调整金额，
            "divide_order_fee": "87.00",  // 分摊之后的实付金额
            "part_mjz_discount": "3.00" , //优惠分摊
             "oid":1915261095690565830 // 子订单订单号
        }
    ]
}
}

注意：上述data字段值虽为json，但是为字符串json，注意转化。

如您的业务场景需要订单的其他字段，可联系客服。

1.2 买家已确认收货消息通知

当买家对订单进行确认收货时，开发者的WeboSocket客户端将收到确认订单的相关信息：

{
    "uuid": "20201010221641200726", // 消息标识
    "code": 0,    // 成功为0，非0为失败
    "msg": "success",  // 如果code非0时，msg有具体的出错原因
    "topic": "tb_push_success_trade",  // 消息类型， tb_push_success_trade表示交易成功
    "data": {
        "buyer_nick": "汉武帝",
        "payment": "2.00", // 订单金额
        "oid": 2289822115844565832, // 如果只有一个子订单的话，子订单号oid与主订单tid一样。
        "tid": 2289822115844565832,
        "seller_nick": "王的店"
    }
}

1.3 卖家修改订单备注消息

当卖家在淘宝后台修改订单备注时， 将订单备注的内容推送给开发者。卖家可以设置根据“旗帜和备注内容”进行规则设置 ，实现只有符合特定旗帜和备注中包含特定内容的订单，才推送给开发者。注：此推送规则设置由卖家设置，详细设置教程见 订单插旗同步规则设置。

1.3.1 不含订单信息

卖家修改订单旗帜和备注时，将旗帜和备注内容进行推送，推送内容不包含当前订单信息。

{
    "uuid": "28012", // 消息标识
    "code": 0,    // 成功为0，非0为失败
    "msg": "success",  // 如果code非0时，msg有具体的出错原因
    "topic": "tb_tradememo_modified",  // 卖家修改订单备注消息（无订单）
    "data": {
                "seller_flag": 1,  // 交易备注旗帜 , 0(灰色), 1(红色), 2(黄色), 3(绿色), 4(蓝色), 5(粉红色)
                "buyer_nick": "我是买家",  // 买家昵称 
                "iid": 544876335798,   
                "seller_memo": "这个要发礼品", // 卖家备注内容
                "end_time": 1605765213000, 
                "payment": "1.50", // 付款金额
                "oid": 1378795575422565830, // 子订单ID
                "seller_nick": "百鞋馆",  // 卖家账号
                "type": "guarantee_trade",
                "tid": 1378795575422565830, // 订单号
                "status": "WAIT_SELLER_SEND_GOODS" // 当前订单状态
            } 
}

1.3.2 包含订单信息

{
    "uuid": "28013",
    "code": 0,
    "msg": "success",
    "topic": "tb_tradememo_modified_with_trade",
    "data": {
        "trade_info": {  
    "oaid": "1h12M4LqkhUkt1ibEk6VyZv2gRsECYSQayzH33CwBP1s3CmkVyx1m4SItNJ6ZhgUibyzr9RA",
    "trade_source": "taobao", // 订单来源，taobao表示淘宝,pdd表示拼多多
    "seller_nick": "我是卖家",//  淘宝或pdd的商家账号
    "tid": 1379298204916565830,  // 订单号
    "buyer_nick": "我是买家",  // 买家昵称
    "buyer_message": "",  // 买家留言
    "buyer_email": "abc@163.com",
    "receiver_state": "上海",
    "receiver_city": "上海市",
    "receiver_town": "陆家嘴街道",
    "receiver_address": "陆家嘴街道东方路2200号215室",
    "receiver_name": "李先生",
    "receiver_mobile": "13816157211",
    "alipay_no": "2020112022001164275735283081",
    "receiver_zip": "200120", // 邮费
    "price": "5.00", //商品价格
    "discount_fee": "0.00", // 优惠金额
    "total_fee": "5.00",  // 商品金额（商品价格乘以数量的总金额）
    "payment": "5.00", // 实付金额
    "post_fee": "0.00", // 邮费
    "pay_time": "2020-11-20 12:17:38", //付款时间
    "created": "2020-11-20 12:17:33",  //订单创建时间
    "status": "WAIT_SELLER_SEND_GOODS", // 订单状态
    "seller_memo": "",  // 卖家备注
    "seller_flag": 0,  // 卖家旗帜
    "pic_path": "https://img.alicdn.com/bao/uploaded/i2/661153176/TB23bWverBmpuFjSZFuXXaG_XXa_!!661153176.jpg",
    "orders": [
        {
            "num_iid": 544876335798,
            "title": "联华超市提取货券xx",
            "price": "5.00",  //商品价格 
            "num": 1, // 购买数量
            "part_mjz_discount": "", // 优惠分摊 
              "divide_order_fee": "5.00", // 
            "payment": "5.00", //  实付金额
            "outer_iid": "lianhua007",  // 商家外部编码(可与商家外部系统对接)
            "outer_sku_id": "white36", //外部网店自己定义的Sku编号
            "pic_path": "https://img.alicdn.com/bao/uploaded/i2/661153176/TB23bWverBmpuFjSZFuXXaG_XXa_!!661153176.jpg",
            "refund_status": "NO_REFUND", // 退款状态
            "sku_properties_name": "尺码:36;颜色:white", // SKU的值
            "discount_fee": "0.00", // 优惠金额
            "adjust_fee": "0.00"  // 卖家手工调整金额
        }
    ]

        },
        "trade_memo":  "{\"seller_flag\":1,\"buyer_nick\":\"superChina\",\"iid\":544876335798,\"seller_memo\":\"明天再发\",\"end_time\":1628062825000,\"payment\":\"10.00\",\"oid\":1998080425210565830,\"seller_nick\":\"百鞋馆\",\"type\":\"guarantee_trade\",\"tid\":1998080425210565830,\"status\":\"TRADE_FINISHED\"}"
    }
}

1.4 买家发起退款

买家发起订单退款，将推送退款消息，退款的消息主题为tb_refund_refundcreated。

{
    "uuid": "28196",
    "code": 0,
    "msg": "success",
    "topic": "tb_refund_refundcreated",
    "data":  {
        "buyer_nick": "我是买家",
        "refund_phase": "onsale",
        "refund_fee": "1.50",   // 退款金额
        "modified": "2020-11-19 16:09:00",
        "bill_type": "refund_bill",
        "oid": 1378795575422565830, // 子订单号
        "seller_nick": "我是卖家",
        "refund_id": 89898411440563058,
        "tid": 1378795575422565830  // 订单号
    }

}

字段说明：

  1. 退款单类型（bill_type）：refund_bill(退款单)，return_bill(退货单),replace_bill(退换货单) 。
  2. 退款阶段类型（refund_phase）:onsale(售中),aftersale(售后)。aftersale消息是本次新加类型。

1.5 订单退款关闭

如果订单退款关闭，将推送退款关闭消息，退款的消息主题topic为tb_refund_refundclosed。

 {
     "uuid": "82471834",
     "code": 0,
     "msg": "success",
     "topic": "tb_refund_refundclosed",
     "data": "{\"buyer_nick\":\"tb129398830\",\"refund_phase\":\"onsale\",\"refund_fee\":\"40.00\",\"modified\":\"2021-09-15 17:44:02\",\"bill_type\":\"return_bill\",\"oid\":1386630985481191187,\"seller_nick\":\"百鞋馆\",\"refund_id\":88660058082198711,\"tid\":1386630985481191187}"
 }

1.6 订单退款成功

如果订单退款成功，将推送退款成功消息，退款的消息主题topic为tb_refund_refundsuccess。

{
    "uuid": "28210",
    "code": 0,
    "msg": "success",
    "topic": "tb_refund_refundsuccess",
    "data": "{\"buyer_nick\":\"supercode\",\"refund_phase\":\"onsale\",\"refund_fee\":\"1.50\",\"modified\":\"2020-11-19 16:13:45\",\"bill_type\":\"refund_bill\",\"oid\":1316497647520565830,\"seller_nick\":\"百鞋馆\",\"refund_id\":89845812341563058,\"tid\":1316497647520565830}"
}

1.7 卖家服务市场订购成功的消息

卖家在服务市场订购”智能发货“软件后，将卖家订购信息推送给开发者，消息主题topic为tb_fuwu_seller_orderpaid。
在一些场景中，卖家可能会过期再重新订购，也可能会在服务期内再续订。因此用order_cycle_start字段作为服务开始的判断原则。

  1. order_cycle_start 为今天： 表示卖家为刚刚订购（或是过期续订）。
  2. order_cycle_start 大于今天： 表示卖家还在服务期，但是又续订，此时服务的order_cycle_start会在上次服务未到期的时间点再加上本次的订购周期。 
 {
    "uuid": "28282",
    "code": 0,
    "msg": "success",
    "topic": "tb_fuwu_seller_orderpaid",
    "data":   {
        "order_cycle_end": "2021-11-13 00:00:00",   // 订购服务的结束时间
        "order_cycle_start": "2021-10-13 00:00:00", // 订购服务的开始时间
        "create": "2020-11-19 17:01:29" ,   // 订购时间
       "seller_nick": "我是卖家账号"
    }
}

1.8 卖家发货消息

卖家在淘宝后台进行发货或是通过其他API调用发货时，将推送此消息，消息主题topic为：tb_trade_tradesellership。

 {
    "uuid": "29165",
    "code": 0,
    "msg": "success",
    "topic": "tb_trade_tradesellership",
    "data":  {
        "buyer_nick": "我是买家昵称",
        "post_fee": "0.00",
        "iid": 544876335798,
        "end_time": 1605856178000,
        "payment": "1.50",
        "oid": 1330633044245565830,
        "seller_nick": "我是卖家账号",
        "type": "guarantee_trade",
        "tid": 1330633044245565830,
        "status": "WAIT_SELLER_SEND_GOODS"  // 订单状态，此消息为发货动作，因此订单状态为发货前的状态（即待卖家发货）
    }
}

1.9 根据买家留言推送待发货订单

根据买家留言推送待发货订单 ， 消息主题topic为：tb_push_paid_trade_with_buyermessage，推送的消息内容如下：

 {
    "uuid": "26",
    "code": 0,
    "msg": "success",
    "topic": "tb_push_paid_trade_with_buyermessage",
    "data": "{\"adjust_fee\":\"0.00\",\"alipay_no\":\"2021080422001164271406967771\",\"buyer_email\":\"\",\"buyer_message\":\"ABC\",\"buyer_nick\":\"supercode\",\"created\":\"2021-08-04 18:19:24\",\"discount_fee\":\"0.00\",\"oaid\":\"1h12M4LqkhUkt1ibEk6VyZv2gRsECYSQayzH33CwBP1s3CmkVyx1m4SItNJ6ZhgUibyzr9RA\",\"orders\":[{\"adjust_fee\":\"0.00\",\"discount_fee\":\"0.00\",\"divide_order_fee\":\"5.00\",\"num\":1,\"num_iid\":544876335798,\"oid\":2003390138416565830,\"outer_iid\":\"lianhua007\",\"outer_sku_id\":\"red36\",\"part_mjz_discount\":\"\",\"payment\":\"10.00\",\"pic_path\":\"https://img.alicdn.com/bao/uploaded/i2/661153176/TB23bWverBmpuFjSZFuXXaG_XXa_!!661153176.jpg\",\"price\":\"5.00\",\"refund_status\":\"NO_REFUND\",\"sku_properties_name\":\"尺码:36;颜色:red\",\"title\":\"联华超市提取货券xx\"}],\"pay_time\":\"2021-08-04 18:19:29\",\"payment\":\"10.00\",\"pic_path\":\"https://img.alicdn.com/bao/uploaded/i2/661153176/TB23bWverBmpuFjSZFuXXaG_XXa_!!661153176.jpg\",\"post_fee\":\"5.00\",\"price\":\"5.00\",\"receiver_address\":\"陆家嘴街道东方路72号15室\",\"receiver_city\":\"上海市\",\"receiver_district\":\"浦东新区\",\"receiver_mobile\":\"13812778899\",\"receiver_name\":\"李先生\",\"receiver_state\":\"上海\",\"receiver_town\":\"\",\"receiver_zip\":\"200120\",\"seller_flag\":0,\"seller_memo\":\"\",\"seller_nick\":\"百鞋馆\",\"status\":\"WAIT_SELLER_SEND_GOODS\",\"tid\":2003390138416565830,\"total_fee\":\"5.00\",\"trade_source\":\"taobao\",  \"oaid\": \"1h12M4LqkhUkt1ibEk6VyZv2gRsECYSQayzH33CwBP1s3CmkVyx1m4SItNJ6ZhgUibyzr9RA\"}"
}

1.10 订单关闭

订单关闭消息，比如卖家同意退款后或是买家订单超时未付款等原因都可能导致订单关闭， 消息主题topic为：tb_push_close_trade，推送的消息内容如下：

{
    "uuid": "22",
    "code": 0,
    "msg": "success",
    "topic": "tb_push_close_trade",
    "data": "{\"buyer_nick\":\"supercode\",\"post_fee\":\"5.00\",\"iid\":544876335798,\"end_time\":1628070714000,\"payment\":\"10.00\",\"oid\":2003779371056565830,\"seller_nick\":\"百鞋馆\",\"type\":\"guarantee_trade\",\"tid\":2003779371056565830,\"status\":\"TRADE_CLOSED\"}"
}

1.11 淘宝修改交易收货地址消息

当淘宝订单的买家收件地址被修改后，将推送此消息， 消息主题topic为：tb_push_trade_address_changed，推送的消息内容如下：

{
    "uuid": "27",
    "code": 0,
    "msg": "success",
    "topic": "tb_push_trade_address_changed",
    "data": "{\"tid\":2002897981809565830}"
}

具体修改后的新收件地址，可通过订单号tid调用订单详情接口获取最新的订单信息。

1.12 淘宝买家退货给卖家消息

当买家将收到货物退还给卖家时，将推送此消息， 消息主题topic为：tb_refund_buyer_return_goods ，推送的消息内容如下：

{
    "uuid": "50",
    "code": 0,
    "msg": "success",
    "topic": "tb_refund_buyer_return_goods",
    "data": "{\"buyer_nick\":\"supercode\",\"refund_phase\":\"aftersale\",\"refund_fee\":\"10.00\",\"modified\":\"2021-09-03 10:40:01\",\"bill_type\":\"return_bill\",\"oid\":2019061080035565830,\"seller_nick\":\"百鞋馆\",\"refund_id\":127443708623563058,\"tid\":2019061080035565830}"
}

1.13 淘宝买家修改退款协议消息

淘宝买家修改退款协议时，将推送此消息， 消息主题topic为：tb_refund_buyer_modify_agreement ，推送的消息内容如下：

{
    "uuid": "46",
    "code": 0,
    "msg": "success",
    "topic": "tb_refund_buyer_modify_agreement",
    "data": "{\"buyer_nick\":\"supercode\",\"refund_phase\":\"aftersale\",\"refund_fee\":\"10.00\",\"modified\":\"2021-09-03 10:38:00\",\"bill_type\":\"return_bill\",\"oid\":2019061080035565830,\"seller_nick\":\"百鞋馆\",\"refund_id\":127443708623563058,\"tid\":2019061080035565830}"
}

1.14 淘宝卖家拒绝退款协议消息

淘宝卖家拒绝退款时，将推送此消息， 消息主题topic为：tb_refund_seller_refuse_agreement ，推送的消息内容如下：

{
    "uuid": "47",
    "code": 0,
    "msg": "success",
    "topic": "tb_refund_seller_refuse_agreement",
    "data": "{\"buyer_nick\":\"supercode\",\"refund_phase\":\"aftersale\",\"refund_fee\":\"10.00\",\"modified\":\"2021-09-03 10:39:03\",\"bill_type\":\"return_bill\",\"oid\":2019061080035565830,\"seller_nick\":\"百鞋馆\",\"refund_id\":127443708623563058,\"tid\":2019061080035565830}"
}

1.15 淘宝卖家同意退款协议消息

淘宝卖家同意退款协议时，将推送此消息， 消息主题topic为：tb_refund_seller_agree_agreement ，推送的消息内容如下：

{
    "uuid": "49",
    "code": 0,
    "msg": "success",
    "topic": "tb_refund_seller_agree_agreement",
    "data": "{\"buyer_nick\":\"supercode\",\"refund_phase\":\"aftersale\",\"refund_fee\":\"10.00\",\"modified\":\"2021-09-03 10:40:01\",\"bill_type\":\"return_bill\",\"oid\":2019061080035565830,\"seller_nick\":\"百鞋馆\",\"refund_id\":127443708623563058,\"tid\":2019061080035565830}"
}

1.16 淘宝电子发票开票申请消息

淘宝卖家同意退款协议时，将推送此消息， 消息主题topic为：tb_alibaba_invoice_apply ，推送的消息内容如下：

{
    "uuid":"102769072",
    "code":0,
    "msg":"success",
    "topic":"tb_alibaba_invoice_apply",
    "data":"{\"trigger_status\":\"refund_seller_confirm\",\"platform_code\":\"TM\",\"business_type\":\"1\",\"platform_tid\":\"2178155486795837034\",\"apply_id\":\"01vHi5FoMzQYnNfl4Uu2H8xOEsMzW5LYO4B_HZSANhC0Y\",\"seller_nick\":\"申沃旗舰店\"}"
}

data参数说明

字段 类型 说明
apply_id 发票申请ID 基本类型 String
business_type 抬头类型，0=个人，1=企业 String
platform_code 电商平台代码,TB,TM,ALIPAY,JD String
platform_tid 电商平台对应的订单号 String
trigger_status 开票申请的触发类型，buyer_payed=卖家已付款，sent_goods=卖家已发货，buyer_confirm=买家确认收货，refund_seller_confirm=卖家同意退款，invoice_supply=买家申请补开发票，invoice_change=买家申请改抬头，change_paper=电换纸 String
seller_nick 卖家Nick String

收到上述的开票消息后，可以通过开票申请数据获取接口获取具体的开票内容。

1.17 淘宝介入退款消息

触发场景
淘宝介入退款消息, 消息主题为taobao_refund_TaobaoIntervened。
推送的消息如下:

{
    "uuid": "82471834",
    "code": 0,
    "msg": "success",
    "topic": "taobao_refund_TaobaoIntervened",
    "data": "{\"buyer_nick\":\"神的赋予\",\"buyer_open_uid\":\"AAEQ90gYAAjcqSrFKsIZsyxH\",\"refund_phase\":\"aftersale\",\"refund_fee\":\"173.00\",\"modified\":\"2022-10-27 23:38:31\",\"bill_type\":\"return_bill\",\"oid\":2955269737445099601,\"seller_nick\":\"tb601525337\",\"refund_id\":186001777616090196,\"tid\":2955269737444099601}",

}

字段说明见淘宝文档: https://open.taobao.com/tmc.htm?docId=664&docType=9

1.18 申请淘宝介入消息

触发场景
申请淘宝介入消息,消息主题为taobao_refund_TaobaoInterApplied。

推送的消息


{
    "uuid": "82471838",
    "code": 0,
    "msg": "success",
    "topic": "taobao_refund_TaobaoInterApplied",
    "data":   "{\"buyer_nick\":\"tb504668324\",\"buyer_open_uid\":\"AAF790gYAAjcqSjFKsI8J1N2\",\"refund_phase\":\"onsale\",\"refund_fee\":\"88.00\",\"modified\":\"2022-10-27 23:40:39\",\"bill_type\":\"refund_bill\",\"oid\":1712327810380746198,\"seller_nick\":\"tb8114133247\",\"refund_id\":110572321360749861,\"tid\":1712327810380746198}",
}

字段说明见 https://open.taobao.com/tmc.htm?docId=663&docType=9

1.19 发表退款留言消息

触发场景
在退款协议中发表留言 当创建退款时，会同时退款留言所以会产生此消息； 当通过页面修改退款留言时，会产生此消息； 当通过发表退款留言api(taobao.refund.message.add)添加退款消息时，会产生此消息；消息主题为taobao_refund_RefundCreateMessage

推送的消息


 {
    "uuid": "82471839",
    "code": 0,
    "msg": "success",
    "topic": "taobao_refund_RefundCreateMessage",
    "data":  "{
        \"buyer_nick\":\"碎银子\",
        \"buyer_open_uid\":\"AAGq5dEAAeG3JedwSFpZMe1\",
        \"refund_phase\":\"onsale\",
        \"refund_fee\":\"12.32\",
        \"bill_type\":\"refund_bill\",
        \"modified\":\"2000-12-30 12:32:20\",
        \"oid\":\"110770592823138\",
        \"seller_nick\":\"麦包包\",
        \"refund_id\":\"592823138\",
        \"tid\":\"110770592823138\"
    }"

}

字段说明见 https://open.taobao.com/tmc.htm?docId=123&docType=9

2. 技术实现

消息通知采用WebSocket作为通讯协议，多数开发语言如Java、C#、PHP、Node.js等都支持WebSocket，不管使用哪种开发语言，强烈建议WebSocket客户端实现重连机制。下面以Java为例进行说明：

2.1 连接服务器

采用加密的WebSocket协议即WSS连接蜂巢服务器，在连接的URL需要附加AppId和Token

wss://kf.fw199.com/acc?appid=YOUR_APPID&token=YOUR_TOKEN

其中YOUR_APPID为开放平台给开发者的AppId，Token由客户端通过AppID和AppSecret进行MD5加密生成，连接的代码如下：

  private static String serverUrl = "wss://kf.fw199.com/acc";
    private EasyWSClient   webSocketClient = null;
    public void start() {

        try {

              String token = Utils.MD5(Config.AppSecret + Config.AppId + Config.AppSecret);
              String finallyUrl = serverUrl +"?appid=" + Config.AppId + "&token=" + token +"&version=v2.0" +"&clientid=lpclient002";
              webSocketClient = new EasyWSClient(new URI(finallyUrl));
              webSocketClient.connect();

        } catch (Exception ex) {
           ex.printStackTrace();
        }

    }

接入参数说明

参数 含义 备注
appid 开发者Id
token 签名值
version 版本，目前最新为v2.0
clientid 客户端标识 ，开发者可以自定义标识，比如client002。当多个客户端接入时，可以标识不同的客户端。 如果不传入的话，服务端会分配一个标识给当前客户端

2.2 处理消息

当蜂巢服务器下发消息给客户端时，客户端需要及时处理消息，可将消息存放数据库或是利用线程池进行处理消息，尽量避免对对一个消息进行长时间的处理。收的消息，如果包含消息号uuid（即uuid不为空），需要对消息向服务端发送消息确认，切记，否则消费会积压或是重复扣费。

  @Override
    public void onMessageEvent(String message) {
          // 强制建议在业务处理之前将收到的message写到日志文件
          logger.info("收到待发订单，sellerNick:"+ syncTrade.getSellerNick() +",订单号:" +  syncTrade.getTid() );

        SyncTradeResponse syncTradeResponse = JSON.parseObject(message, SyncTradeResponse.class);
        if (syncTradeResponse.getCode() == 0) {

            if (syncTradeResponse.getTopic().equals("tb_push_wait_seller_send_trade")) {
                // 这里处理待发货订单的业务逻辑
                SyncTrade  syncTrade = JSON.parseObject(syncTradeResponse.getData(), SyncTrade.class);

            } else if (syncTradeResponse.getTopic().equals("tb_push_success_trade")) {
                // 这里处理买家确认收货的订单
                SyncSuccessTrade  syncSuccessTrade = JSON.parseObject(syncTradeResponse.getData(), SyncSuccessTrade.class);
                System.out.println("收到买家确认收货订单，sellerNick:"+ syncSuccessTrade.getSellerNick() +",订单号:" +  syncSuccessTrade.getTid());
            }

            //  如果是需要确认的消息，则确认此消息，否则服务端消息将会重发。
            if ( syncTradeResponse.getUuid() != null && !syncTradeResponse.getUuid().equals("")){
                send("{\"cmd\":\"ack_sync_data\", \"seq\":\"" + syncTradeResponse.getUuid() +   "\"}");
            }

        } else {
            System.out.println("服务端返回业务错误："+ syncTradeResponse.getMsg());
        }

        System.out.println("========onMessageEvent=========== \n " + message + "\n" );
    }

警告

开发者一定要考虑消息的重复性，即服务端在特别情况下，可能会推送重复消息，客户端如果已经对订单做过处理，则重复的订单要忽略，避免造成损失！

2.3 心跳机制

客户端需要每隔30秒发送一个心跳指令给服务器，否则长时间无数据会被服务器断开。

  Timer timerBeat = new Timer();
    public  void sendBeat() {

        if (timerBeat != null) { 
            TimerTask beatTask = new TimerTask() {
                @Override
                public void run() {
                    if (ws != null && ws.isOpen()) {
                        ws.send("{\"cmd\":\"beat\"}");
                    }
                }
            };
            timerBeat.schedule(beatTask, new Date(), BEAT_INTERVAL);
        } 

    }

当服务端收到客户端的心跳时，服务端会返回一个心跳确认，内容如下：

{"uuid":"","code":0,"msg":"success","topic":"ack_beat","data":""}

客户端一般不需要对“心跳确认消息”进行处理。

消息通知的Java版完整代码已放在Github上，若您使用其他开发语言，请参考Java代码实现。

2.4 常见问题

  1. 如果我有多家店铺，需要使用多个websocket接入吗？

    一个开发者账号建议用一个websocket接入就可以，不需要使用多个websocket连接， 一个开发者可以处理多家店铺， 比如，如果开发者关联了多家店铺，这多家店铺的订单都会通过websocket推送给开发者，注意：websocket的推送信息中是包含不同店铺的标识seller_nick，即可以区分不同的店铺。

    服务端在2分钟后会再次推送，尝试30次后停止。

  2. 允许多个websocket客户端同时接入吗

一般只用一个websocket客户端接入即可，如果订单量比较大，存在消息堆积时，可以接入多个客户端，加速消息处理。

  1. 多个网站（系统）可以用共一个蜂巢账号吗？

3.1 如果仅是调用接口的话，可以共用一个蜂巢账号。但是如果涉及消息推送就可能会有问题，即多个websocket使用相同的AppId连接进来，服务端只会将某条消息推送给其中一个websocket客户端。 比如，A网站所在的A服务器和B网站所在B服务器，通过websocket连接进蜂巢服务器，蜂巢下发消息时，可能会
发给A服务器，也可能会下发给B服务器， 消息随机发给不同的客户端，影响业务。这种场景，建议另外再申请一个蜂巢开发者账号。
3.2 如果消息量过大，想要并行处理消息， 可以考虑同时连接进来多个websocket（相同的AppId）, 但要注意将每个WebSocket收到的消息，业务处理完成后，都存入同一个数据库。
3.3 系统已经上线了，如何进行测试呢？ 如果将生产环境中收到的json消息数据下载在本地，在本地模拟从蜂巢收到的json消息即可。

  1. 店铺授权了, 但是网站还是看不到订单？

这个问题其实是涉及双方系统同步问题， 蜂巢的订单到第三方网站（系统）有2种方式，这2种方式可以同时配合使用。 第一种是蜂巢主动推送 ，在商家授权都正常情况，推送是实时。 但是推送不会推送历史订单，包括授权过期后，再次授权时，只会对授权后的新订单开始推送。 第二种是第三方网站（系统）主动通过调用订单接口来同步。 这种方式只有商家的淘宝（拼多多）授权未过期，都可以获取历史和当前的最新订单。 针对商家过期再次授权，建议第三方网站通过订单接口来同步，具体的思路一些方法可参考。
a. 在商家授权回调时，进行24小时-48内的订单同步。
b. 在网站增加一个手动同步按钮，由客户自己选时间段，进行订单同步。
c. 同步时，为节约资源和成本，可使用增量订单同步接口。 系统每次同步后记录最后一次的同步时间作为下次同步的开始时间。如果最后一次同步时间过长（比如超72小时以上）可以指定最后一次为24小时前，前面提到具体这些时间节点可根据业务自行决定。
d. 如果商家的近期订购都没有过期， 但还是存在漏单的情况，建议按下面的步骤排查。 1. 确定开通了订单推送服务。 2 . 第三方网站（系统）先在自己侧的推送同步日志里查询是否有收到蜂巢推送的遗漏订单号，如果有收到的话，说明可能没有写到本地数据库里。 如果在日志里没有收到蜂巢推送的订单。 将开发者Id，商家账号，订单号这3个信息告知我们。

  1. 历史订单会推送吗

    不会。只有在商家授权给您后，才会推送新订单。如果需要历史订单，在考虑商家在首次登录或过期后授权再进来时，通过订单列表接口获取历史订单。

  2. 关于订单推送的一些规则
    a. 只有在商家授权给您后，才会推送新订单，见第5点。
    b. 订单插旗（修改备注）推送，只要符合插旗推送规则，就会推送订单，不管当前的订单状态。 即不管订单是退款状态还是已发货状态等。
    c. 建议买家发起退款或卖家发货消息也开启，否则第三方网站的订单看到的都是待发货的订单，即使淘宝里的订单状态是退款中或是卖家已发货。
    d. 第三方的网站应该根据不同的订单消息修改自己网站里的订单状态。 见本文最上面的表格。
    e. 一个订单有可能会重复推送，比如客户端没有发回执给服务端，或是多次进行插旗（修改备注）等等。第三方网站要注意避免生成重复的订单， 如果是已经同步的订单，要更新最新的订单信息到自己的数据库。
    f. 如果是非实时场景，可以使用订单列表接口（增强版），此接口可根据订单的状态、订单日期 、订单旗帜进行实时查询。

  1. 订单有积压如何处理？
    1.收到消息后，可以放队列或数据库里，消息事件里不要处理过长时间的逻辑 2. 在日志文件里增加收到消息的时间，以及发送回执给服务器的时间。 3. 增加多个消息同步客户端实例，增加并发处理速度。
文档更新时间: 2023-04-19 18:16   作者：admin