• 对接前说明
    • API调用协议
    • 接口参数介绍
    • 安全规范
    • 下载demo
  • API列表
    • 订单创建(门店方式)
    • 订单创建(送货分拣方式)
    • 取消订单
    • 查询订单状态
    • 订单状态回调
    • 订单异常回调
    • 评价骑手
    • 配送能力校验
    • 获取骑手当前位置
    • 查询合作方配送范围
    • 配送范围变更回调
  • 联调说明
    • 联调流程介绍
    • 订单测试接口
    • 门店范围变更回调测试
  • 附录
    • 请求返回状态码定义
    • 城市id列表
    • 订单取消原因列表
    • 订单状态代码列表
  • 订单创建(门店方式)接口迁移步骤
    • 迁移前提
    • 迁移步骤
  • 常见问题
    • 订单在未完成以前的所有状态都能取消吗?
    • 什么情况下订单会改派骑手?
    • 美团配送在什么情况下会取消订单?
    • 美团配送开放平台的测试地址是什么?
API调用协议

调用流程

合作方调用配送开放平台API,需要按照以下步骤:填充参数 > 生成签名 > 拼装HTTP请求 > 发起HTTP请求> 得到HTTP响应 > 解释json结果

请求规则

规则名称 描述
请求地址 https://peisongopen.meituan.com/api
传输协议 采用HTTPS
请求方式 POST
参数格式 application/x-www-form-urlencoded
字符编码 统一采用UTF-8字符编码

返回值规则

规则名称 描述
数据格式 application/json
字符编码 统一采用UTF-8字符编码
数据结构
{
	"code": 状态代码,
	"message": 描述信息,
	"data": 返回数据信息
}

详细状态码定义请参照 请求返回状态码定义

接口参数介绍

配送开放平台API请求参数分为两种。访问API接口时需要同时提供两种参数。

系统参数:必传,包含appkey,签名,时间戳,接口版本信息

应用参数:请参照具体接口的参数定义 API列表

系统参数介绍

参数名称 参数类型 参数描述
appkey String 配送开放平台为每个合作方分配独立的appkey,作为合作方接入认证标识。每个appkey会绑定一个secret,用于计算签名。请妥善保管secret,避免泄密。如果secret意外泄露,可要求重新生成。
timestamp long 时间戳,格式为long,时区为GMT+8,即合作方调用接口时距离Epoch(1970年1月1日) 以秒计算的时间(unix-timestamp)。开放平台允许合作方请求最大时间误差为10分钟(配送开放平台接到请求的时间 - 合作方调用接口的时间 < 10分钟)。
version String API协议版本,可选值:1.0。
sign String API请求参数的签名计算结果。

业务参数介绍

具体请参照 API列表各接口的参数定义。

安全规范

签名算法

为了防止API调用过程中被黑客恶意篡改,调用任何一个API都需要携带签名,开放平台服务端会根据请求参数,对签名进行验证,签名不合法的请求将会被拒绝。

1)将所有系统参数及业务参数(其中sign,byte[]及值为空的参数除外)按照参数名的字典顺序排序

2)将参数以参数1值1参数2值2...的顺序拼接,例如a=&c=3&b=1,变为b1c3,参数使用utf-8编码

3)按照secret + 排序后的参数的顺序进行连接,得到加密前的字符串

4)对加密前的字符串进行sha1加密并转为小写字符串,得到签名

5)将得到的签名赋给sign作为请求的参数

假设请求参数如下

secret: test

系统参数:

appkey=test

timestamp=1477395862

version=1.0

应用参数:

number=123

string=测试

double=123.123

boolean=true

empty=

加密前的字符串为

testappkeytestbooleantruedouble123.123number123string测试timestamp1477395862version1.0

sha1计算所得sign为

8943ba698f4b009f80dc2fd69ff9b313381263bd

以java举例,签名算法代码如下

// 所有参数按参数名排序
Set<String> keySet = paramMap.keySet();
List<String> keyList = new ArrayList<>(keySet);
Collections.sort(keyList);
 
// 加密前字符串拼接
StringBuilder signStr = new StringBuilder();
for (String key : keyList) {
    if (key.equals( "sign" )) {
       continue ;
    }
 
    Object value = paramMap.get(key);
    if (value == null || (value.getClass().isArray() && byte . class .isAssignableFrom(value.getClass().getComponentType()))) {
       continue ;
    }
 
    String valueString = value.toString();
 
    if (StringUtils.isEmpty(valueString)) {
       continue ;
    }
    signStr.append(key).append(value);
}
 
// 计算SHA1签名
String sign = SHA1Util.Sha1( "test" + signStr.toString()).toLowerCase();
下载demo

为提升对接效率,可以参考如下demo:

demo-Java版本
订单创建(坐标方式)

合作方将订单发送给美团配送平台。

此接口为已废弃的发单模式,未来将不再支持。

推荐未接入的合作方使用 订单创建(门店方式)接口。

已接入的合作方请逐步迁移到 订单创建(门店方式),迁移步骤详见 订单创建(门店方式)接口迁移步骤。

方法名:order/create

