API文档

# 回调消息

Type 说明
HEART_BEAT 心跳检测
ORDER 订单数据
LIVE_USER_IN_OUT 客户进出直播间
LIVE_USER_BLOCKED 客户拉黑/取消拉黑

# 心跳检测

用于检测第三方回调地址是否能够正常接收请求。

频率: 每10分钟一次。

{
  "timestamp": 1722828600046,
  "msgType": "HEART_BEAT",
  "data": "4b97695a-ac06-4d41-956b-28bd792503f8"
}

# 订单

当用户下单、取消订单、订单超时、支付成功、退款等操作时，将会产生订单数据回调。

频率: 立即。

订单状态:

状态 说明
wait_pay 待支付
paid 已支付
cancel 已取消
timeout 超时未支付
refunded 已退款
wait_shipping 待发货
shipped 已发货
received 已收货

状态机:

订单状态

  • 用户下单后，非0元单将被标识为 "待支付(wait_pay)"，0元虚拟商品订单将直接被标识为 "已支付(paid)"，0元实物商品将被直接标识为 "待发货(wait_shipping)"。
  • "待支付(wait_pay)" 订单若被用户取消，将被标识为 "已取消(cancel)"。已取消订单不会再被改为其它状态。
  • "待支付(wait_pay)" 订单在【30分钟内】未付款，将被标识为 "超时未支付(timeout)"。
  • "待支付(wait_pay)" 订单在【30分钟内】付款，虚拟商品将被标识为 "已支付(paid)"，实物商品将被标识为 "待发货(wait_shipping)"。
  • "已支付(paid)" "待发货(wait_shipping)" 订单若退款，会被标识为 "已退款(refunded)"。
  • "待发货(wait_shipping)" 订单发货后被标识为 "已发货(shipped)"。
  • "已发货(shipped)" 订单被用户确认收货或系统自动收货后，被标识为 "已收货(received)"。

支付状态:

状态 说明
wait_pay 待支付
paid 已支付
refunded 已退款

支付渠道

枚举值 说明
1 微信扫码支付
2 微信APP支付
3 微信手机网站支付
4 微信公众号支付
5 微信小程序支付
6 微信当面付
7 支付宝当面付-扫码支付
8 支付宝APP支付
9 支付宝手机网站支付
10 支付宝电脑网站支付
11 线下现金支付
12 线下POS机刷卡
13 线下企微收款码
14 线下结余支付

消息结构:

{
  "timestamp": 1722827262571,
  "msgType": "ORDER",
  "data": {
    "orderNo": "24080511074233306655",   // 订单号(唯一键)
    "status": "wait_shipping",           // 订单状态
    "createTime": 1722827262280,         // 下单时间
    "customerNum": "GCbuT1LVwO",         // 客户编号
    "customerName": "123****1165",       // 客户姓名
    "customerMobile": "12345678912",     // 客户手机号
    "customerNickname": "吃葡萄不吐葡萄皮", // 微信昵称
    "customerAvatar": "http://wx.qlogo.cn/mmhead/Q3auHgzwzM5wvMrJOOSicHVw74cVKGR3qAO8Tj5vM28k1b6O3dibRuHQ/0",
    "customerUnionId": "odzSQxCW8AMAucrHXsWYw-amJoqg", // 客户微信UnionID
    "originPrice": 0,    // 原始金额，单位毫（10000倍，1分钱=100毫）
    "discountPrice": 0,  // 优惠金额，优惠了多少钱。单位毫
    "shouldPayPrice": 0, // 应付金额，单位毫
    "paidPrice": 0,      // 已支付金额，单位毫
    "refundPrice": 0,    // 已退款金额，单位毫
    "shippingPrice": 0,  // 运费，单位毫
    "skuList": [ // 商品列表
      {
        "skuId": "202407241416209086", // 商品号(唯一键)
        "skuName": "测试免费商品",       // 商品名称
        "thumbImg": "https://duanxunbao-test.oss-cn-beijing.aliyuncs.com/1/2024-07-24/46cbb240-4984-11ef-bc76-432e1f940901.jpg", // 商品封面图地址
        "skuCount": 1,                 // 购买数量
        "originPrice": 0,              // 商品价格，单位毫
        "isVirtual": false,            // 是否虚拟商品。false 表示实物商品
        "outSkuId": ""                 // 商品外部编码。第三方系统的商品编号，可在添加、编辑商品时设置。
      }
    ],
    "payRecordList": [ // 支付信息
      {
        "num" : "FKK30sqE97", // 唯一编号
        "payNo": "zf2akyc535e1etvwvvd0424082700006",   // 短训宝系统产生的支付单号，唯一。
        "transaction": "4200002407202408106625233436", // 微信/支付宝支付流水号
        "payStatus" : "paid", // 支付状态
        "payPrice": 10000,    // 支付金额，实际金额放大10000倍。 
        "payTime" : 1724760685000, // 支付时间，精确到毫秒
        "payChannel" : 4,     // 支付渠道 3-微信网站扫码 4-微信公众号支付 9-支付宝网站扫码
        "payChannelDesc" : "微信公众号支付", // 支付渠道描述
        "payServiceCode": "weixin", // 支付服务代码: weixin,alipay
        "createTime": 1724760670000 // 创建时间，精确到毫秒
      }
    ],
    "couponInfos": [
      {
        "couponId": "FKK30sqE9K",  // 优惠券编号
        "couponName": "满减券",   //  优惠券名称
        "couponDiscount": 0,   //优惠券优惠金额
      }
    ],
    "userId": "Fcs6aVzi19", // 成单人ID
    "liveId": "Fcs6aVziee", // 直播间ID
    "roomId": "20239871987312" // 百家云直播间ID
  }
}

