# 上传合单物流信息

接口应在服务器端调用，详细说明参见服务端API。

# 接口说明

# 接口英文名

uploadCombinedShippingInfo

# 功能描述

调用此接口上传合单物流信息
该接口用于商户接入购物订单业务。商户接入后，可帮助用户查看/管理微信内购物的订单，追踪订单进展、获取售后服务等。用户后续可以从微信「我」-「服务」-「钱包」-「账单」中进入，也可以从支付凭证消息进入账单详情页回溯已购物的订单。
具体业务介绍及完整接入指南可参见购物订单。

# 注意事项

根据指定的订单单号类型，采用不同参数给指定订单上传订单信息，为订单上传物流信息时主单和子单的订单单号类型必须保持和上传订单信息时一致
- 商户侧单号形式（枚举值1），通过下单商户号和商户侧单号确定一笔订单
- 微信支付单号形式（枚举值2），通过微信支付单号确定一笔订单
发货模式根据具体发货情况选择
- 统一发货（枚举值1），一笔订单统一发货，只有一个物流单号，此类型无需再指定包裹中商品
- 分拆发货（枚举值2），一笔订单分拆发货，包括多个物流单号。需指定每个物流单内包含的具体商品。系统使用「上传购物详情」中的“商户侧商品ID”来标识具体商品。
物流公司编码，参见获取运力 id 列表get_delivery_list
上传时间，用于标识请求的先后顺序，如果要更新物流信息，上传时间必须比之前的请求更新，请按照Rfc3399格式填写
必须在支付完成后才能上传物流信息

# 调用方式

# HTTPS 调用


POST https://api.weixin.qq.com/user-order/combine-orders/shippings?access_token=ACCESS_TOKEN

# 第三方调用

调用方式以及出入参和HTTPS相同，仅是调用的token不同
该接口所属的权限集id为：120、121、142
服务商获得其中之一权限集授权后，可通过使用authorizer_access_token代商家进行调用

# 请求参数

属性

类型

必填

说明

access_token

string

是

接口调用凭证，该参数为 URL 参数，非 Body 参数。使用getAccessToken 或者 authorizer_access_token

order_key

object

是

合单订单，需要上传购物详情的合单订单，根据订单类型二选一

属性	类型	必填	说明
order_number_type	number	否	订单单号类型，用于确认需要上传详情的订单
transaction_id	string	否	原支付交易对应的微信订单号
mchid	string	否	支付下单商户的商户号，由微信支付生成并下发。
out_trade_no	string	否	商户系统内部订单号，只能是数字、大小写字母_-*且在同一个商户号下唯一

sub_orders

array<object>

否

子单购物详情

属性

类型

必填

说明

order_key

object

是

需要上传购物详情的子单订单，订单类型与合单订单保持一致

属性	类型	必填	说明
order_number_type	number	否	订单单号类型，用于确认需要上传详情的订单
transaction_id	string	否	原支付交易对应的微信订单号
mchid	string	否	支付下单商户的商户号，由微信支付生成并下发。
out_trade_no	string	否	商户系统内部订单号，只能是数字、大小写字母_-*且在同一个商户号下唯一

delivery_mode

number

是

发货模式，发货模式枚举值：1、UNIFIED_DELIVERY（统一发货）2、SPLIT_DELIVERY（分拆发货）

示例值: UNIFIED_DELIVERY

shipping_list

array<object>

否

子单物流信息列表

多重性: [1, 10]

属性

类型

必填

说明

tracking_no

string

是

物流单号，示例值: 323244567777 字符字节限制: [1, 128]

express_company

string

是

物流公司编码，快递公司ID，参见「查询物流公司编码列表」示例值: DHL 字符字节限制: [1, 128]

item_list

array<object>

否

物流关联的商品列表，当统一发货（单个物流单）时，该项不填；当分拆发货（多个物流单）时，需填入各物流单关联的商品列表多重性: [0, 50]

属性

类型

必填

说明

merchant_item_id

string

否