参数名称 参数类型 是否必须 参数描述
delivery_id long 即配送活动标识,由外部系统生成,不同order_id应对应 不同的delivery_id,若因美团系统故障导致发单接口失 败,可利用相同的delivery_id重新发单,系统视为同一次 配送活动,若更换delivery_id,则系统视为两次独立配送 活动。
order_id String

订单id,即该订单在合作方系统中的id,最长不超过32个字符

注:目前若某一订单正在配送中(状态不为取消),再次发送同一订单 (order_id相同)将返回同一mt_peisong_id

city_id int 城市id,详见下表
delivery_service_code int 配送服务代码,详情见合同
sender_name String 发货方名称,最长不超过256个字符
sender_address String 发货方地址,最长不超过512个字符
sender_phone String 发货方电话,最长不超过64个字符
sender_lng int 发货方经度(高德坐标),高德坐标*10^6
sender_lat int 发货方纬度(高德坐标),高德坐标*10^6
receiver_name String 收件人名称,最长不超过256个字符
receiver_address String 收件人地址,最长不超过512个字符
receiver_phone String 收件人电话,最长不超过64个字符
receiver_lng int 收件人经度(高德坐标),高德坐标*10^6
receiver_lat int 收件人纬度(高德坐标),高德坐标*10^6
goods_category int

货物品类,可选品类为

10:快餐外卖,20:水果,30:生鲜,40:快递

goods_value double 货物价格,单位为元,精确到小数点后两位,范围为0-99999999.99
goods_height double 货物高度,单位为cm,精确到小数点后两位,范围为0-99999999.99
goods_width double 货物宽度,单位为cm,精确到小数点后两位,范围为0-99999999.99
goods_length double 货物长度,单位为cm,精确到小数点后两位,范围为0-99999999.99
goods_weight double 货物重量,单位为kg,精确到小数点后两位,范围为0-99999999.99
goods_detail String

货物详情,最长不超过10240个字符,内容为JSON格式,示例如下:

{"goods":[{"goodCount":1,"goodName":"货品名称","goodPrice":9.99,单位为元,"goodUnit":"个"}]

其中,goods对应货物列表;goodCount表示货物数量,int类型;goodName表示货品名称,String类型;goodPrice表示货品单价,double类型;goodUnit表示货品单位,String类型。

强烈建议提供,方便骑手在取货时确认货品信息

goods_pickup_info String 货物取货信息,用于骑手到店取货,最长不超过100个字符
goods_delivery_info String 货物交付信息,最长不超过100个字符
expected_pickup_time long 期望取货时间,时区为GMT+8,当前距离 Epoch(1970年1月1日) 以秒计算的时间,即unix-timestamp。
expected_delivery_time long 期望送达时间,时区为GMT+8,当前距离 Epoch(1970年1月1日) 以秒计算的时间,即unix-timestamp。
order_type int

订单类型,默认为0

0: 即时单(尽快送达,限当日订单)

1: 预约单

poi_seq String 门店订单流水号,建议提供,方便骑手门店取货
note String 备注,最长不超过200个字符。
cash_on_delivery double 骑手应付金额,单位为元,精确到分【预留字段】
cash_on_pickup double 骑手应收金额,单位为元,精确到分【预留字段】
invoice_title String 发票抬头,最长不超过256个字符【预留字段】

返回信息:

成功返回{"code":0, data: {"mt_peisong_id": 美团配送内部订单id, "delivery_id": 配送活动标识, "order_id": 外部订单id}}
失败返回{"code":错误码, "message": 错误描述}

订单创建(门店方式)

合作方根据已录入的门店信息 将订单发送给美团配送平台。

方法名:order/createByShop

参数名称 参数类型 是否必须 参数描述
delivery_id long 即配送活动标识,由外部系统生成,不同order_id应对应不同的delivery_id,若因美团系统故障导致发单接口失败,可利用相同的delivery_id重新发单,系统视为同一次配送活动,若更换delivery_id,则系统视为两次独立配送活动。
order_id String

订单id,即该订单在合作方系统中的id,最长不超过32个字符

注:目前若某一订单正在配送中(状态不为取消),再次发送同一订单(order_id相同)将返回同一mt_peisong_id

shop_id String

取货门店id,即合作方向美团提供的门店id

注:测试门店的shop_id固定为 test_0001 ,仅用于对接时联调测试。

delivery_service_code int

配送服务代码,详情见合同

飞速达:4002

快速达:4011

及时达:4012

集中送:4013

receiver_name String 收件人名称,最长不超过256个字符
receiver_address String 收件人地址,最长不超过512个字符
receiver_phone String 收件人电话,最长不超过64个字符
receiver_lng int 收件人经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用),坐标 * (10的六次方),如 116398419
receiver_lat int 收件人纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用),坐标 * (10的六次方),如 39985005
coordinate_type int 坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标 (默认值为0)
goods_value double 货物价格,单位为元,精确到小数点后两位,范围为0-5000
goods_height double 货物高度,单位为cm,精确到小数点后两位,范围为0-45
goods_width double 货物宽度,单位为cm,精确到小数点后两位,范围为0-50
goods_length double 货物长度,单位为cm,精确到小数点后两位,范围为0-65
goods_weight double 货物重量,单位为kg,精确到小数点后两位,范围为0-50
goods_detail String

货物详情,最长不超过10240个字符,内容为JSON格式,示例如下:

