私域订单导入

核心场景 私域订单导入接口说明。

1. 一次最多可以导入100个订单。如果订单之前已经导入过，则会更新订单的关键信息，如订单状态等。
2. 由于不同电商平台对订单的字段定义和描述各有不同，请根据蜂巢导入订单的字段说明，将对应的订单字段值按要求导入。

一. 请求参数

请求URL:

POST https://kf.fw199.com/gateway/wbprinter/trade/import

参数名	类型	说明	示例
appid	String	合作伙伴AppId
trade_list	String	要导入的订单列表json数据
timestamp	String	当前时间戳
sign	String	接口签名	如何计算生成见示例代码

trade_list 请求数据示例

一、主订单字段描述

字段	类型	必填	说明	示例
trade_no	String	是	订单号	3581388577432263461x
status	String	是	订单状态，1 待付款，2 待发货，3 已发货，4 已完成，5 已取消	2
receiver_name	String	是	收件人明文姓名（明文订单）	hanson
receiver_mobile	String	是	收件人的明文手机号（明文订单）	18817838888
receiver_province_name	String	是	省名称	陕西省
receiver_city_name	String	是	城市名称	汉中市
receiver_distrct_name	String	是	区名称	南郑区
receiver_street_name	String	否	街道名称	汉山街道
receiver_detail_address	String	是/否	明文详细地址	宋园路30弄1号302室古城公寓
exp_ship_time	String	否	预计发货时间	2022-03-22 00:38:39
appointment_ship_time	String	否	预约发货时间	2022-03-22 00:38:39
trade_remark	String	否	卖家备注	老顾客
transit_fee	float64	否	运费，单位元	5
goods_fee	float64	否	订单金额，单位元	10
total_fee	float64	否	支付金额，单位元	15
create_date	String	是	订单创建时间	2022-03-22 00:38:38
seller_nick	String	是	店铺名称或商城名称	XX旗舰店
buyer_message	String	否	买家留言	请检查质量再发
promotion_amount	float64	否	订单优惠总金额	0
update_time	String	是	订单更新时间	2022-03-22 00:38:39
pay_time	String	否	订单付款时间
seller_flag	String	否	卖家旗帜，0灰; 1紫;2青;3绿;4橙;5红	1
trade_source_type	int	是	固定传1	1
op	int	是	平台代码，私域明文订单固定传9
out_trade_no	String	否	外部系统订单号	DD202310250061
pay_way	int	否	付款方式 , 1：现金，2：支付宝，3：微信，4：银行转账 5：电汇 6: 快递代收货款　7：其他	7
pay_status	int	否	收款状态，0：未收，1：部分已收，2：全部已收到	2
buyer_user_id	int	否	买家UserId	2
total_num	int	否	订单的商品总数，子订单商品数量之和	2

二、子订单字段描述

蜂巢字段	类型	必填	说明	示例
order_id	String	是	子订单号
product_id	int64	是	产品Id
product_name	String	是	产品名称
pic_url	String	是	产品图片url
qty	int	是	购买数量
price	float64	是	单价，单位元
sub_total	float64	是	金额，price单价* qty数量
remark	String	否	自行备注
spec	String	否	规格，不同平台格式不同	颜色:黑色;尺码:42
product_code	String	否	外部商品编码
sku_code	String	否	外部sku编码
refund_status	String	是	子订单退款状态，//0/无售后；1/待退款；2/退款中；3/卖家已经同意退款，等待买家退货；4/买家已经退货，等待卖家确认收货；5/卖家拒绝退款；6/退款关闭；7/退款成功	0
pay_amount	float64	否	实付金额
sku_id	int64	否	商品sku_id
tax_rate	float64	否	税率，小数点方式。如6％传0.06 。　默认为0

接口导入订单时，如果报错：　传入的订单格式有误，请检查trade_list的json格式。则核实对上面订单字段的类型，即数字类型的字段，不要加双引号“”，字符串类型才加双引号“”。

三、请求传入订单JSON的示例

下面是请求示例，相关参数根据实际业务修改。

[
  {
    "buyer_message": "尽快发货",
    "create_date": "2025-09-21 20:30:00",
    "goods_fee": 10,
    "op": 9,
    "orders": [
      {
        "order_id": "DD202509100002",
        "pay_amount": 10,
        "pic_url": "https://static.earthmother.cn/upload/product/product__1f016de233c74a8d89638d898e0ca4a4.jpg",
        "price": 10,
        "product_id": 8016,
        "product_name": "遥控器【锦昱】",
        "qty": 1,
        "refund_status": "0",
        "sku_code": "6503035",
        "sku_id": 8016,
        "spec": "YCWA16NCWQ",
        "sub_total": 10
      }
    ],
    "out_trade_no": "DD202509100002",
    "pay_time": "2025-09-22 20:30:00",
    "promotion_amount": 0,
    "receiver_city_name": "上海市",
    "receiver_detail_address": "宋园路30弄1号302室古城公寓",
    "receiver_distrct_name": "长宁区",
    "receiver_mobile": "13699998888",
    "receiver_name": "测试",
    "receiver_province_name": "上海",
    "seller_flag": "0",
    "seller_nick": "东方明珠",
    "status": "2",
    "total_fee": 10,
    "trade_no": "DD202509100002",
    "trade_remark": "明文订单",
    "trade_source_type": 1,
    "transit_fee": 0,
    "update_time": "2025-09-22 20:30:00"
  }
]

二. 请求示例代码

Java

@Test
public void importTrade() throws Exception {
    String trades = "[{\"buyer_message\":\"尽快发货\",\"create_date\":\"2025-09-21 20:30:00\",\"goods_fee\":10,\"op\":9,\"orders\":[{\"order_id\":\"DD202509100002\",\"pay_amount\":10,\"pic_url\":\"https://static.earthmother.cn/upload/product/product__1f016de233c74a8d89638d898e0ca4a4.jpg\",\"price\":10,\"product_id\":8016,\"product_name\":\"遥控器【锦昱】\",\"qty\":1,\"refund_status\":\"0\",\"sku_code\":\"6503035\",\"sku_id\":8016,\"spec\":\"YCWA16NCWQ\",\"sub_total\":10}],\"out_trade_no\":\"DD202509100002\",\"pay_time\":\"2025-09-22 20:30:00\",\"promotion_amount\":0,\"receiver_city_name\":\"上海市\",\"receiver_detail_address\":\"宋园路30弄1号302室古城公寓\",\"receiver_distrct_name\":\"长宁区\",\"receiver_mobile\":\"13699998888\",\"receiver_name\":\"测试\",\"receiver_province_name\":\"上海\",\"seller_flag\":\"0\",\"seller_nick\":\"东方明珠\",\"status\":\"2\",\"total_fee\":10,\"trade_no\":\"DD202509100002\",\"trade_remark\":\"明文订单\",\"trade_source_type\":1,\"transit_fee\":0,\"update_time\":\"2025-09-22 20:30:00\"}]";

    Map<String, String> data = new HashMap<String, String>();
    data.put("appid", Config.AppId);
    data.put("trade_list", trades);
    long timestamp = System.currentTimeMillis() / 1000;
    data.put("timestamp", String.valueOf(timestamp));        // 参数签名
    data.put("sign", Utils.Sign(data, Config.AppSecret));
    doHttpRequest(Config.FCPrinterImportTradeUrl, data);
}

三. 返回结果示例

{"code":0,"message":"ok","data":"导入成功","trace_id":"06ce72de-bc5f-47db-bebf-3bc221675a9d"}

说明： code为0表示成功，非0为失败，message会包含失败原因。