# 发货信息合单录入

> 接口应在服务器端调用，不可在前端（小程序、网页、APP等）直接调用，具体可参考[接口调用指南](/doc/oplatform/developers/dev/guide.md)。

接口英文名：uploadCombinedShippingInfo

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

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

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

## 1. 调用方式

### HTTPS 调用

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

### 云调用

- 调用方法：wxa.sec.order.uploadCombinedShippingInfo

- 出入参和 HTTPS 调用相同，调用方式可查看 [云调用](/doc/oplatform/developers/dev/cloudCall.md) 说明文档。

### 第三方调用

- 本接口支持第三方平台代商家调用。

- 该接口所属的权限集 id 为：142

- 服务商获得其中之一权限集授权后，可通过使用 [authorizer_access_token](/doc/oplatform/developers/dev/AuthorizerAccessToken.md) 代商家进行调用，具体可查看 [第三方调用](/doc/oplatform/Third-party_Platforms/2.0/Before_Develop/call_interface.md) 说明文档。

## 2. 请求参数

### 查询参数 `Query String Parameters`

```json
[
  {
    "参数名": "access_token",
    "类型": "string",
    "必填": "是",
    "示例": "ACCESS_TOKEN",
    "说明": "接口调用凭证，可使用 [access_token](/miniprogram/dev/server/API/mp-access-token/api_getaccesstoken)、[authorizer_access_token](/doc/oplatform/openApi/ticket-token/api_getauthorizeraccesstoken.md)"
  }
]
```

### 请求体 `Request Payload`

```json
[
  {
    "参数名": "order_key",
    "类型": "object",
    "必填": "是",
    "说明": "合单订单，需要上传物流详情的合单订单，根据订单类型二选一"
  },
  {
    "参数名": "sub_orders",
    "类型": "objarray",
    "必填": "否",
    "说明": "子单物流详情"
  },
  {
    "参数名": "upload_time",
    "类型": "string",
    "必填": "是",
    "说明": "上传时间，用于标识请求的先后顺序 示例值: \u0000INLINECODE_2\u0000"
  },
  {
    "参数名": "payer",
    "类型": "object",
    "必填": "是",
    "说明": "支付者，支付者信息"
  }
]
```

### Body.order_key `Object Payload`

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

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

">

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

子单物流详情

```json
[
  {
    "参数名": "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`

支付者，支付者信息

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

__order_key">

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

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

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

__shipping_list">

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

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

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

__shipping_list__contact">

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

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

```json
[
  {
    "参数名": "consignor_contact",
    "类型": "string",
    "必填": "否",
    "说明": "寄件人联系方式，寄件人联系方式，采用掩码传输，最后4位数字不能打掩码 示例值: \u0000INLINECODE_11\u0000 值限制: 0 ≤ value ≤ 1024"
  },
  {
    "参数名": "receiver_contact",
    "类型": "string",
    "必填": "否",
    "说明": "收件人联系方式，收件人联系方式为，采用掩码传输，最后4位数字不能打掩码 示例值: \u0000INLINECODE_12\u0000 值限制: 0 ≤ value ≤ 1024"
  }
]
```

## 3. 返回参数

### 返回体 `Response Payload`

```json
[
  {
    "参数名": "errcode",
    "类型": "number",
    "说明": "错误码"
  },
  {
    "参数名": "errmsg",
    "类型": "string",
    "说明": "错误信息"
  }
]
```

## 4. 注意事项

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

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

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

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

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

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

3.物流公司编码，参见[获取运力 id 列表get_delivery_list](/miniprogram/dev/server/API/weixin-express/express-msg/api_get_delivery_list)。

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

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

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

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

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

## 5. 代码示例

请求示例

```json
{
    "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"
    }
}
```

返回示例

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

## 6. 错误码

以下是本接口的错误码列表，其他错误码可参考 [通用错误码](/doc/oplatform/developers/errCode/README.md)；调用接口遇到报错，可使用官方提供的 [API 诊断工具](https://developers.weixin.qq.com/console/devtools/debug?utm_source=api_errcode) 辅助定位和分析问题。

```json
[
  {
    "错误码": "-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. 适用范围

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