{
"goods":[
    {
      "goodCount": 1,
      "goodName": "货品名称",
      "goodPrice": 9.99,
      "goodUnit": "个"
    }
  ]
}
goods对应货物列表;
goodCount表示货物数量,int类型,必填且必须大于0;
goodName表示货品名称,String类型,必填且不能为空;
goodPrice表示货品单价,double类型,选填,数值不小于0;
goodUnit表示货品单位,String类型,选填,最长不超过20个字符。
强烈建议提供,方便骑手在取货时确认货品信息
goods_pickup_info String 货物取货信息,用于骑手到店取货,最长不超过100个字符
goods_delivery_info String 货物交付信息,最长不超过100个字符
expected_pickup_time long 期望取货时间,时区为GMT+8,当前距离Epoch(1970年1月1日) 以秒计算的时间,即unix-timestamp。
expected_delivery_time long

即时单(除当天送):否

预约单:是

期望送达时间,时区为GMT+8,当前距离Epoch(1970年1月1日) 以秒计算的时间,即unix-timestamp

即时单:以发单时间 + 服务包时效作为期望送达时间(当天送服务包需客户指定期望送达时间)

预约单:以客户传参数据为准

服务包 编码 即时单期望送达时间规则
飞速达 4002 发单时间+45mins
快速达 4011 发单时间+1h
及时达 4012 发单时间+2h
集中送 4013 发单时间+2h
order_type int

订单类型,默认为0

0: 即时单(尽快送达,限当日订单)

1: 预约单

poi_seq String 门店订单流水号,建议提供,方便骑手门店取货
note String 备注,最长不超过200个字符。
cash_on_delivery double 骑手应付金额,单位为元,精确到分【预留字段】
cash_on_pickup double 骑手应收金额,单位为元,精确到分【预留字段】
invoice_title String 发票抬头,最长不超过256个字符【预留字段】

返回信息:

成功返回

{
	"code":0,
	"data": {
		"mt_peisong_id": 美团配送内部订单id,
		"delivery_id": 配送活动标识,
		"order_id": 外部订单id
	}
}

失败返回

{
	"code":错误码,
	"message": 错误描述
}
							
订单创建(送货分拣方式)

根据合作方的送件地址,自动选择合适的中间仓库作为线下货物的交接地点,并完成末端配送。

方法名:order/createByCoordinates

参数名称 参数类型 是否必须 参数描述
delivery_id long 即配送活动标识,由外部系统生成,不同order_id应对应 不同的delivery_id,若因美团系统故障导致发单接口失 败,可利用相同的delivery_id重新发单,系统视为同一次 配送活动,若更换delivery_id,则系统视为两次独立配送 活动。
order_id String

订单id,即该订单在合作方系统中的id,最长不超过32个字符

注:目前若某一订单正在配送中(状态不为取消),再次发送同一订单(order_id相同)将返回同一mt_peisong_id

delivery_service_code int

配送服务代码,详情见合同

飞速达:4002

快速达:4011

及时达:4012

集中送:4013

pick_up_type int

货物取货类型,目前只支持1

1:客户配送至站点

2:美团自取

receiver_name String 收件人名称,最长不超过256个字符
receiver_phone String 收件人电话,最长不超过64个字符
receiver_province String 收件人地址省,如上海市,江苏省
receiver_city String 收件人地址市,如上海市,南京市
receiver_country String 收件人地址区县,如静安区
receiver_town String 收件人地址街道,如宝山路街道
receiver_detail_address String 收件人地址详情,如永兴路365号
receiver_lng int 收件人经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用),坐标 * (10的六次方),如 116398419
receiver_lat int 收件人纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用),坐标 * (10的六次方),如 39985005
coordinate_type int 坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标 (默认值为0)
goods_value double 货物价格,单位为元,精确到小数点后两位,范围为0-5000
goods_height double 货物高度,单位为cm,精确到小数点后两位,范围为0-45
goods_width double 货物宽度,单位为cm,精确到小数点后两位,范围为0-50
goods_length double 货物长度,单位为cm,精确到小数点后两位,范围为0-65
goods_weight double 货物重量,单位为kg,精确到小数点后两位,范围为0-50
goods_detail String

货物详情,最长不超过10240个字符,内容为JSON格式,示例如下:

{
  "goods":[
    {
      "goodCount": 1,
      "goodName": "货品名称",
      "goodPrice": 9.99,
      "goodUnit": "个"
    }
  ]
}
goods对应货物列表;
goodCount表示货物数量,int类型,必填且必须大于0;
goodName表示货品名称,String类型,必填且不能为空;
goodPrice表示货品单价,double类型,选填,数值不小于0;
goodUnit表示货品单位,String类型,选填,最长不超过20个字符。
强烈建议提供,方便骑手在取货时确认货品信息
goods_pickup_info String 货物取货信息,用于骑手到店取货,最长不超过100个字符
goods_delivery_info String 货物交付信息,最长不超过100个字符
expected_pickup_time long 期望取货时间,时区为GMT+8,当前距离Epoch(1970年1月1日) 以秒计算的时间,即unix-timestamp。
expected_delivery_time long 期望送达时间,时区为GMT+8,当前距离Epoch(1970年1月1日) 以秒计算的时间,即unix-timestamp。
order_type int