注意: orderNo 和 skuId 都是短训宝系统内的唯一键。若需要对接第三方系统中的商品编号，请在商品管理功能中设置 "商品外部编码" 后再通过 "outSkuId" 字段进行映射。

外部商品编码

# 客户进出直播间事件

当用户进入直播间时产生数据。

频率: 每分钟回调一次，一次最多100条数据。1分钟内超出100人进出直播间的，将由下一批回调数据推送。

{
    "timestamp": 1722827400041,
    "msgType": "LIVE_USER_IN_OUT",// 客户进入直播间事件
    "data": [
      {
        "event": "user_in", // 事件类型。user_in 客户进入直播间。user_out 客户退出直播间。
        "eventTime": 1722827400041, // 事件时间
        "liveId": "Lc2G1ox0sY",// 直播间id
        "liveTitle": "直播间名称",
        "userNumber": "122",// 直播间用户id
        "customerNum": "xxx",// 
        "name": "直播间用户名",
        "avatar": "https://xxxxxxxx",// 直播间用户头像
        "openId": "xxxx", // 客户的openId
        "unionId": "xxxx", // 客户的微信unionId
        "mobile": "xxxx", // 客户手机号
        "weworkContactId": "", // 企微客户ID
        "inviteUserId": "K8y5xA0Ox1", // 邀请人id。邀请客户进入直播间的员工id
        "dxbs": "L_q92XlaPes5", // 短训宝与第三方系统打通参数
        "corpId": "ww12344", //企微商户id
        "bizNum": "xxxx", //商户id
        "weworkUserList":[  //添加过weworkContactId为好友的企微成员列表
           {
                  "weworkUserId": "xxxxx", //企微id
                  "weworkUserName": "xxx" //企微名称
            }
        ],
        "inviteUserBindWeworkUserList":[//邀请人绑定的企微成员列表
            {
                  "weworkUserId": "xxxxx", //企微id
                  "weworkUserName": "xxx" //企微名称
            }
        ]
     }
  ]
}

# 客户进出回放事件

当用户进入回放时产生数据。

频率: 每分钟回调一次。

{
    "timestamp": 1643024243268,
    "msgType": "LIVE_PLAYBACK_USER_IN_OUT",// 客户进入直播间事件
    "data": [
      {
      	"event": "in", // 事件类型。in 客户进入直播间。out 客户退出直播间。
      	"eventTime": 1643024243268, // 事件时间
        "msgId": "24121956012476_288_1735108425655_in", // 消息唯一id
      	"liveId": "Lc2G1ox0sY",// 直播间id
        "roomId": "24121956012476", // 直播间房间号
        "liveTitle": "直播间名称",
        "userNumber": "122",// 直播间用户id
        "customerNum": "xxx",//
      	"openId": "xxxx", // 客户的openId
      	"unionId": "xxxx", // 客户的微信unionId
        "mobile": "xxxx", // 客户手机号
        "weworkContactId": "", // 企微客户ID
      	"inviteUserId": "K8y5xA0Ox1", // 邀请人id。邀请客户进入直播间的员工id
      	"dxbs": "L_q92XlaPes5", // 短训宝与第三方系统打通参数
        "fid": "500058422",
        "guid": "282376CDA63CAB546C8F8BDF755E4F5E",
        "sessionId": "0"
     }
  ]
}

