消息通知（打单发货结果）｜WebSocket / HTTP 推送

核心场景 蜂巢打单发货结果回调通知，便于第三方业务系统同步订单与物流单号。

在蜂巢打单中完成「发货」操作后，蜂巢消息服务会把发货结果（成功或失败）推送给开发者。第三方系统可据此更新自有系统中的订单状态，并在失败时按失败原因继续处理。

接收消息前，请先开通对应消息权限。

推送方式

支持以下两种推送方式，按业务需要二选一（也可咨询客服协助配置）：

推送方式	说明	配置方式
WebSocket	开发者客户端长连接接收消息，实时性好，适合已有 WebSocket 接入能力的系统	使用 AppId + Token 连接消息服务，详见订单消息通知 / WebSocket 接入
HTTP	蜂巢主动向您提供的 HTTPS 回调地址 POST 推送消息	请将回调 URL 提供给蜂巢客服，由客服在后台为您的开发者账号完成配置与启用

HTTP 推送说明

请提供可公网访问的 HTTPS 回调地址给客服。
客服配置并启用后，发货结果将以 HTTP POST（JSON）推送到该地址。
您的接口在成功接收并处理后，请返回：

{"code":0,"message":"success"}

若返回非 0 或超时/网络失败，蜂巢会按重试策略再次推送。

消息列表

消息 topic	说明
`fc_print_trade_print_finish`	蜂巢打单电子面单打印完成，并执行了发货操作后触发

发货可能成功，也可能失败。无论成功或失败，都会推送本消息；失败时 data.message 中包含失败原因，可按关键字匹配后做后续处理。

消息详情：蜂巢打单电子面单打印完成

topic：fc_print_trade_print_finish
产生条件：在蜂巢打单系统中点击发货完成时产生

一、成功示例（WebSocket）

{
  "uuid": "CNK+ChAAGAAgAA==",
  "code": 0,
  "msg": "success",
  "topic": "fc_print_trade_print_finish",
  "data": "{\"logistics_code\":\"SF\",\"logistics_name\":\"顺丰快递\",\"logistics_no\":\"SF3270428903757\",\"message\":\"成功\",\"op\":9,\"orders\":[{\"order_id\":\"DO202511071126162748211\",\"qty\":12}],\"out_trade_no\":\"DO20251107112616274821\",\"seller_nick\":\"全渠道店铺\",\"status\":1,\"tid\":\"DO20251107112616274821\"}"
}

data 字段为 JSON 字符串，解析后结构示意如下：

{
  "logistics_code": "SF",
  "logistics_name": "顺丰快递",
  "logistics_no": "SF3270428903757",
  "message": "成功",
  "op": 9,
  "orders": [
    {
      "order_id": "DO202511071126162748211",
      "qty": 12
    }
  ],
  "out_trade_no": "DO20251107112616274821",
  "seller_nick": "全渠道店铺",
  "status": 1,
  "tid": "DO20251107112616274821"
}

二、失败示例（WebSocket）

{
  "uuid": "CNK+ChAAGAAgAA==",
  "code": 0,
  "msg": "success",
  "topic": "fc_print_trade_print_finish",
  "data": "{\"logistics_code\":\"ZJS\",\"logistics_name\":\"宅急送\",\"logistics_no\":\"ZJS000383452882\",\"message\":\"订单[3912560886642498520]发货失败,订单状态为[已收货]，不是待发货状态。\",\"op\":6,\"seller_nick\":\"b2b-1624961198\",\"status\":0,\"tid\":\"3912560886642498520\",\"orders\":[{\"order_id\":\"DO202511071126162748211\",\"qty\":12}]}"
}

三、HTTP 推送示例

HTTP 推送的业务字段与 WebSocket 一致；外层通常还会带 sign 等签名字段，示例如下：

{
  "uuid": "",
  "code": 0,
  "sign": "32E6A1F31E67DF9F2CE37101AA072B80",
  "topic": "fc_print_trade_print_finish",
  "msg": "success",
  "data": "{\"logistics_code\":\"SF\",\"logistics_name\":\"顺丰快递\",\"logistics_no\":\"SF3270428903757\",\"message\":\"成功\",\"op\":9,\"orders\":[{\"order_id\":\"DO202511071126162748211\",\"qty\":12}],\"out_trade_no\":\"DO20251107112616274821\",\"seller_nick\":\"全渠道店铺\",\"status\":1,\"tid\":\"DO20251107112616274821\"}"
}

data 参数说明

参数名	类型	说明
op	int	电商平台编码：1 淘宝，2 拼多多，3 抖店 OMS，5 京东，6 1688，8 快手
logistics_code	String	快递公司代码
logistics_name	String	快递公司名称
logistics_no	String	物流单号；多个单号（如子母单）用英文逗号分隔，第一个为母单号
out_trade_no	String	导入订单时传入的自有系统订单号，原样返回
seller_nick	String	电商平台商家账号
tid	String	电商平台订单号（导入时的 `trade_no`）；若拆单，会在原单号后追加 `-x`
orders	集合	商品明细列表
orders.order_id	String	子订单明细标识（导入时的 `order_id`），原样返回
orders.qty	int	商品明细数量
status	int	调用电商平台发货是否成功：0 失败，1 成功
message	String	发货失败时的失败原因；成功时一般为「成功」

常见失败原因（message）

data.message 可能有多种文案，常见例如：

该物流公司揽收或派送范围不支持
订单[3912560886642498520]发货失败,订单状态为[已收货]，不是待发货状态
当前订单[291066544547]不符合用户行为[1]规则,详情请看文档 https://joyspace.jd.com/pages/oCLTiHpIQphOqPV4crgK
业务服务错误,订单已退款

如需精确定位，建议按失败原因中的关键字匹配后处理。