订单类型,目前只支持预约单

0: 及时单(尽快送达,限当日订单)

1: 预约单

poi_seq String 门店订单流水号,建议提供,方便骑手门店取货
note String 备注,最长不超过200个字符。

返回信息:

成功返回

{
  "code": 0,
  "data": {
    "mt_peisong_id": 美团配送内部订单id,
    "delivery_id": 配送活动标识,
    "order_id": 外部订单id,
    "road_area": 路区信息,
    "destination_id": 目的地信息
  }
}
							

失败返回

{
	"code":错误码,
	"message": 错误描述
}
取消订单

订单在未完成状态下,合作方可以取消订单。

方法名:order/delete

参数名称 参数类型 是否必须 参数描述
delivery_id long 配送活动标识
mt_peisong_id String 美团配送内部订单id,最长不超过32个字符
cancel_reason_id int
取消原因类别,默认为接入方原因
cancel_reason String 详细取消原因,最长不超过256个字符

返回信息:

成功返回

{
	"code":0,
	"data": {
		"mt_peisong_id": 美团配送内部订单id,
		"delivery_id": 配送活动标识,
		"order_id": 外部订单id
	}
}

失败返回

{
	"code":错误码,
	"message": 错误描述
}

注:如果订单已配送完成,则返回错误

查询订单状态

查询订单状态及对应的骑手信息

方法名:order/status/query

参数名称 参数类型 是否必须 参数描述
delivery_id long 配送活动标识
mt_peisong_id String 美团配送内部订单id,最长不超过32个字符

返回信息:

成功返回

{
	"code":0,
	"data": 订单状态信息
}

data 格式如下:

参数名称 参数类型 是否必须 参数描述
delivery_id long 配送活动标识
mt_peisong_id String 美团配送内部订单id,最长不超过32个字符
order_id String 外部订单号,最长不超过32个字符
status int

状态代码,可选值为

0:待调度

20:已接单

30:已取货

50:已送达

99:已取消

operate_time int 订单状态变更时间,格式为unix-timestamp
courier_name String 配送员姓名(订单已被骑手接单后会返回骑手信息)
courier_phone String 配送员电话(订单已被骑手接单后会返回骑手信息)
cancel_reason_id int 取消原因id,详情请参考 美团配送开放平台接口文档--门户页面-4.3,订单取消原因列表
cancel_reason String 取消原因详情,最长不超过256个字符

返回信息:

失败返回

{
	"code":错误码,
	"message": 错误描述
}
订单状态回调

每次订单状态发生变化时,会对合作方提供的回调url进行回调。

注:回调url必须使用80或8080端口

签名算法

跟配送平台签名算法一致。使用配送平台的appkey跟secret做签名计算。

成功与重试

回调根据http响应码为200且返回{"code":0} 判断为成功,否则为失败

若第一次回调失败,会在10分钟内重试5次,且每次重试时间间隔逐步延长

若5次重试全部失败,会在之后每小时重试一次,直到当天结束。

回调接口说明

请求方式:post

请求格式:application/x-www-form-urlencoded

参数名称 参数类型 是否必须 参数描述
delivery_id long 配送活动标识
mt_peisong_id String 美团配送内部订单id,最长不超过32个字符
order_id String 外部订单号,最长不超过32个字符
status int 状态代码,可选值为

0:待调度

20:已接单

30:已取货

50:已送达

99:已取消

回调接口的订单状态改变可能会跳过中间状态,比如从待调度状态直接变为已取货状态。

订单状态不会回流。即订单不会从已取货状态回到待调度状态。

订单状态为“已接单”和“已取货”时,如果当前骑手不能完成配送,会出现改派操作,例如:将订单从骑手A改派给骑手B,由骑手B完成后续配送,因此会出现同一订单多次返回同一状态不同骑手信息的情况”

courier_name String 配送员姓名(已接单,已取货状态的订单,配送员信息可能改变)
courier_phone String 配送员电话(已接单,已取货状态的订单,配送员信息可能改变)
cancel_reason_id int 取消原因id,详情参考 美团配送开放平台接口文档--门户页面-4.3,订单取消原因列表
cancel_reason String 取消原因详情,最长不超过256个字符
appkey String 开放平台分配的appkey,合作方唯一标识。
timestamp long 时间戳,格式为long,时区为GMT+8,当前距 离Epoch(1970年1月1日) 以秒计算的时间,即 unix-timestamp。
sign String 数据签名
订单异常回调

每次配送员上报订单异常(如商家未营业、顾客留错电话等等)时,会对合作方提供的异常回调url进行回调。

注:回调url必须使用80或8080端口

签名算法

跟配送平台签名算法一致。使用配送平台的appkey跟secret做签名计算。

成功与重试

回调根据http响应码为200且返回{"code":0} 判断为成功,否则为失败

若第一次回调失败,会在10分钟内重试5次,且每次重试时间间隔逐步延长

若5次重试全部失败,会在之后每小时重试一次,直到当天结束。

回调接口说明

请求方式:post

请求格式:application/x-www-form-urlencoded