商户侧商品ID，商户系统内部商品编码，分拆发货模式下为必填，用于标识每笔物流单号内包含的商品，需与「上传购物详情」中传入的商品ID匹配

示例值: 1246464644 字符字节限制: [1, 64]

contact

object

否

联系方式，当发货的物流公司为顺丰时，联系方式为必填，收件人或寄件人联系方式二选一

	属性	类型	必填	说明
	consignor_contact	string	否	寄件人联系方式，寄件人联系方式，采用掩码传输，最后4位数字不能打掩码示例值: 189**1234, 021-1234, 1234, 02-*1234, 02-**23-10, 123-8008 值限制: 0 ≤ value ≤ 1024 字段加密: 使用APIv3定义的方式加密**
	receiver_contact	string	否	收件人联系方式，收件人联系方式为，采用掩码传输，最后4位数字不能打掩码示例值: 1891234, 021-**1234, 1234, 02-1234, 02-***23-10, **123-8008 值限制: 0 ≤ value ≤ 1024 字段加密: 使用APIv3定义的方式加密

upload_time

string

否

上传时间，用于标识请求的先后顺序

示例值: 2021-05-20T13:29:35.120+08:00

payer

object

否

支付者，支付者信息

	属性	类型	必填	说明
	openid	string	是	用户标识，用户在商户appid下的唯一标识。下单前需获取到用户的Openid 示例值: oUpF8uMuAJO_M2pxb1Q9zNjWeS6o 字符字节限制: [1, 128]

# 返回参数

属性	类型	说明
errcode	number	错误码
errmsg	string	错误原因

# 调用示例

示例说明: JS Fetch API

# 请求数据示例


// 拼装URL
let url = `https://api.weixin.qq.com/user-order/combine-orders/shippings`;


// Json包体
let jsonBody = {};
jsonBody["order_key"] = {
   "order_number_type": "WXPAY_TRADE_NUMBER",
   "transaction_id": "o9a3q",
   "mchid": "bpgux",
   "out_trade_no": "tktyq"
};
jsonBody["sub_orders"] = [
   {
      "order_key": {
         "order_number_type": "MERCHANT_TRADE_NUMBER",
         "transaction_id": "6r6m0",
         "mchid": "kzwri",
         "out_trade_no": "v1rsd"
      },
      "delivery_mode": "SPLIT_DELIVERY",
      "shipping_list": [
         {
            "tracking_no": "323244567777",
            "express_company": "DHL",
            "item_list": [
               {
                  "merchant_item_id": "1246464644"
               },
               {
                  "merchant_item_id": "1246464644"
               }
            ],
            "contact": {
               "consignor_contact": "****1234",
               "receiver_contact": "189****1234"
            }
         },
         {
            "tracking_no": "323244567777",
            "express_company": "DHL",
            "item_list": [
               {
                  "merchant_item_id": "1246464644"
               },
               {
                  "merchant_item_id": "1246464644"
               }
            ],
            "contact": {
               "consignor_contact": "****1234",
               "receiver_contact": "0**2-******23-10"
            }
         }
      ]
   },
   {
      "order_key": {
         "order_number_type": "MERCHANT_TRADE_NUMBER",
         "transaction_id": "2m08y",
         "mchid": "fr2db",
         "out_trade_no": "m2dok"
      },
      "delivery_mode": "UNIFIED_DELIVERY",
      "shipping_list": [
         {
            "tracking_no": "323244567777",
            "express_company": "DHL",
            "item_list": [
               {
                  "merchant_item_id": "1246464644"
               },
               {
                  "merchant_item_id": "1246464644"
               }
            ],
            "contact": {
               "consignor_contact": "0**2-***1234",
               "receiver_contact": "****123-8008"
            }
         },
         {
            "tracking_no": "323244567777",
            "express_company": "DHL",
            "item_list": [
               {
                  "merchant_item_id": "1246464644"
               },
               {
                  "merchant_item_id": "1246464644"
               },
               {
                  "merchant_item_id": "1246464644"
               }
            ],
            "contact": {
               "consignor_contact": "0**2-***1234",
               "receiver_contact": "189****1234"
            }
         }
      ]
   },
   {
      "order_key": {
         "order_number_type": "MERCHANT_TRADE_NUMBER",
         "transaction_id": "dxy5d",
         "mchid": "w5acd",
         "out_trade_no": "tqbik"
      },
      "delivery_mode": "UNIFIED_DELIVERY",
      "shipping_list": [
         {
            "tracking_no": "323244567777",
            "express_company": "DHL",
            "item_list": [
               {
                  "merchant_item_id": "1246464644"
               },
               {
                  "merchant_item_id": "1246464644"
               }
            ],
            "contact": {
               "consignor_contact": "****123-8008",
               "receiver_contact": "****1234"
            }
         },
         {
            "tracking_no": "323244567777",
            "express_company": "DHL",
            "item_list": [
               {
                  "merchant_item_id": "1246464644"
               },
               {
                  "merchant_item_id": "1246464644"
               }
            ],
            "contact": {
               "consignor_contact": "****123-8008",
               "receiver_contact": "0**2-***1234"
            }
         }
      ]
   }
];
jsonBody["upload_time"] = "2021-05-20T13:29:35.120 08:00";
jsonBody["payer"] = {
   "openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o"
};

