小程序
取消
开发
中文
EN
取消
  • 服务端

    • # 预下配送单

    调试工具

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

    # 接口说明

    # 接口英文名

    preAddOrder

    # 功能描述

    # 使用场景描述

    • 在用户提交外卖订单时，商家可调用本接口查询配送公司是否可接单、预计多久接单、运费预估等。预估运费可作为展示给用户的运费参考值。
    • 举个例子：商家通过预下配送单接口返回的预估运费是8元，商家可决定前端顾客下外卖单时展示给顾客看的运费是真实的8元，还是其他商家指定的金额。
    • 说明：本接口非必须调用接口，若不需要获取配送公司是否可接单、预计多久接单、运费预估等，也可不调用本接口，直接下配送单。
    • 顺丰同城可返回配送费用、配送距离、预计骑手接单时间，不支持返回delivery_token。
    • 闪送可返回配送费用、配送距离、预计骑手接单时间，不支持返回delivery_token。
    • 美团配送返回0时表示校验通过，不支持返回配送费用、配送距离、预计骑手接单时间和delivery_token。
    • 达达支持预下单查询配送费用、配送距离、预计骑手接单时间和delivery_token(有效期3分钟)

    # 调用方式

    # HTTPS 调用

    
POST https://api.weixin.qq.com/cgi-bin/express/local/business/order/pre_add?access_token=ACCESS_TOKEN

    # 第三方调用

    • 调用方式以及出入参和HTTPS相同，仅是调用的token不同

    • 该接口所属的权限集id为：51、71

    • 服务商获得其中之一权限集授权后，可通过使用authorizer_access_token代商家进行调用

    # 请求参数

    属性 类型 必填说明
    access_token string 是 接口调用凭证，该参数为 URL 参数，非 Body 参数。使用getAccessToken 或者 authorizer_access_token
    shopid string 是 商家id， 由配送公司分配的appkey
    shop_order_id string 是 唯一标识订单的 ID，由商户生成, 不超过128字节
    delivery_id string 是 配送公司ID
    openid string 是 下单用户的openid
    sender object 是 发件人信息，闪送、顺丰同城急送必须填写，美团配送、达达，若传了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：百度坐标
    country_name string 否
    receiver object 是 收件人信息
    属性 类型 必填 说明
    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：百度坐标
    country_name string 否
    cargo object 是 货物信息
    属性 类型 必填 说明
    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 array<object> 是 货物列表
    属性 类型 必填 说明
    good_count number 是 货物数量
    good_name string 是 货品名称
    good_price number 否 货品单价，精确到小数点后两位（如果小数点后位数多于两位，则四舍五入保留两位小数）
    good_unit string 否 货品单位，最长不超过20个字符
    goods_pickup_info string 否 货物取货信息，用于骑手到店取货，最长不超过100个字符
    cargo_first_class string 是 品类一级类目, 详见品类表
    cargo_second_class string 是 品类二级类目
    order_info object 是 订单信息
    属性 类型 必填 说明
    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
    shop object 是 商品信息，会展示到物流通知消息中
    属性 类型 必填 说明
    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 否 该参数在【即使配送】的addOrder接口才生效。若结算方式为：第三方向配送公司统一结算，商户后续和第三方结算，则该参数必填；在该结算模式下，第三方用自己的开发小程序替授权商户发起下单，并将授权小程序的appid给平台，后续配送通知中可回流授权商户小程序。
    detail_list array<object> 否
    属性 类型 必填 说明
    goods_name string 是 商品名称
    goods_img_url string 是 商品图片url
    delivery_sign string 是 用配送公司提供的appSecret加密的校验串说明
    shop_no string 是 商家门店编号，在配送公司登记，美团、闪送必填
    sub_biz_id string 是 子商户id，区分小程序内部多个子商户
    order_source string 否
    order_sequence string 否

    # 返回参数

    属性 类型 说明
    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

    # 调用示例

    示例说明: 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"
}

    示例说明: HTTPS调用失败返回

    # 请求数据示例

    
同上

    # 返回数据示例

    
{
  "resultcode": 1010,
  "resultmsg": "收件人信息不正确"
}

    # 错误码

    错误码 错误码取值 解决方案
    40001 invalid credential  access_token isinvalid or not latest 获取 access_token 时 AppSecret 错误，或者 access_token 无效。请开发者认真比对 AppSecret 的正确性，或查看是否正在为恰当的公众号调用接口