参数名称 参数类型 是否必须 参数描述
delivery_id long 配送活动标识
mt_peisong_id String 美团配送内部订单id,最长不超过32个字符
order_id String 外部订单号,最长不超过32个字符
exception_id long 异常ID,用来唯一标识一个订单异常信息。接入方用此字段用保证接口调用的幂等性。
exception_code int

订单异常代码,当前可能的值为:

10001:顾客电话关机

10002:顾客电话已停机

10003:顾客电话无人接听

10004:顾客电话为空号

10005:顾客留错电话

10006:联系不上顾客其他原因

10101:顾客更改收货地址

10201:送货地址超区

10202:顾客拒收货品

10203:顾客要求延迟配送

10401:商家关店/未营业

exception_descr String 订单异常详细信息
exception_time long 配送员上报订单异常的时间,格式为long,时区为GMT+8,距离Epoch(1970年1月1日) 以秒计算的时间,即unix-timestamp。
courier_name String 上报订单异常的配送员姓名
courier_phone String 上报订单异常的配送员电话
appkey String 开放平台分配的appkey,合作方唯一标识。
timestamp long 时间戳,格式为long,时区为GMT+8,当前距 离Epoch(1970年1月1日) 以秒计算的时间,即 unix-timestamp。
sign String 数据签名
评价骑手

接口功能说明

为了将合作方端的顾客对骑手的评价及时反馈给美团,提高美团侧的配送质量,海葵开放平台提供了对骑手的评价接口。合作方可以将顾客对骑手的评价信息通过此接口反馈给美团,同时需要注意以下几点:

1. 因各合作方的评分规则和量级的差异化,目前此接口传入的评分不作为骑手的考量参考(评分字段作为预留),仅评价信息会作为对骑手的反馈信息;

2. 仅接受已完成订单的评价, 未完成及删除的订单不接受评价;

3. 每笔订单只可进行一次评价,不允许重复评价;

接口说明

方法名:order/evaluate

请求方式:post

请求格式:application/x-www-form-urlencoded

请求参数:key = value形式

参数名称 参数类型 是否必须 参数描述
delivery_id long 配送活动标识
mt_peisong_id String 美团配送内部订单id,最长不超过32个字符
score int

评分(5分制)

预留参数,不作为骑手反馈参考

合作方需传入0-5之间分数或者不传,否则报错

comment_content String 评论内容(评论的字符长度需小于1024)

返回信息

失败返回

{
	"code":错误码,
	"message": 错误描述
}

成功返回

{
	"code":0,
	"data": 订单状态信息
}

data 格式如下:

参数名称 参数类型 是否必须 参数描述
delivery_id long 配送活动标识
mt_peisong_id String 美团配送内部订单id,最长不超过32个字符
order_id String 外部订单号,最长不超过32个字符
配送能力校验

根据合作方提供的模拟发单参数,确定美团是否可配送。主要校验项:门店是否存在、门店配送范围、门店营业时间、门店支持的服务包。

方法名:order/check

参数名称 参数类型 是否必须 参数描述
shop_id String

取货门店 id,即合作方向美团提供的门店 id。

注:测试门店的 shop_id 固定为 test_0001,仅用于对接时联调测试。

delivery_service_code int

配送服务代码,详情见合同

飞速达: 4002

快速达: 4011

及时达: 4012

集中送: 4013

receiver_address String 收件人地址,最长不超过 512 个字符
receiver_lng int 收件人经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用),坐标 * (10的六次方),如 116398419
receiver_lat int 收件人纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用),坐标 * (10的六次方),如 39985005
coordinate_type int 坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标 (默认值为0)
check_type int 预留字段,方便以后扩充校验规则,check_type = 1
mock_order_time long 模拟发单时间,时区为 GMT+8,当前距离 Epoch(1970年1月1日) 以秒计算的时间,即 unix-timestamp。

返回信息

成功返回

{
	"code":0,
	"message": "校验通过",
	"data": ""
}

失败返回

{
	"code": 错误码,
	"message": "错误描述"
}
获取骑手当前位置

接口功能说明

通过订单 id 获取当前订单下骑手的实时位置信息,需要注意以下几点:

1. 骑手位置的更新频率为 30s;

2. 接口返回的骑手坐标为火星坐标(高德地图和腾讯地图均采用火星坐标),而非百度坐标;

3. 接口返回的坐标量级为真实坐标的基础上乘以 10 的 6 次方的整数,例如:骑手真实坐标为(116.255596, 40.029185),则接口返回结果为(116255596, 40029185);

4. 订单状态只有为“已接单”和“已取货”时,才会返回骑手位置信息,接口返回结果与订单状态的对应关系如下:

订单状态码 订单状态描述 是否返回位置信息 错误码 返回结果
0 待调度 129 返回错误信息:“订单未调度,请分配骑手后重试”
10 已调度 132 返回错误信息:“骑手目前没有位置信息,请稍后重试”
20 已接单 - 返回获取成功的骑手位置信息
30 已取货 - 返回获取成功的骑手位置信息
50 已送达 130 返回错误信息:“订单已送达,无法获取位置信息”
99 已取消 131 返回错误信息:“订单已取消,无法获取位置信息”

接口说明

方法名:order/rider/location

请求方式:post

请求格式:application/x-www-form-urlencoded

请求参数:key = value 形式

