# 发货信息合单录入

接口应在服务器端调用，不可在前端（小程序、网页、APP等）直接调用，具体可参考接口调用指南。

接口英文名：uploadCombinedShippingInfo

用户交易后，默认资金将会进入冻结状态，开发者在发货后，需要在小程序平台录入相关发货信息，平台会将发货信息以消息的形式推送给购买的微信用户。

如果你已经录入发货信息，在用户尚未确认收货的情况下可以通过该接口修改发货信息，但一个支付单只能更新一次发货信息，请谨慎操作。

如暂时没有完成相关API的对接开发工作，你也可以登陆小程序的后台，通过发货信息录入页面手动录入发货信息。

# 1. 调用方式

# HTTPS 调用

POST https://api.weixin.qq.com/wxa/sec/order/upload_combined_shipping_info?access_token=ACCESS_TOKEN

# 云调用

调用方法：wxa.sec.order.uploadCombinedShippingInfo
出入参和 HTTPS 调用相同，调用方式可查看云调用说明文档。

# 第三方调用

本接口支持第三方平台代商家调用。
该接口所属的权限集 id 为：142
服务商获得其中之一权限集授权后，可通过使用 authorizer_access_token 代商家进行调用，具体可查看第三方调用说明文档。

# 2. 请求参数

# 查询参数 `Query String Parameters`

参数名	类型	必填	示例	说明
access_token	string	是	ACCESS_TOKEN	接口调用凭证，可使用 access_token、authorizer_access_token

# 请求体 `Request Payload`

参数名	类型	必填	说明
order_key	object	是	合单订单，需要上传物流详情的合单订单，根据订单类型二选一
sub_orders	objarray	否	子单物流详情
upload_time	string	是	上传时间，用于标识请求的先后顺序示例值: `2022-12-15T13:29:35.120+08:00`
payer	object	是	支付者，支付者信息

# Body.order_key `Object Payload`

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

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

# Body.sub_orders(Array) `Object Payload`

子单物流详情

参数名	类型	必填	说明
order_key	object	是	需要上传物流详情的子单订单，订单类型与合单订单保持一致
logistics_type	number	是	物流模式，发货方式枚举值：1、实体物流配送采用快递公司进行实体物流配送形式 2、同城配送 3、虚拟商品，虚拟商品，例如话费充值，点卡等，无实体配送形式 4、用户自提
delivery_mode	number	是	发货模式，发货模式枚举值：1、UNIFIED_DELIVERY（统一发货）2、SPLIT_DELIVERY（分拆发货）示例值: UNIFIED_DELIVERY
is_all_delivered	boolean	否	分拆发货模式时必填，用于标识分拆发货模式下是否已全部发货完成，只有全部发货完成的情况下才会向用户推送发货完成通知。示例值: true/false
shipping_list	objarray	否	子单物流信息列表多重性: [1, 15]

# Body.payer `Object Payload`

支付者，支付者信息

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

# Body.sub_orders(Array).order_key `Object Payload`

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

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

# Body.sub_orders(Array).shipping_list`Object Payload`

子单物流信息列表多重性: [1, 15]

参数名	类型	必填	说明
tracking_no	string	否	物流单号，物流快递发货时必填，示例值: 323244567777 字符字节限制: [1, 128]
express_company	string	否	物流公司编码，快递公司ID，参见获取运力 id 列表get_delivery_list，物流快递发货时必填，示例值: DHL 字符字节限制: [1, 128]
item_desc	string	是	商品信息，例如：微信红包抱枕*1个，限120个字以内
contact	object	否	联系方式，当发货的物流公司为顺丰时，联系方式为必填，收件人或寄件人联系方式二选一

# Body.sub_orders(Array).shipping_list.contact `Object Payload`

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

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

# 3. 返回参数

# 返回体 `Response Payload`

参数名	类型	说明
errcode	number	错误码
errmsg	string	错误信息

# 4. 注意事项

1.根据指定的订单单号类型，采用不同参数给指定订单上传物流信息，注意子单和主单的订单单号类型必须一致：

(1). 商户侧单号形式（枚举值1），通过下单商户号和商户侧单号确定一笔订单。

(2). 微信支付单号形式（枚举值2），通过微信支付单号确定一笔订单。

2.发货模式根据具体发货情况选择：

(1). 统一发货（枚举值1），一笔订单统一发货，只有一个物流单号。

(2). 分拆发货（枚举值2），一笔订单分拆发货，包括多个物流单号。

3.物流公司编码，参见获取运力 id 列表get_delivery_list。

4.上传时间，用于标识请求的先后顺序，如果要更新物流信息，上传时间必须比之前的请求更新，请按照RFC 3339格式填写。

5.分拆发货仅支持使用物流快递发货，一笔支付单最多分拆成 15 个包裹。

6.以下情况将视为重新发货，每笔支付单仅有一次重新发货机会。

(1). 对已完成发货的支付单再次调用该 API。

(2). 使用该 API 修改发货模式或物流模式。

# 5. 代码示例

请求示例