# 客户领取使用优惠券事件

当用户领取或使用优惠券时产生数据。

频率: 实时。

{
    "timestamp": 1643024243268,
    "msgType": "COUPON_USER_GET_USE",// 用户领取或使用优惠券
    "data": [
      {
        "event": "get", // 事件类型。get 客户领取。use 客户使用优惠券。
        "eventTime": 1643024243268, // 事件时间
        "couponCustomerId": 1,// 学员优惠券ID
        "couponId": 1,// 优惠券ID
        "couponName": "xxx",// 优惠券名称
        "couponType": 1,// 优惠卷类型 1商品 2核销
        "type": 1,// 优惠类型 1满减卷 2现金券 3折扣卷 4核销卷
        "customerNum": "xxx",// 客户编码
        "unionId": "xxxx", // 客户的微信unionId
        "mobile": "xxxx", // 客户手机号
        "orderNo": "xxxx", // 使用订单号
      }
  ]
}

# 命中单场直播关键词用户信息，及命中的关键词消息

当用户命中单场直播关键词产生数据。

{
    "timestamp": 1643024243268,
    "msgType": "LIVE_HIT_KEYWORD",// 命中单场直播关键词事件
    "data": [
      {
        "liveId": "xxxx",
        "roomId": "38488484894993",
        "userNumber": "122",// 直播间用户ID
        "name": "直播间用户名",
        "avatar": "https://xxxxxxxx",// 直播间用户头像
        "unionId": "xxxx", // 客户的微信unionId  可能为空
        "mobile": "xxxx", // 客户手机号   可能为空
        "msgContent": "xxxx",   // 发送消息内容
        "msgTime": "2025-01-21 18:49:38",   // 发送时间
        "hitKeyword": "xxxxx"
     }
  ]
}

# 直播间预约的用户

当C端用户预约直播间产生数据。

{
    "timestamp": 1643024243268,
    "msgType": "LIVE_BOOK_CUSTOMER",// 预约直播间事件
    "data": [
      {
        "liveId": "xxxx",
        "roomId": "38488484894993",
        "userNumber": "122",// 直播间用户ID
        "name": "直播间用户名",
        "avatar": "https://xxxxxxxx",// 直播间用户头像
        "unionId": "xxxx", // 客户的微信unionId  可能为空
        "mobile": "xxxx", // 客户手机号   可能为空
     }
  ]
}

# 员工绑定企微回调

当员工绑定企微后产生数据。

{
    "timestamp": 1643024243268,
    "msgType": "USER_BIND_WEWORK_USER",// 用户绑定企微事件
    "data": {
        "id": "123abc", //用户id
        "corpId": "ww12344", //企微商户id
        "bizNum": "xxxx", //商户id
        "list": [
            {
                "weworkUserId": "xxxxx", //企微id
                "weworkUserName": "xxx" //企微名称
            }
        ]
    }
}

# 客户拉黑/取消拉黑事件

当直播间信令收到拉黑或取消拉黑事件时产生数据。

频率: 实时。

{
    "timestamp": 1721000000000,
    "msgType": "LIVE_USER_BLOCKED",// 客户拉黑/取消拉黑事件
    "data": {
        "event": "blocked", // 事件类型。blocked 拉黑。unblocked 取消拉黑（单个）。unblocked_all 取消拉黑（全部）
        "eventTime": 1721000000000, // 事件时间
        "liveId": "xxxx", // 直播间id
        "roomId": "xxxx", // 百家云房间id
        "liveTitle": "xxx公开课", // 直播间名称
        "userNumber": "xxxx", // 直播间用户id。event为unblocked_all时为空
        "customerNum": "HbXuqPHv8h", // 客户编号。event为unblocked_all时为空
        "name": "张三", // 客户用户名
        "mobile": "138****0000", // 客户手机号
        "unionId": "xxxx" // 客户的微信unionId
    }
}

←