# 添加配送单

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

接口英文名：addLocalOrder

该接口用于下配送单。

# 1. 调用方式

# HTTPS 调用

POST https://api.weixin.qq.com/cgi-bin/express/local/business/order/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_token	string	是	预下单接口返回的参数，配送公司可保证在一段时间内运费不变
delivery_sign	string	是	用配送公司提供的appSecret加密的校验串，见注意事项
shop_no	string	是	商家门店编号，在配送公司登记，如果只有一个门店，美团闪送必填, 值为店铺id
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	否	该参数在【即使配送】的addOrder接口才生效。若结算方式为：第三方向配送公司统一结算，商户后续和第三方结算，则该参数必填；在该结算模式下，第三方用自己的开发小程序替授权商户发起下单，并将授权小程序的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	小费(单位：元)	-
insurancfee	number	保价费(单位：元)	-
distance	number	配送距离(整数单位：米)	-
waybill_id	string	配送单号	-
order_status	number	配送状态。	枚举值
finish_code	number	收货码	-
pickup_code	number	取货码	-
dispatch_duration	number	预计骑手接单时间，单位秒，比如5分钟，就填300, 无法预计填0	-

# 4. 枚举信息

# Body.cargo.cargo_first_class `Enum`

品类一级类目

枚举值	描述
美食夜宵	零食小吃香锅/烤鱼西餐日韩料理海鲜/烧烤快餐/地方菜小龙虾披萨
甜品饮料	甜品奶茶果汁咖啡面包/糕点冰淇淋
蛋糕	蛋糕
日用百货	便利店水站/奶站零食/干果五金日用粮油调味文具店酒水行地方特产进口食品宠物用品超市书店宠物食品用品办公家居用品
果蔬生鲜	果蔬海鲜水产冷冻速食
鲜花	鲜花
医药健康	送药器材器具
美妆护肤	日化美妆
母婴	孕婴用品
文件或票务	保单票务文件政府文件证件
服饰鞋帽	服饰鞋帽综合
洗涤	脏衣服收干净衣服派
珠宝奢侈品	珠宝饰品奢侈品
家居家装	家具装修建材厨房卫浴
数码产品	数码产品
配件器材	配件器材
电商	电视购物线上商城
现场勘查	现场勘查
快递业务	快递配送
其他	其他

# Res.order_status `Enum`

配送状态。

枚举值	描述
101	配送公司接单阶段——等待分配骑手，即初始状态
102	配送公司接单阶段——分配骑手成功
103	配送公司接单阶段——商家取消订单，订单结束
201	骑手取货阶段——骑手到店开始取货
202	骑手取货阶段——取货成功
203	骑手取货阶段——取货失败，商家取消订单，订单结束
204	骑手取货阶段——取货失败，骑手因自身原因取消订单，订单结束
205	骑手取货阶段——取货失败，骑手因商家原因取消订单，订单结束
301	骑手配送阶段——配送中
302	骑手配送阶段——配送成功，订单结束
303	骑手配送阶段——商家取消订单，配送物品开始返还商家
304	骑手配送阶段——无法联系收货人，配送物品开始返还商家
305	骑手配送阶段——收货人拒收，配送物品开始返还商家
401	骑手返回配送货品阶段——货品返还商户成功，订单结束
501	因运力系统原因取消，订单结束
502	因不可抗拒因素（天气，道路管制等原因）取消，订单结束

# 5. 注意事项

# 使用场景举例

商家可调用本接口向配送公司请求下配送单，配送公司会返回这一单的配送单号、配送费、预计骑手接单时间等信息。
如遇下单错误，请先确认一下编码方式，python建议 json.dumps(b, ensure_ascii=False)，php建议 json_encode($arr, JSON_UNESCAPED_UNICODE) 可预约时间：达达：72小时内，闪送2小时以后，48小时以内。

# 商家接入准备

小程序进行微信认证
开通事件推送，设置事件地址：登录小程序后台，开发->开发设置->消息推送->启用
消息加密方式使用安全模式，数据格式选JSON
如果授权给第三方，则不需要步骤2
在配送公司注册账号，并在小程序后台进行授权绑定

# 名称解释