参数名称 参数类型 是否必须 参数描述
delivery_id long 配送活动标识
mt_peisong_id String 美团配送内部订单 id,最长不超过 32 个字符

返回信息:

成功返回:

{
	"code": 0,
	"data": {
		"lat": 40029185, //纬度
		"lng": 116255596 //经度
	}
}

失败返回

{
	"code": 错误码,
	"message": "错误描述"
}
查询合作方配送范围

接口功能说明

根据配送服务代码、取货门店id获取该门店支持的配送范围。

接口说明

方法名:shop/area/query

请求方式:post

请求格式:application/x-www-form-urlencoded

请求参数:key = value 形式

参数名称 参数类型 是否必须 参数描述
delivery_service_code int 配送服务代码
shop_id String 取货门店id

返回信息:

失败返回{"code":错误码, "message": 错误描述}

成功返回{"code":0, data: 门店范围信息}

data 格式如下:

参数名称 参数类型 是否必须 参数描述
scope String

门店配送范围

例:[{"x":31.305655,"y":96.954307},

{"x":31.237576,"y":97.025718},

{"x":31.327946,"y":97.158928},

{"x":31.35375,"y":97.006492}]

配送范围变更回调

每次美团运营新增、修改配送范围时,会对合作方提供的配送范围变更回调url进行回调。

注:回调url必须使用80或8080端口

签名算法

跟配送平台签名算法一致。使用配送平台的appkey跟secret做签名计算。

成功与重试

回调根据http响应码为200且返回{"code":0} 判断为成功,否则为失败。

若回调失败,会在之后每小时重试一次,直到当天结束。

回调接口说明

请求方式:post

请求格式:application/x-www-form-urlencoded

参数名称 参数类型 是否必须 参数描述
delivery_service_code int 配送服务代码
shop_id String 取货门店id
scope String

门店配送范围

例:[{"x":31.305655,"y":96.954307},

{"x":31.237576,"y":97.025718},

{"x":31.327946,"y":97.158928},

{"x":31.35375,"y":97.006492}]

appkey String 开放平台分配的appkey,合作方唯一标识。
timestamp long 时间戳,格式为long,时区为GMT+8,当前距离Epoch(1970年1月1日) 以秒计算的时间,即unix-timestamp。
sign String 数据签名
联调流程介绍

合作方联调请按照以下流程:

1,提前通知美团工作人员联调计划与时间,并告知测试回调地址

2,美团工作人员会按照时间发放并启用测试appkey及secret

3,使用测试appkey及secret测试创建订单,删除订单及查询订单接口

4,测试创建订单及删除订单时,请注意是否收到能正确回调消息。若不能收到,请与美团工作人员联系

5,若需要测试其他订单状态,请使用订单测试接口模拟订单状态。

6,联调至少需要测试 发单接口,取消接口以及配送状态回调

7,联调完成后,需要通过美团工作人员验收之后,才能发布上线,验收流程如下

  1. 1.使用测试账号,创建一个测试订单,验证创建订单成功
  2. 2.使用模拟接单及模拟取货接口,验证回调成功
  3. 3.取消该测试订单,验证取消订单成功
  4. 4.请将该测试订单的订单号告知美团工作人员,执行对接验收工作
订单测试接口

若合作方需要测试订单调度的回调消息,可使用以下接口模拟改变订单状态

接口名称 接口地址 描述
模拟接单 /api/test/order/arrange 模拟骑手接受该订单,订单状态变为已接单
模拟取货 /api/test/order/pickup 模拟骑手到店并完成取货,订单状态变为已取货
模拟送达 /api/test/order/deliver 模拟骑手将货物送达客户手中,订单状态变为已完成
模拟改派 /api/test/order/rearrange 模拟骑手因故不能继续配送订单,站长将改派另一骑手继续配送此订单,订单状态不变。
模拟上传异常 /api/test/order/reportException 模拟骑手上传异常,回调合作方的回调地址,将异常信息发送给合作方。

请求参数(模拟url接口与正常API接口一样,也需要附带系统参数及计算签名信息)

参数名 类型 必填 描述
delivery_id long 即配送活动标识,由外部系统生成,不同order_id应对应不同的delivery_id,若因美团系统故障导致发单接口失败,可利用相同的delivery_id重新发单,系统视为同一次配送活动,若更换delivery_id,则系统视为两次独立配送活动。
mt_peisong_id String 美团配送内部订单id,最长不超过32个字符

返回信息:

成功返回

{
	"code":0
}

失败返回

{
	"code": 错误码,
	"message":错误描述
}

注:此接口只适用于测试订单,若测试订单出现错误,则接口根据不同错误类型返回不同的原因,{"code":124, "message":"模拟操作失败,(括号内为下面对应的错误信息)"}

模拟操作错误信息:

代码 信息描述
1 系统错误,建议稍后重试或联系美团RD
2 订单不存在,建议检查参数是否正确
3 账号为非测试账号,不允许模拟操作
4 订单为非测试订单,不允许模拟操作
5 订单已取消,不允许模拟操作
6 送达时间有限制,取货后短时间内不允许点送达,建议稍后重试
7 操作越级,建议根据订单状态按顺序进行模拟操作
门店范围变更回调测试