// 设置包头
let headers = {"Content-Type": "application/json"};


// 发送请求
fetch(url, {
  body: JSON.stringify(jsonBody),
  headers: headers,
  method: "POST"
})
  .then(response => response.json())
  .then(response => console.log("Success:", JSON.stringify(response)))
  .catch(error => console.error("Error:", error));

# 返回数据示例


{ 
"errcode":0, 
"errmsg":"ok"
}

# 错误码

错误码	错误码取值	解决方案
-1	system error	系统繁忙，此时请开发者稍候再试
268435461	参数错误	根据错误原因描述修改参数
268485192	用户标识openid为空	用户标识openid必须填写
268485214	上传时间必须设置	上传时间必须填写
268485195	微信支付单号形式下transaction_id字段必须设置	微信支付单号形式下transaction_id字段必须设置
268485196	商户侧单号形式下mchid字段必须设置	商户侧单号形式下mchid字段必须设置
268485197	商户侧单号形式out_trade_no字段必须设置	商户侧单号形式下out_trade_no字段必须设置
268485194	订单单号类型非法	按照文档中订单类型枚举填写该字段
268485253	上传的合单购物详情主单的订单单号类型与子单的单号类型不一致	上传的合单购物详情主单的订单单号类型与子单的单号类型必须一致
268485195	微信支付单号形式下transaction_id字段必须设置	微信支付单号形式下transaction_id字段必须设置
268485196	商户侧单号形式下mchid字段必须设置	商户侧单号形式下mchid字段必须设置
268485197	商户侧单号形式out_trade_no字段必须设置	商户侧单号形式下out_trade_no字段必须设置
268485194	订单单号类型非法	按照文档中订单类型枚举填写该字段
268485224	物流发货模式非法	按照文档中物流形式枚举设置该字段
268485229	物流信息列表为空	物流信息列表至少填写一个
268485228	统一发货模式下，物流信息列表长度必须为1	统一发货模式下，物流信息列表长度必须为1
268485231	统一发货模式下不需要填写商品ID	统一发货模式下不需要填写商品ID
268485226	物流单号不能为空	物流单号必须填写
268485227	物流公司编码必须设置	物流公司编码必须填写
268485230	物流关联的商品列表中的商户侧商品ID不能为空	物流关联的商品列表中的商户侧商品ID必须填写
268485232	分拆发货模式下，物流关联的商品列表不能为空	分拆发货模式下，物流关联的商品列表至少填写一个
268457014	openid解码后为0	openid不合法，请确认后重试
268485216	上传时间非法，请按照Rfc3399格式填写	上传时间必须满足Rfc3399格式，如2021-05-20T13:29:35.120+08:00
268485217	商户号不合法，请确认后重试	商户号不合法，请确认后重试