appkey: 一般为商家在登录配送公司开放平后分配的相应的appkey值
AppSecret: 一般为商家在登录配送公司开放平后分配的相应的秘钥
shopid：微信平台字段，对应配送公司的appkey
shop_no：商家对不同门店进行的编号，需要在配送公司系统有过登记，比如商家自己门店系统中有100个门店，编号是1-100，在顺丰同城的系统中有登记过这100个门店，且在顺丰同城登记的编号也是1-100，那么下单的时候传shop_no=1，就是编号为1 的门店下的配送单
shop：下单请求的一个字段，商家信息，会展示到物流通知消息中，如下图所示
下单请求的取货码和收货码：取货码是指骑手在商家这里取货时，商家出示取货码，骑手才能完成取货；收货码指骑手送达给用户时，用户出示收货码，骑手才算配送完成。商家可在配送公司开放平台设置是否需要开启取货码和收货码

# 调用api接口说明

编码方式：UTF-8
数据格式：JSON
提交方式：POST
下单需要使用绑定的shopid和AppSecret，其中shopid即配送公司账号的appkey，AppSecret即配送公司账号对应的秘钥
resultcode错误码和resultmsg错误描述由运力方定义，微信侧负责透传，只统一定义code=0表示成功
除了平台本身的加解密和签名，和订单相关的请求还需要带上运力侧签名delivery_sign，签名规则为
如果接口请求里有字段shop_order_id ，则delivery_sign=SHA1(shopid + shop_order_id + AppSecret)，其中shopid对应运力侧的appkey，shop_order_id对应订单id，AppSecret即配送公司账号对应的秘钥
如果请求里没有字段shop_order_id ，则delivery_sign=SHA1(shopid + AppSecret)，其中shopid对应运力侧的appkey，AppSecret即配送公司账号对应的秘钥
示例：shopid=“test_shop_id”，shop_order_id =“test_shop_order_id”， AppSecret=“test_app_secrect”，则delivery_sign=“a93d8d6bae9a9483c1b1d4e8670e7f6226ec94cb”

# 关于 order_status 枚举值说明

最终状态包括成功状态302，失败状态: 103,203,204,205,401,501,502。
当状态更新时，我们会在关键节点给收件用户推送服务通知，告知配送状态，同一配送单常态下会收到三条通知，即【骑手已接单】、【骑手已取货，配送中】、【配送已完成】，配送异常时会下发【配送异常】服务通知。

# 不同服务通知对应的 order_status 枚举值为

服务通知	对应的order_status值
骑手已接单	102
骑手已取货，配送中	202或301
配送已完成	302
配送异常	203、204、205、303、304、305、501、502

# 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.15296,
    "lng": 116.50603,
    "name": "老王",
    "phone": "18512345678"
  },
  "sender": {
    "address": "xx大厦",
    "address_detail": "1号楼101",
    "city": "北京市",
    "coordinate_type": 0,
    "lat": 40.448612,
    "lng": 116.383075,
    "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",
  "delivery_token": "xxxxxxxx"
}

返回示例

{
  "resultcode": 0,
  "resultmsg": "ok",
  "fee": 10,
  "deliverfee": 10,
  "couponfee": 0,
  "tips": 0,
  "insurancfee": 0,
  "distance": 1000,
  "waybill_id": "123456789",
  "order_status": 101,
  "finish_code": 1024,
  "pickup_code": 2048,
  "dispatch_duration": 300
}

# 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.15296,
    "lng": 116.50603,
    "name": "老王",
    "phone": "18512345678"
  },
  "sender": {
    "address": "xx大厦",
    "address_detail": "1号楼101",
    "city": "北京市",
    "coordinate_type": 0,
    "lat": 40.448612,
    "lng": 116.383075,
    "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",
  "delivery_token": "xxxxxxxx"
}

返回示例

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

# 7. 错误码

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

错误码	错误描述	解决方案
40001	invalid credential access_token isinvalid or not latest	获取 access_token 时 AppSecret 错误，或者 access_token 无效。请开发者认真比对 AppSecret 的正确性，或查看是否正在为恰当的公众号调用接口
930555	微信平台系统错误
930556	配送公司超时
930557	配送公司系统错误
930558	配送公司逻辑错误
930559	openid无效
930560	未绑定的商户号
930561	参数错误
930562	配送单已经存在
930563	配送单不存在
930564	调用无配额
930565	配送单已结束
9300535	shop字段商品缩略图 url、商品名称为空或者非法，或者商品数量为0

# 8. 适用范围

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