若合作方需要测试门店配送范围变更的回调,可使用以下接口模拟门店配送范围变更

接口名称 接口地址 描述
模拟门店配送范围变更 /api/test/shop/area/callback 模拟门店配送范围变更

请求参数(模拟url接口与正常API接口一样,也需要附带系统参数及计算签名信息)

参数名 类型 必填 描述
shop_id String

取货门店id,即合作方向美团提供的门店id

注:测试门店的shop_id固定为 test_0001 ,仅用于对接时联调测试。

delivery_service_code int

配送服务代码,详情见合同

飞速达:4002

快速达:4011

及时达:4012

集中送:4013

返回信息:

成功返回

{
	"code":0
}

失败返回

{
	"code": 错误码,
	"message":错误描述
}

注:此接口只适用于测试模拟门店范围变更回调,若测试过程中出现错误,则接口根据不同错误类型返回不同的原因,{"code":124, "message":"模拟操作失败,(括号内为下面对应的错误信息)"}

模拟操作错误信息:

代码 信息描述
1 系统错误,建议稍后重试或联系美团RD
124 模拟操作失败
请求返回状态码定义

0为请求成功

1-99为平台错误

100以上为业务错误

代码 描述信息
0 成功
1 系统错误
2 缺少系统参数
3 缺少参数,数据不完整
4 参数格式错误
5 app_key不存在或合作方不合作
6 签名验证错误
7 没有权限操作这条数据
8 api版本号不支持
9 请求时间超出最大时限
10 当前ip不在可访问列表中
11 接口流控
100 订单id已创建配送订单
101 订单id正在创建配送订单
102 订单不存在
103 货品信息有误,金额过大,体积过大,重量过沉等
104 订单已完成,不能取消
105 订单预计完成时间不在可接受范围
106 所选城市未合作
107 所选配送服务类型无效
108 非合作时间
109 取货地址超区
110 送货地址超区
111 不在美团配送站点营业时间内
112 门店不存在
113 不在门店营业时间内
114 门店非营业状态
115 门店未开通所选服务包
116 超过所选服务包允许的时效限制
117 预约时间超出范围
118 订单类型不符合要求
119 门店不支持预约单
120 预约时间超出范围
121 门店不支持营业时间外发预订单
122 保价服务异常
123 价格缺失,无法投保
124 模拟操作失败
125 订单尚未完成,不允许进行评价操作
126 订单已评价,不允许重复评价
127 坐标方式发出的订单,不允许评价操作
128 所选位置暂未开通服务
129 订单未调度,请分配骑手后重试
130 订单已送达,无法获取位置信息
131 订单已取消,无法获取位置信息
132 骑手目前没有位置信息,请稍后重试
133 创建订单接口禁用中,请咨询您的销售经理
城市id列表
110000 北京 310000 上海 440300 深圳 440100 广州
210100 沈阳 340100 合肥 410100 郑州 510100 成都
210200 大连 500000 重庆 220100 长春 610100 西安
330200 宁波 120000 天津 350100 福州 370200 青岛
370100 济南 320500 苏州 320200 无锡 430100 长沙
460100 海口 320400 常州 530100 昆明 330100 杭州
350200 厦门 230100 哈尔滨 330782 义乌 420100 武汉
450100 南宁 410300 洛阳 360100 南昌 320100 南京
330700 金华 330300 温州 331000 台州 440600 佛山
210100 沈阳 340100 合肥 410100 郑州 510100 成都
441800 清远 140800 运城 230600 大庆 610900 安康
370400 枣庄 511000 内江 360900 宜春 211400 葫芦岛
440200 韶关 610700 汉中 411100 漯河 141000 临汾
620100 兰州 520100 贵阳 340200 芜湖 330600 绍兴
430600 岳阳 340700 铜陵 220600 白山 420800 荆门
230800 佳木斯 341200 阜阳 130500 邢台 430300 湘潭
130200 唐山 370600 烟台 130100 石家庄 320300 徐州
530700 丽江 210900 阜新 610500 渭南 450300 桂林
211200 铁岭 340300 蚌埠 445200 揭阳 231000 牡丹江
320600 南通 150100 呼和浩特 350500 泉州 140100 太原
150600 鄂尔多斯 411700 驻马店 220800 白城 431000 郴州
341100 滁州 520300 遵义 440900 茂名 420300 十堰
640100 银川 320800 淮安 130300 秦皇岛 370300 淄博
330900 舟山 511400 眉山 445100 潮州 511500 宜宾
410900 濮阳 350700 南平 210500 本溪 341300 宿州
320700 连云港 370700 潍坊 150200 包头 460200 三亚
150700 呼伦贝尔 210600 丹东 330500 湖州 220400 辽源
431100 永州 450400 梧州 411600 周口 150800 巴彦淖尔
630100 西宁 210300 鞍山 350300 莆田 330400 嘉兴
360700 赣州 410400 平顶山 360400 九江 421000 荆州
520600 铜仁 340800 安庆 511700 达州 430900 益阳
321100 镇江 410700 新乡 211000 辽阳 370800 济宁
340500 马鞍山 150400 赤峰 610400 咸阳 371600 滨州
430500 昭阳 411200 三门峡 360800 吉安 140700 晋中
130400 邯郸 430200 株洲 371300 临沂 321300 宿迁
340600 淮北 370500 东营 230300 鸡西 220500 通化
140300 阳泉 450800 贵港 140500 晋城 640200 石嘴山
441300 惠州 210800 营口 371000 威海 410200 开封
370900 泰安 371100 日照 441200 肇庆 341500 六安
420700 鄂州 371700 菏泽 431200 怀化 140900 忻州
652800 巴音郭楞 360200 景德镇 445300 云浮
130700 张家口 350600 漳州 321200 泰州 410500 安阳
421100 黄冈 610300 宝鸡 530400 玉溪 410800 焦作
620500 天水 340400 淮南 361000 抚州 130800 承德
620900 酒泉 441500 汕尾 532600 文山壮族
650100 乌鲁木齐 411400 商丘 510700 绵阳 331100 丽水
510300 自贡 231200 绥化 510500 泸州 440700 江门
341600 亳州 512000 资阳 360500 新余 510400 攀枝花
361100 上饶 542100 昌都 371200 莱芜 610200 铜川
440800 湛江 230200 齐齐哈尔 450200 柳州 320900 盐城
140400 长治 152200 兴安盟 511300 南充 350800 龙岩
420900 孝感 341000 黄山 350400 三明 441600 河源
360300 萍乡 530800 普洱 140600 朔州 450600 防城港
420500 宜昌 140200 大同 411300 南阳 222400 延边
450500 北海 220300 四平 420200 黄石 442000 中山
441400 梅州 540100 拉萨 610800 榆林 211300 朝阳
520400 安顺 610600 延安 431300 娄底 511800 雅安
131000 廊坊 411500 信阳 211100 盘锦 210700 锦州
411000 许昌 150500 通辽 420600 襄阳 511100 乐山
141100 吕梁 450900 玉林 410600 鹤壁 640300 吴中
130900 沧州 350900 宁德 150900 乌兰察布 341800 宣城
510900 遂宁 220700 松原 130600 保定 430400 衡阳
440500 汕头 510600 德阳 210400 抚顺 330800 横州
150300 乌海 450700 钦州 341700 池州 441700 阳江
653100 喀什 511600 广安 421300 随州 421200 咸宁
订单取消原因列表