{
    "order_key": {
        "order_number_type": 1,
        "mchid": "fake-mchid-123",
        "out_trade_no": "fake-tradeno-20221214190427-0"
    },
    "sub_orders": [
        {
            "order_key": {
                "order_number_type": 1,
                "mchid": "fake-mchid-123",
                "out_trade_no": "fake-tradeno-20221214190427-01"
            },
            "delivery_mode": 2,
            "logistics_type": 1,
            "is_all_delivered": true,
            "shipping_list": [
                {
                    "tracking_no": "fake-trackingno-202212141904271",
                    "express_company": "YD",
                    "item_desc": "微信气泡狗零钱包*1",
                    "contact": {
                        "consignor_contact": "021-**34-12"
                    }
                },
                {
                    "tracking_no": "fake-trackingno-202212141904272",
                    "express_company": "DHL",
                    "item_desc": "微信黄脸布艺胸针*1；微信气泡狗零钱包*1",
                    "contact": {
                        "consignor_contact": "021-**34-12"
                    }
                }
            ]
        },
        {
            "order_key": {
                "order_number_type": 1,
                "mchid": "fake-mchid-321",
                "out_trade_no": "fake-tradeno-20221214190427-02"
            },
            "delivery_mode": 1,
            "logistics_type": 1,
            "shipping_list": [
                {
                    "tracking_no": "fake-trackingno-202212141904273",
                    "express_company": "YTO",
                    "item_desc": "微信气泡狗双面钥匙扣*1",
                    "contact": {
                        "receiver_contact": "+86-123****4321"
                    }
                }
            ]
        }
    ],
    "upload_time": "2022-12-15T13:29:35.120+08:00",
    "payer": {
        "openid": "ogqztkPsejM9MQAFfwCQSCi4oNg3"
    }
}

返回示例

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

# 6. 错误码

以下是本接口的错误码列表，其他错误码可参考通用错误码；调用接口遇到报错，可使用官方提供的 API 诊断工具辅助定位和分析问题。

错误码	错误描述
-1	system error。系统繁忙，此时请开发者稍候再试
10060001	支付单不存在。请检查微信支付单号形式下 transaction_id 字段或商户侧单号形式下 mchid、out_trade_no 字段是否有误
10060002	支付单已完成发货，无法继续发货。请检查支付单发货情况
10060003	支付单已使用重新发货机会。支付单处于已发货状态时调用该API视为重新发货，仅可重新发货一次，请检查支付单发货情况
10060004	支付单处于不可发货的状态。请检查支付单状态
10060005	物流类型有误。按照文档中物流类型枚举填写该字段
10060006	非快递发货时不允许分拆发货。非快递发货时不允许分拆发货，请检查请求参数
10060007	分拆发货模式下必须填写 is_all_delivered 字段。请检查请求参数中的 is_all_delivered 字段
10060008	商品描述 item_desc 字段不能为空。用于发货信息录入场景时商品描述字段不能为空
10060009	商品描述 item_desc 字段太长。请检查商品描述字段
10060012	系统错误。系统繁忙，此时请开发者稍候再试
10060014	参数错误。根据错误原因描述修改参数
10060019	系统错误。系统繁忙，此时请开发者稍候再试
10060020	该笔支付单在没有任何商品描述的情况下不允许完成发货。请补充商品描述 item_desc
10060023	发货信息未更新。支付单信息不变
10060024	物流信息列表太长。支付单物流信息列表长度不可大于 15
10060025	物流公司编码太长。请检查物流公司编码是否有误
10060026	物流单号太长.。请检查物流单号是否有误
10060031	该笔支付单不属于 openid 所指定的用户。请检查支付单号或 openid 是否有误
268485194	订单单号类型非法。按照文档中订单单号类型枚举填写该字段
268485195	微信支付单号形式下 transaction_id 字段不能为空。微信支付单号形式下 transaction_id 字段必须设置
268485196	商户侧单号形式下 mchid 字段不能为空。商户侧单号形式下 mchid 字段必须设置
268485197	商户侧单号形式下 out_trade_no 字段不能为空。商户侧单号形式下 out_trade_no 字段必须设置
268485216	上传时间非法，请按照 RFC 3339 格式填写。上传时间必须满足 RFC 3339 格式，如 2022-12-15T13:29:35.120+08:00
268485224	发货模式非法。按照文档中发货模式枚举设置该字段
268485226	物流单号不能为空。物流快递发货时物流单号必须填写
268485227	物流公司编码不能为空。物流快递发货时物流公司编码必须填写
268485228	统一发货模式下，物流信息列表长度必须为 1。统一发货模式下，物流信息列表长度必须为 1

# 7. 适用范围

本接口暂未明确可调用账号类型，或在业务中根据调用传参自行确定是否可调用，请以实际调用情况为准。

# 发货信息合单录入

# 1. 调用方式

# HTTPS 调用

# 云调用

# 第三方调用

# 2. 请求参数

# 查询参数 Query String Parameters

# 请求体 Request Payload

# Body.order_key Object Payload

# Body.sub_orders(Array) Object Payload

# Body.payer Object Payload

# Body.sub_orders(Array).order_key Object Payload

# Body.sub_orders(Array).shipping_listObject Payload

# Body.sub_orders(Array).shipping_list.contact Object Payload