# 预下配送单
接口应在服务器端调用，不可在前端（小程序、网页、APP等）直接调用，具体可参考接口调用指南。
接口英文名：preAddOrder
# 使用场景描述
- 在用户提交外卖订单时，商家可调用本接口查询配送公司是否可接单、预计多久接单、运费预估等。预估运费可作为展示给用户的运费参考值。
- 举个例子：商家通过预下配送单接口返回的预估运费是8元，商家可决定前端顾客下外卖单时展示给顾客看的运费是真实的8元，还是其他商家指定的金额。
- 说明：本接口非必须调用接口，若不需要获取配送公司是否可接单、预计多久接单、运费预估等，也可不调用本接口，直接下配送单。
- 顺丰同城可返回配送费用、配送距离、预计骑手接单时间，不支持返回delivery_token。
- 闪送可返回配送费用、配送距离、预计骑手接单时间，不支持返回delivery_token。
- 美团配送返回0时表示校验通过，不支持返回配送费用、配送距离、预计骑手接单时间和delivery_token。
- 达达支持预下单查询配送费用、配送距离、预计骑手接单时间和delivery_token(有效期3分钟)
# 1. 调用方式
# HTTPS 调用
POST https://api.weixin.qq.com/cgi-bin/express/local/business/order/pre_add?access_token=ACCESS_TOKEN
# 云调用
- 本接口不支持云调用。
# 第三方调用
本接口支持第三方平台代商家调用。
该接口所属的权限集 id 为：51、71
服务商获得其中之一权限集授权后，可通过使用 authorizer_access_token 代商家进行调用，具体可查看 第三方调用 说明文档。
# 2. 请求参数
# 查询参数 Query String Parameters
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| access_token | string | 是 | 接口调用凭证，可使用 access_token、authorizer_access_token |
# 请求体 Request Payload
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| shopid | string | 是 | 商家id， 由配送公司分配的appkey |
| shop_order_id | string | 是 | 唯一标识订单的 ID，由商户生成, 不超过128字节 |
| delivery_id | string | 是 | 配送公司ID |
| openid | string | 是 | 下单用户的openid |
| sender | object | 是 | 发件人信息，闪送、顺丰同城急送必须填写，美团配送、达达，若传了shop_no的值可不填该字段 |
| receiver | object | 是 | 收件人信息 |
| cargo | object | 是 | 货物信息 |
| order_info | object | 是 | 订单信息 |
| shop | object | 是 | 商品信息，会展示到物流通知消息中 |
| delivery_sign | string | 是 | 用配送公司提供的appSecret加密的校验串说明 |
| shop_no | string | 是 | 商家门店编号，在配送公司登记，美团、闪送必填 |
| sub_biz_id | string | 是 | 子商户id，区分小程序内部多个子商户 |
# Body.sender Object Payload
发件人信息，闪送、顺丰同城急送必须填写，美团配送、达达，若传了shop_no的值可不填该字段
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | 是 | 姓名，最长不超过256个字符 |
| city | string | 是 | 城市名称，如广州市 |
| address | string | 是 | 地址(街道、小区、大厦等，用于定位) |
| address_detail | string | 是 | 地址详情(楼号、单元号、层号) |
| phone | string | 是 | 电话/手机号，最长不超过64个字符 |
| lng | number | 是 | 经度（火星坐标或百度坐标，和 coordinate_type 字段配合使用，确到小数点后6位 |
| lat | number | 是 | 纬度（火星坐标或百度坐标，和 coordinate_type 字段配合使用，精确到小数点后6位） |
| coordinate_type | number | 否 | 坐标类型，0：火星坐标（高德，腾讯地图均采用火星坐标） 1：百度坐标 |
# Body.receiver Object Payload
收件人信息
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | 是 | 姓名，最长不超过256个字符 |
| city | string | 是 | 城市名称，如广州市 |
| address | string | 是 | 地址(街道、小区、大厦等，用于定位) |
| address_detail | string | 是 | 地址详情(楼号、单元号、层号) |
| phone | string | 是 | 电话/手机号，最长不超过64个字符 |
| lng | number | 是 | 经度（火星坐标或百度坐标，和 coordinate_type 字段配合使用，确到小数点后6位 |
| lat | number | 是 | 纬度（火星坐标或百度坐标，和 coordinate_type 字段配合使用，精确到小数点后6位） |
| coordinate_type | number | 否 | 坐标类型，0：火星坐标（高德，腾讯地图均采用火星坐标） 1：百度坐标 |
# Body.cargo Object Payload
货物信息
| 参数名 | 类型 | 必填 | 说明 | 枚举 |
|---|---|---|---|---|
| goods_value | number | 是 | 货物价格，单位为元，精确到小数点后两位（如果小数点后位数多于两位，则四舍五入保留两位小数），范围为(0-5000] | - |
| goods_height | number | 否 | 货物高度，单位为cm，精确到小数点后两位（如果小数点后位数多于两位，则四舍五入保留两位小数），范围为(0-45] | - |
| goods_width | number | 否 | 货物宽度，单位为cm，精确到小数点后两位（如果小数点后位数多于两位，则四舍五入保留两位小数），范围为(0-50] | - |
| goods_length | number | 否 | 货物长度，单位为cm，精确到小数点后两位（如果小数点后位数多于两位，则四舍五入保留两位小数），范围为(0-65] | - |
| goods_weight | number | 是 | 货物重量，单位为kg，精确到小数点后两位（如果小数点后位数多于两位，则四舍五入保留两位小数），范围为(0-50] | - |
| goods_detail | object | 否 | 货物详情，最长不超过10240个字符 | - |
| goods_pickup_info | string | 否 | 货物取货信息，用于骑手到店取货，最长不超过100个字符 | - |
| cargo_first_class | string | 是 | 品类一级类目, | 枚举值 |
| cargo_second_class | string | 是 | 品类二级类目 | - |
# Body.order_info Object Payload
订单信息
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| delivery_service_code | string | 否 | 配送服务代码 不同配送公司自定义, 顺丰和达达不填 |
| expected_delivery_time | number | 否 | 期望派单时间(达达支持，表示达达系统调度时间, 到那个时间才会有状态更新的回调通知)，unix-timestamp, 比如1586342180 |
| order_type | number | 否 | 订单类型, 0: 即时单 1 预约单，如预约单，需要设置expected_delivery_time或expected_finish_time或expected_pick_time |
| poi_seq | string | 否 | 门店订单流水号，建议提供，方便骑手门店取货，最长不超过32个字符 |
| note | string | 否 | 备注，最长不超过200个字符 |
| order_time | number | 否 | 用户下单付款时间, 顺丰必填, 比如1555220757 |
| is_insured | number | 否 | 是否保价，0，非保价，1.保价 |
| declared_value | number | 否 | 保价金额，单位为元，精确到分 |
| tips | number | 否 | 小费，单位为元, 下单一般不加小费 |
| is_direct_delivery | number | 否 | 是否选择直拿直送（0：不需要；1：需要。选择直拿直送后，同一时间骑手只能配送此订单至完成，配送费用也相应高一些，闪送必须选1，达达可选0或1，其余配送公司不支持直拿直送） |
| cash_on_delivery | number | 否 | 骑手应付金额，单位为元，精确到分 |
| cash_on_pickup | number | 否 | 骑手应收金额，单位为元，精确到分 |
| rider_pick_method | number | 否 | 物流流向，1：从门店取件送至用户；2：从用户取件送至门店 |
| is_finish_code_needed | number | 否 | 收货码（0：不需要；1：需要。收货码的作用是：骑手必须输入收货码才能完成订单妥投） |
| is_pickup_code_needed | number | 否 | 取货码（0：不需要；1：需要。取货码的作用是：骑手必须输入取货码才能从商家取货） |
| expected_finish_time | number | 否 | 期望送达时间(美团、顺丰同城急送支持），unix-timestamp, 比如1586342180 |
| expected_pick_time | number | 否 | 期望取件时间（闪送、顺丰同城急送支持，闪送需要设置两个小时后的时间，顺丰同城急送只需传expected_finish_time或expected_pick_time其中之一即可，同时都传则以expected_finish_time为准），unix-timestamp, 比如1586342180 |
# Body.shop Object Payload
商品信息，会展示到物流通知消息中
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| wxa_path | string | 否 | 商家小程序的路径，建议为订单页面 |
| img_url | string | 否 | 商品缩略图 url；shop.detail_list为空则必传，shop.detail_list非空可不传。 |
| goods_name | string | 否 | 商品名称, 不超过128字节；shop.detail_list为空则必传，shop.detail_list非空可不传。 |
| goods_count | number | 否 | 商品数量；shop.detail_list为空则必传。shop.detail_list非空可不传，默认取shop.detail_list的size |
| wxa_appid | string | 否 | 该参数在【即时配送】的addLocalOrder接口才生效。若结算方式为：第三方向配送公司统一结算，商户后续和第三方结算，则该参数必填；在该结算模式下，第三方用自己的开发小程序替授权商户发起下单，并将授权小程序的appid给平台，后续配送通知中可回流授权商户小程序。 |
# Body.cargo.goods_detail Object Payload
货物详情，最长不超过10240个字符
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| goods | objarray | 是 | 货物列表 |
# Body.cargo.goods_detail.goods(Array) Object Payload
货物列表
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| good_count | number | 是 | 货物数量 |
| good_name | string | 是 | 货品名称 |
| good_price | number | 否 | 货品单价，精确到小数点后两位（如果小数点后位数多于两位，则四舍五入保留两位小数） |
| good_unit | string | 否 | 货品单位，最长不超过20个字符 |
# 3. 返回参数
# 返回体 Response Payload
| 参数名 | 类型 | 说明 |
|---|---|---|
| resultcode | number | 运力返回的错误码 |
| resultmsg | string | 运力返回的错误描述 |
| fee | number | 实际运费(单位：元)，运费减去优惠券费用 |
| deliverfee | number | 运费(单位：元) |
| couponFee | number | 优惠券费用(单位：元) |
| tips | number | 小费(单位：元) |
| insurancefee | number | 保价费(单位：元) |
| distance | number | 配送距离(单位：米)预计骑手接单时间，单位秒，比如5分钟，就填300, 无法预计填0 |
| delivery_token | string | 配送公司可以返回此字段，当用户下单时候带上这个字段，保证在一段时间内运费不变 |
| dispatch_duration | number | 预计骑手接单时间，单位秒，比如5分钟，就填300, 无法预计填0 |
# 4. 枚举信息
# Body.cargo.cargo_first_class Enum
品类一级类目,
| 枚举值 | 描述 |
|---|---|
| 美食夜宵 | 零食小吃 香锅/烤鱼 西餐 日韩料理 海鲜/烧烤 快餐/地方菜 小龙虾 披萨 |
| 甜品饮料 | 甜品 奶茶果汁 咖啡 面包/糕点 冰淇淋 |
| 蛋糕 | 蛋糕 |
| 日用百货 | 便利店 水站/奶站 零食/干果 五金日用 粮油调味 文具店 酒水行 地方特产 进口食品 宠物用品 超市 书店 宠物食品用品 办公家居用品 |
| 果蔬生鲜 | 果蔬 海鲜水产 冷冻速食 |
| 鲜花 | 鲜花 |
| 医药健康 | 送药 器材器具 |
| 美妆护肤 | 日化美妆 |
| 母婴 | 孕婴用品 |
| 文件或票务 | 保单 票务文件 政府文件 证件 |
| 服饰鞋帽 | 服饰鞋帽综合 |
| 洗涤 | 脏衣服收 干净衣服派 |
| 珠宝奢侈品 | 珠宝饰品 奢侈品 |
| 家居家装 | 家具 装修建材 厨房卫浴 |
| 数码产品 | 数码产品 |
| 配件器材 | 配件器材 |
| 电商 | 电视购物 线上商城 |
| 现场勘查 | 现场勘查 |
| 快递业务 | 快递配送 |
| 其他 | 其他 |
# 5. 注意事项
本接口无特殊注意事项
# 6. 代码示例
# 6.1 HTTPS调用成功返回
请求示例
{
"cargo": {
"cargo_first_class": "美食夜宵",
"cargo_second_class": "零食小吃",
"goods_detail": {
"goods": [
{
"good_count": 1,
"good_name": "水果",
"good_price": 10,
"good_unit": "元"
},
{
"good_count": 2,
"good_name": "蔬菜",
"good_price": 20,
"good_unit": "元"
}
]
},
"goods_height": 1,
"goods_length": 3,
"goods_value": 5,
"goods_weight": 1,
"goods_width": 2
},
"delivery_id": "SFTC",
"delivery_sign": "01234567890123456789",
"openid": "oABC123456",
"order_info": {
"delivery_service_code": "",
"expected_delivery_time": 0,
"is_direct_delivery": 0,
"is_finish_code_needed": 1,
"is_insured": 0,
"is_pickup_code_needed": 1,
"note": "test_note",
"order_time": 1555220757,
"order_type": 0,
"poi_seq": "1111",
"tips": 0
},
"receiver": {
"address": "xxx地铁站",
"address_detail": "2号楼202",
"city": "北京市",
"coordinate_type": 0,
"lat": 40.1529600000,
"lng": 116.5060300000,
"name": "老王",
"phone": "18512345678"
},
"sender": {
"address": "xx大厦",
"address_detail": "1号楼101",
"city": "北京市",
"coordinate_type": 0,
"lat": 40.4486120000,
"lng": 116.3830750000,
"name": "刘一",
"phone": "13712345678"
},
"shop": {
"goods_count": 2,
"goods_name": "宝贝",
"img_url": "https://mmbiz.qpic.cn/mmbiz_png/xxxxxxxxx/0?wx_fmt=png",
"wxa_path": "/page/index/index"
},
"shop_no": "12345678",
"sub_biz_id": "sub_biz_id_1",
"shop_order_id": "SFTC_001",
"shopid": "122222222",
}
返回示例
{
"resultcode": 0,
"resultmsg": "ok",
"fee": 10,
"deliverfee": 10,
"couponfee": 0,
"tips": 0,
"insurancfee": 0,
"distance": 1000,
"dispatch_duration": 300,
"delivery_token": "1111111"
}
# 6.2 HTTPS调用失败返回
请求示例
{
"cargo": {
"cargo_first_class": "美食夜宵",
"cargo_second_class": "零食小吃",
"goods_detail": {
"goods": [
{
"good_count": 1,
"good_name": "水果",
"good_price": 10,
"good_unit": "元"
},
{
"good_count": 2,
"good_name": "蔬菜",
"good_price": 20,
"good_unit": "元"
}
]
},
"goods_height": 1,
"goods_length": 3,
"goods_value": 5,
"goods_weight": 1,
"goods_width": 2
},
"delivery_id": "SFTC",
"delivery_sign": "01234567890123456789",
"openid": "oABC123456",
"order_info": {
"delivery_service_code": "",
"expected_delivery_time": 0,
"is_direct_delivery": 0,
"is_finish_code_needed": 1,
"is_insured": 0,
"is_pickup_code_needed": 1,
"note": "test_note",
"order_time": 1555220757,
"order_type": 0,
"poi_seq": "1111",
"tips": 0
},
"receiver": {
"address": "xxx地铁站",
"address_detail": "2号楼202",
"city": "北京市",
"coordinate_type": 0,
"lat": 40.1529600000,
"lng": 116.5060300000,
"name": "老王",
"phone": "18512345678"
},
"sender": {
"address": "xx大厦",
"address_detail": "1号楼101",
"city": "北京市",
"coordinate_type": 0,
"lat": 40.4486120000,
"lng": 116.3830750000,
"name": "刘一",
"phone": "13712345678"
},
"shop": {
"goods_count": 2,
"goods_name": "宝贝",
"img_url": "https://mmbiz.qpic.cn/mmbiz_png/xxxxxxxxx/0?wx_fmt=png",
"wxa_path": "/page/index/index"
},
"shop_no": "12345678",
"sub_biz_id": "sub_biz_id_1",
"shop_order_id": "SFTC_001",
"shopid": "122222222",
}
返回示例
{
"resultcode": 1010,
"resultmsg": "收件人信息不正确"
}
# 7. 错误码
以下是本接口的错误码列表，其他错误码可参考 通用错误码；调用接口遇到报错，可使用官方提供的 API 诊断工具 辅助定位和分析问题。
| 错误码 | 错误描述 | 解决方案 |
|---|---|---|
| 40001 | invalid credential access_token isinvalid or not latest | 获取 access_token 时 AppSecret 错误，或者 access_token 无效。请开发者认真比对 AppSecret 的正确性，或查看是否正在为恰当的公众号调用接口 |
# 8. 适用范围
本接口暂未明确可调用账号类型，或在业务中根据调用传参自行确定是否可调用，请以实际调用情况为准。