客户取消订单原因

客户调用订单取消接口时可以选择的取消原因。

原因类别 代码 描述
接入方原因 101 顾客主动取消
102 顾客更改配送时间/地址
103 备货、包装、货品质量问题取消
199 其他接入方原因
美团配送原因 201 配送服务态度问题取消
202 骑手配送不及时
203 骑手取货不及时
299 其他美团配送原因
其他原因 399 其他原因

系统取消订单原因

美团配送系统在发生异常状况自动取消订单时使用的取消原因。

原因类别 代码 描述
接入方原因 1110 取货地址超区
1111 送货地址超区
1199 其他接入方原因
美团配送原因 1201 当前运力紧张,暂无骑手接单,建议稍后重新发单
1202 因骑手原因,订单被取消
1203 因系统原因,订单被取消,建议稍后重新发单
1299 其他美团配送原因
其他原因 1399 其他原因
订单状态代码列表
订单状态代码 订单状态描述
0 待调度
20 已接单
30 已取货
50 已送达
99 已取消
迁移前提

与订单创建(坐标方式)不同,订单创建(门店方式)面向签订服务包合同的客户。 所以在迁移前请确保与美团签订服务包合同。

迁移步骤

1、联系美团开发及业务人员,沟通迁移计划

2、联系美团业务人员,提供门店详细信息

3、将发单接口更改为 订单创建(门店方式),并使用门店详细信息中提供的门店id发单

4、联系美团业务人员,获取测试门店id

5、使用测试账号及测试门店id,联调测试

6、联调测试通过后,正式上线,迁移完成

订单在未完成以前的所有状态都能取消吗?

是的

什么情况下订单会改派骑手?

在少数情况下(如恶劣天气或骑手遇到突发情况),导致骑手已接单但却无法完成该订单,会出现订单改派骑手的情况 如果订单改派骑手,开放平台会重新发送一次订单状态改变消息,消息中订单状态不变,骑手信息更新

示例:
假设有订单1已被骑手A接单,因为骑手A遇到突发情况无法继续送货,站长改派骑手B继续送货,则发送的消息为:

{
  "sign": "d4b6fbe38dec53ce50e14fd14280b54bfb142c06",
  "timestamp": "1492338072",
  "delivery_id": "1621632",
  "status": "20", //已接单
  "appkey": "appkey",
  "courier_phone": "15900717353", // 骑手B电话
  "courier_name": "何伟", // 骑手B姓名
  "order_id": "123",
  "mt_peisong_id": "123"
}
美团配送在什么情况下会取消订单?

通常情况下,美团不会取消订单,除非遇到恶劣天气等不可抗因素导致美团运力不足的情况。 建议各合作方应自己实现取消订单功能,避免因订单无法取消造成货品损失。

美团配送开放平台的测试地址是什么?

美团配送开放平台的测试地址与线上地址一致,即https://peisongopen.meituan.com/api

测试环境与正式环境使用测试账号及线上账号区分

测试账号与正式账号可分别对应测试回调地址及正式回调地址