此文档内容已不再维护,请查看新文档
  • 对接前说明
    • API调用协议
    • 接口参数介绍
    • 安全规范
    • 下载demo
  • API列表
    • 订单创建(门店方式)
    • 订单创建(送货分拣方式)
    • 取消订单
    • 查询订单状态
    • 订单状态回调
    • 订单异常回调
    • 预发单接口
    • 获取配送码
    • 评价骑手
    • 配送能力校验
    • 获取骑手当前位置
    • 获取骑手位置H5
    • 增加小费接口
    • 查询门店配送范围
    • 配送范围变更回调
    • 配送风险等级变更回调
    • 门店创建
    • 门店修改
    • 查询门店信息
    • 门店状态回调
    • 配送员上下班打卡回调
    • 取餐码信息下发
    • 取件码、签收码回调
    • 图片上传接口文档
    • 门店履约信息变更回调
  • 联调说明
    • 联调流程介绍
    • 订单测试接口
    • 门店范围变更回调测试
    • 配送风险等级变更回调测试
    • 门店状态回调测试
    • 配送员上下班打卡回调测试
  • 附录
    • 请求返回状态码定义
    • 城市id列表
    • 订单取消原因列表
    • 订单状态代码列表
    • 品类代码列表
    • 新服务产品列表
    • 货品标准计量单位列表
  • 公告通知
    • 【重要通知】美团配送技术服务合作中心新增支付场景接口升级通知
  • 订单创建(门店方式)接口迁移步骤
    • 迁移前提
    • 迁移步骤
API调用协议

调用流程

合作方调用美团配送技术服务合作中心API,需要按照以下步骤:填充参数 > 生成签名 > 拼装HTTP请求 > 发起HTTP请求> 得到HTTP响应 > 解释json结果

流量控制

为保证系统稳定,针对每个接口都做了流量控制,如果接口请求的QPS大于设置的阈值,会返回 {"code":11,"message":"接口流控"},如果遇到流量控制,建议三次重试,每次间隔10秒。如需详细了解,联系美团技术。

注意:美团配送API(含联调测试API)不支持压测场景,禁止合作方压测场景直接调用美团配送API。

请求规则

规则名称 描述
请求地址 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个字符;若收件人是港澳台电话,请按{区号}_{手机号}输入,例:852_12345678。

地区 区号
香港 852
澳门 853
台湾 886
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": 错误描述}

订单创建(门店方式)

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

本接口暂不支持测试门店(test_0001)调试使用余额支付的订单,账期支付与余额支付的发单流程无差异,使用账期支付方式发单联调完成后即可上线。

流量控制

同一AppKey每秒超过40次访问将被限流,返回{"code":11,"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。若调用预发单接口后再创建订单时,请将order_id保持一致。

outer_order_source_desc String

订单来源:

101.美团(外卖&闪购)

102.饿了么

103.京东到家

105.抖音

201.商家web网站

202.商家小程序-微信

203.商家小程序-支付宝

204.商家APP

205.商家热线

其他,请直接填写中文字符串,最长不超过20个字符

非「其他」需传代码

outer_order_source_no String 原平台订单号,如订单来源为美团,该字段必填,且为美团平台生成的订单号,最长不超过32个字符
shop_id String

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

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

delivery_service_code int

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

1)服务包

飞速达:4002

快速达:4011

及时达:4012

集中送:4013

跑腿-帮送:4031

2)新服务产品

具体可参考新服务产品列表

receiver_name String 收件人名称,最长不超过256个字符
receiver_address String 收件人地址,最长不超过512个字符
receiver_phone String

收件人电话,最长不超过64个字符;收件人首要联系方式,只支持传输一个真实手机号码或隐私号;传输隐私号的分机号时,请保持英文“,”隔开;若收件人手机号是真实号码,可联系运营开通隐私号服务;不支持带*号的手机号码;若收件人是港澳台电话,请按{区号}_{手机号}输入,例:852_12345678。

地区 区号
香港 852
澳门 853
台湾 886
receiver_phone_spare String 备用手机号,最长不超过64个字符;收件人其他的真实手机号或有效隐私号,可支持至多2个备用手机号,需要通过英文“;”区分;传输隐私号格式请保持分机号英文“,”隔开(如:135XXXXXXX,XXXX)
receiver_lng int 收件人经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用),坐标 * (10的六次方),如 116398419
receiver_lat int 收件人纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用),坐标 * (10的六次方),如 39985005
coordinate_type int 坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标 (默认值为0)
delivery_qr_code String

配送码,示例:

{
	"business": "peisong-qrfetch",
	"content": "1623988921138003398"
}

若门店没有开通扫码配送服务,传值后则不处理,按照普通模式骑手履约;

若门店开通扫码配送服务,配送码未传值,同样按照普通模式骑手履约;

若门店开通扫码配送服务,并且配送码传值后校验配送码有效后,骑手按照扫码配送模式履约。

goods_value double

货物价格,单位为元,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为0-5000

跑腿-帮送服务包:范围0-3000

goods_height double 货物高度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为0-45
goods_width double 货物宽度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为0-50
goods_length double 货物长度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为0-65
goods_weight double

货物重量,单位为kg,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为0-50

跑腿-帮送服务包:范围0-20

goods_detail String

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

{
"goods":[
    {
      "goodCount": 1,
      "goodName": "货品名称",
      "goodPrice": 9.99,
			"goodUnit": "个",
			"goodUnitCode":"10008"
    }
  ]
}
goods对应货物列表;
goodCount表示货物数量,int类型,必填且必须大于0;
goodName表示货品名称,String类型,必填且不能为空;
goodPrice表示货品单价,double类型,选填,数值不小于0,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数);
goodUnit表示货品单位,String类型,选填,最长不超过20个字符;
goodUnitCode表示货品标准计量单位,String类型,有特殊计费模式商家请必传;若字段【goodUnit】与当前字段同时传值不一致时,则以当前货品标准计量单位为准;参照货品标准计量单位列表
强烈建议提供,方便骑手在取货时确认货品信息
goods_pickup_info String 货物取货信息,用于骑手到店取货,最长不超过100个字符
goods_delivery_info String 货物交付信息,最长不超过100个字符
expected_pickup_time long

非跑腿-帮送服务包:否

跑腿-帮送服务包-即时单:否

跑腿-帮送服务包-预约单:是

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

跑腿-帮送服务包预约单:发单后60分钟到次日23:50,10的倍数

跑腿-帮送服务包即时单:不允许设置此字段

expected_delivery_time long

即时单(除当天送):否

预约单:是

跑腿-帮送服务包:否

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

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

预约单:以客户传参数据为准(预约时间必须大于当前下单时间+服务包时效+3分钟)

跑腿-帮送服务包传此值不生效

1)服务包

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

2)新服务产品

具体可参考新服务产品列表

order_type int

订单类型,默认为0

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

1: 预约单

跑腿-帮送服务包预约单,会存在骑手提前接单的可能

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

加小费字段,加小费,精确到元,需要为1或1的倍数,上限20;

非跑腿-帮送服务包不支持

goods_code_switch int 收货码开关,默认为0,0=off,1=on,当收件人手机号为隐私号时,不支持收货码; 非跑腿-帮送服务包不支持
pay_type_code int

支付方式,0、账期支付,1、余额支付;

当前门店可支持的支付方式可以通过查询门店信息接口获取;选择余额支付时,建单成功后若账户余额扣款失败,则美团系统自动会发起订单取消;建单成功后会返回支付方式对应的付款方式。

coupons_id String

优惠券ID;

当前是否有可用优惠券可以通过配送能力校验接口获取;若传值,则会校验优惠券ID在当前时刻是否符合使用规则,若不传值,则不会使用优惠券。

返回信息:

成功返回

{
	"code":0,
	"data": data信息
}

data 格式如下:

参数名称 参数类型 是否必须 参数描述
mt_peisong_id String 美团配送内部订单id
delivery_id long 配送活动标识
order_id String 外部订单id
delivery_distance int 订单配送距离,单位为米,当前订单计算的配送距离
delivery_fee double 订单配送价格,单位为元,价格受距离、发单时间、配送高峰、特殊天气等不同计费因素影响
base_delivery_fee double 优惠可用金额,单位为元;使用余额支付时有值;总配送费仲可使用优惠券抵扣的部分配送费用,金额受到不同计费因素以及优惠券使用规则影响
pay_amount double 实际支付价格,单位为元;使用优惠券等扣减后价格;支付方式为账期时支付价格以账单为准
settlement_mode_code int 结算方式,1、实时结算,2、账期结算;账期结算下包含的支付方式为账期;实时结算下包含的支付方式为余额;后续会扩展多种支付方式
coupons_amount double

优惠券金额,单位为元;

当前订单创建时刻传入的优惠券且符合使用条件时则有值,反之无值或为0。

失败返回

{
	"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

outer_order_source_desc String

订单来源:

101.美团(外卖&闪购)

102.饿了么

103.京东到家

105.抖音

201.商家web网站

202.商家小程序-微信

203.商家小程序-支付宝

204.商家APP

205.商家热线

其他,请直接填写中文字符串,最长不超过20个字符

非「其他」需传代码

outer_order_source_no String 原平台订单号,如订单来源为美团,该字段必填,且为美团平台生成的订单号,最长不超过32个字符
delivery_service_code int

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

1)服务包

飞速达:4002

快速达:4011

及时达:4012

集中送:4013

2)新服务产品

具体可参考新服务产品列表

pick_up_type int

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

1:客户配送至站点

2:美团自取

receiver_name String 收件人名称,最长不超过256个字符
receiver_phone String

收件人电话,最长不超过64个字符;若收件人是港澳台电话,请按{区号}_{手机号}输入,例:852_12345678。

地区 区号
香港 852
澳门 853
台湾 886
receiver_province String 收件人地址省,如上海市,江苏省,最长不超过10个字符
receiver_city String 收件人地址市,如上海市,南京市,最长不超过10个字符
receiver_country String 收件人地址区县,如静安区,最长不超过10个字符
receiver_town String 收件人地址街道,如宝山路街道,最长不超过30个字符
receiver_detail_address String 收件人地址详情,如永兴路365号,最长不超过100个字符
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": "个",
			"goodUnitCode":"10008"
    }
  ]
}
goods对应货物列表;
goodCount表示货物数量,int类型,必填且必须大于0;
goodName表示货品名称,String类型,必填且不能为空;
goodPrice表示货品单价,double类型,选填,数值不小于0,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数);
goodUnit表示货品单位,String类型,选填,最长不超过20个字符;
goodUnitCode表示货品标准计量单位,String类型,有特殊计费模式商家请必传;若字段【goodUnit】与当前字段同时传值不一致时,则以当前货品标准计量单位为准;参照货品标准计量单位列表
强烈建议提供,方便骑手在取货时确认货品信息
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 门店订单流水号,建议提供,方便骑手门店取货,最长不超过32个字符
note String 备注,最长不超过200个字符。

返回信息:

成功返回

{
	"code":0,
	"data": data信息
}

data 格式如下:

参数名称 参数类型 是否必须 参数描述
mt_peisong_id String 美团配送内部订单id
delivery_id long 配送活动标识
order_id String 外部订单id
road_area String 路区信息
destination_id String 目的地信息
delivery_distance int 订单配送距离,单位为米,当前订单计算的配送距离
delivery_fee double 订单配送价格,单位为元,价格受距离、发单时间、配送高峰、特殊天气等不同计费因素影响

失败返回

{
	"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": 错误描述
}

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

查询订单状态

查询订单状态及对应的骑手信息(仅支持90天内产生的订单)

方法名:order/status/query

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

流量控制

同一AppKey每秒超过10次访问将被限流,返回{"code":11,"message":"接口流控"}。可以通过降低查询频次解决。

返回信息:

成功返回

{
	"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 long 订单状态变更时间,格式为unix-timestamp
predict_delivery_time String 订单预计送达时间
courier_name String 配送员姓名(订单已被骑手接单后会返回骑手信息)
courier_phone String 配送员电话(订单已被骑手接单后会返回骑手信息)
cancel_reason_id int 取消原因id,详情请参考 美团配送技术服务合作中心接口文档--门户页面-4.3,订单取消原因列表
cancel_reason String 取消原因详情,最长不超过256个字符
delivery_distance int 订单配送距离,单位为米
delivery_fee double 订单配送价格,单位为元
pay_amount double 实际支付价格,单位为元;使用优惠券等扣减后价格;支付方式为账期时支付价格以账单为准
settlement_mode_code init 结算方式,1、实时结算,2、账期结算;账期结算下包含的支付方式为账期;实时结算下包含的支付方式为余额;后续会扩展多种支付方式
coupons_amount double

优惠券金额,单位为元;

当前订单存在使用符合条件的优惠券则有值,反之无值或为0。

temperature string

配送员体温(单位:℃),示例值:36.4℃

根据当地防疫要求作相应透出,请勿用于其他目的,并根据相关法律法规进行个人信息保护。

meal_box_status string

配送员餐箱消毒状态:1-餐箱已消毒

根据当地防疫要求作相应透出,请勿用于其他目的,并根据相关法律法规进行个人信息保护。

nucleic_status string

配送员核酸状态:1-核酸阴性

根据当地防疫要求作相应透出,请勿用于其他目的,并根据相关法律法规进行个人信息保护。

vaccine_status string

配送员疫苗状态:1-已接种疫苗

根据当地防疫要求作相应透出,请勿用于其他目的,并根据相关法律法规进行个人信息保护。

health_code string

配送员健康码状态:1-健康绿码

根据当地防疫要求作相应透出,请勿用于其他目的,并根据相关法律法规进行个人信息保护。

pickup_goods_code string

取货码

delivery_goods_code string

收货码

返回信息:

失败返回

{
	"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个字符
predict_delivery_time String 订单预计送达时间
appkey String 美团配送技术服务合作中心分配的appkey,合作方唯一标识。
timestamp long 系统调用时间戳,格式为long,时区为GMT+8,当前距离Epoch(1970年1月1日) 以秒计算的时间,即 unix-timestamp。
sign String 数据签名
temperature string

配送员体温(单位:℃),示例值:36.4℃

根据当地防疫要求作相应透出,请勿用于其他目的,并根据相关法律法规进行个人信息保护。

meal_box_status string

配送员餐箱消毒状态:1-餐箱已消毒

根据当地防疫要求作相应透出,请勿用于其他目的,并根据相关法律法规进行个人信息保护。

nucleic_status string

配送员核酸状态:1-核酸阴性

根据当地防疫要求作相应透出,请勿用于其他目的,并根据相关法律法规进行个人信息保护。

vaccine_status string

配送员疫苗状态:1-已接种疫苗

根据当地防疫要求作相应透出,请勿用于其他目的,并根据相关法律法规进行个人信息保护。

health_code string

配送员健康码状态:1-健康绿码

根据当地防疫要求作相应透出,请勿用于其他目的,并根据相关法律法规进行个人信息保护。

operate_time long

订单状态变更时间,格式为unix-timestamp

订单异常回调

每次配送员上报订单异常(如商家未营业、顾客留错电话等等)时,会对合作方提供的异常回调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:顾客要求延迟配送

10301:商家出餐慢

10401:商家关店/未营业

10601:联系不上商家

10701:商家定位错误

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)

流量控制

同一AppKey每秒超过10次访问将被限流,返回{"code":11,"message":"接口流控"}。可以通过降低查询频次解决。

返回信息

失败返回

{
	"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

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

1)服务包

飞速达:4002

快速达:4011

及时达:4012

集中送:4013

2)新服务产品

具体可参考新服务产品列表

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。

流量控制

同一AppKey每秒超过30次访问将被限流,返回{"code":11,"message":"接口流控"}。如需要高频访问,可以通过【查询门店配送范围】接口将配送范围缓存到本地,然后利用缓存的配送范围进行配送能力校验。

返回信息

成功返回

{
	"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 已送达 - 返回获取成功的骑手送达位置信息
99 已取消 131 返回错误信息:“订单已取消,无法获取位置信息”

接口说明

方法名:order/rider/location

请求方式:post

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

请求参数:key = value 形式

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

流量控制

同一AppKey每秒超过40次访问将被限流,返回{"code":11,"message":"接口流控"}。可以通过降低查询频次解决。

返回信息:

成功返回:

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

失败返回

{
	"code": 错误码,
	"message": "错误描述"
}
增加小费接口

增加小费接口,目前只适用于4031服务包;根据订单支付方式进行扣款,若是支付方式为余额且余额不足时,增加小费失败。

方法名:order/addTip

参数名称 参数类型 是否必须 参数描述
delivery_id long

配送活动标识

mt_peisong_id String 美团配送内部订单id,最长不超过32个字符
tip_amount int

校验加小费金额,精确到元,需要为1或1的倍数,上限20

追加小费最多5次,+发单小费 总额上限为20

serial_number String 加小费传入的唯一标识,用来幂等处理,最长不超过128个字符

流量控制

同一AppKey每秒超过40次访问将被限流,返回{"code":11,"message":"接口流控"}。可以通过降低查询频次解决。

返回信息:

成功返回{"code":0, "message": "成功"}

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

查询门店配送范围

接口功能说明

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

接口说明

方法名:shop/area/query

请求方式:post

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

请求参数:key = value 形式

参数名称 参数类型 是否必须 参数描述
delivery_service_code int

配送服务代码

回传时区分 服务包code和新服务产品code

shop_id String 取货门店id

流量控制

同一AppKey每秒超过2次访问将被限流,返回{"code":11,"message":"接口流控"}。可以通过降低查询频次解决。

返回信息:

失败返回{"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 数据签名
配送风险等级变更回调

配送风险等级变更时,会对合作方提供的URL进行回调。(配送风险等级指的是受不可抗力如天气、交通管制等因素导致的配送失败可能性。配送风险等级0为正常,1-4即为出现风险或无法完成配送)

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

签名算法

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

成功与重试

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

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

回调接口说明

请求方式:post

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

参数名称 参数类型 是否必须 参数描述
shop_id String 取货门店id
delivery_risk_level int 配送风险等级
appkey String 美团配送技术服务合作中心分配的appkey,合作方唯一标识。
timestamp long 时间戳,格式为long,时区为GMT+8,当前距离Epoch(1970年1月1日) 以秒计算的时间,即unix-timestamp。
sign String 数据签名
门店创建

合作方提交门店信息(注意测试推单仍然用系统默认test_0001门店)

流量控制

同一AppKey每秒超过10次访问将被限流,返回{"code":11,"message":"接口流控"}。可以通过降低查询频次解决。

方法名:shop/create

参数名称 参数类型 是否必须 参数描述
shop_id String 取货门店id,即合作方向美团提供的门店id
shop_name String 门店名称

说明:①门店名称格式请按照 【XX品牌-XX店 or XX品牌(XX店)】填写,例:百果园(望京店),括号内信息必须以【店】结尾;②名称最大不能超过50个字符。

注:该名称需与实体门店门牌保持一致,保证骑手取货可确认门店。

category int 一级品类,见附件品类代码表

说明:品类需按门店真实配送品类选择,如无法判断可咨询您的销售经理。

second_category int 二级品类,见附件品类代码表

说明:品类需按门店真实配送品类选择,如无法判断可咨询您的销售经理。

contact_name String 门店联系人姓名
contact_phone String 联系电话

说明:支持手机号、支持400电话、支持固话(格式为【区号】【-】【座机号】【-】【分机号】,分机号如有则添加)。

contact_email String 联系邮箱
shop_address String 门店地址

说明:①地址长度不得小于5个字符大于60个字符;②地址信息不得含有折扣/满减信息。

注:请提供真实准确的门店地址,便于骑手取货。

shop_address_detail String 门牌号
shop_lng int 门店经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用),坐标 * (10的六次方),如 116398419

说明:门店坐标与地址所在城市、行政区等需保持一致。

注:请提供准确坐标,便于骑手取货。

shop_lat int 门店纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用),坐标 * (10的六次方),如 39985005

说明:门店坐标与地址所在城市、行政区等需保持一致。

注:请提供准确坐标,便于骑手取货。

coordinate_type int 坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标 (默认值为0)
delivery_service_codes String

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

1)服务包

飞速达:4002

快速达:4011

及时达:4012

集中送:4013

跑腿帮送:4031

例如:4011,4012(多个英文逗号隔开)

2)新服务产品

具体可参考新服务产品列表

business_hours String

营业时间

例:[{"beginTime":"00:00","endTime":"24:00"}]

注:传入后美团根据区域可配送时间取交集时间作为门店配送时间

pickup_address_desc String

取件地址信息补充说明

说明:

①地址信息补充说明不超过50个字;

②请对门店地址信息进行补充描述,便于骑手找店;

示例:柳港园B区西门附近,麦当劳对面

shop_guide_images String

门店指引图片信息

示例:["fffjhgkjht.jpg","kerfgdfhk.jpg","ehtrkhkh khhkhh.png"]

说明:

①请上传门头&门店周边照片,此照片将用于骑手找店指引;

②图片数量1~3张;

③请填写图片链接地址,图片链接地址获取见图片上传接口返回值中的fileKey

返回信息:

成功返回{"code":0, "data": {"shop_id": test, "status": 0}}

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

门店修改

合作方提交门店信息(注意测试推单仍然用系统默认test_0001门店);门店信息不能同时为空,则返回报错;若参数和原门店数据一致,则返回报错;若存在门店修改未审核任务时,则返回报错。

流量控制

同一AppKey每秒超过15次访问将被限流,返回{"code":11,"message":"接口流控"}。可以通过降低查询频次解决。

方法名:shop/update

参数名称 参数类型 是否必须 参数描述
shop_id String 取货门店id,即合作方向美团提供的门店id
shop_name String 门店名称

说明:①门店名称格式请按照 【XX品牌-XX店 or XX品牌(XX店)】填写,例:百果园(望京店),括号内信息必须以【店】结尾;②名称最大不能超过50个字符。

注:该名称需与实体门店门牌保持一致,保证骑手取货可确认门店。

contact_name String 门店联系人姓名
contact_phone String 联系电话

说明:支持手机号、支持400电话、支持固话(格式为【区号】【-】【座机号】【-】【分机号】,分机号如有则添加)。

contact_email String 联系邮箱
shop_address String 门店地址

说明:①地址长度不得小于5个字符大于60个字符;②地址信息不得含有折扣/满减信息。

注:请提供真实准确的门店地址,便于骑手取货。

shop_address_detail String 门牌号
shop_lng int 门店经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用),坐标 * (10的六次方),如 116398419

说明:门店坐标与地址所在城市、行政区等需保持一致。

注:请提供准确坐标,便于骑手取货。

shop_lat int 门店纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用),坐标 * (10的六次方),如 39985005

说明:门店坐标与地址所在城市、行政区等需保持一致。

注:请提供准确坐标,便于骑手取货。

coordinate_type int 坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标 (默认值为0)
delivery_service_codes String

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

1)服务包

飞速达:4002

快速达:4011

及时达:4012

集中送:4013

跑腿帮送:4031

例如:4011,4012(多个英文逗号隔开)

2)新服务产品

具体可参考新服务产品列表

business_hours String

营业时间

例:[{"beginTime":"00:00","endTime":"24:00"}]

注:传入后美团根据区域可配送时间取交集时间作为门店配送时间

pickup_address_desc String

取件地址信息补充说明

说明:

①地址信息补充说明不超过50个字;

②请对门店地址信息进行补充描述,便于骑手找店;

示例:柳港园B区西门附近,麦当劳对面

shop_guide_images String

门店指引图片信息

示例:["fffjhgkjht.jpg","kerfgdfhk.jpg","ehtrkhkh khhkhh.png"]

说明:

①请上传门头&门店周边照片,此照片将用于骑手找店指引;

②图片数量1~3张;

③请填写图片链接地址,图片链接地址获取见图片上传接口返回值中的fileKey

返回信息:

成功返回{"code":0, "data": {"shop_id": test, "status": 0}}

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

查询门店信息

查询门店基本信息

方法名:shop/query

参数名称 参数类型 是否必须 参数描述
shop_id String 取货门店id,即合作方向美团提供的门店id

流量控制

同一AppKey每秒超过30次访问将被限流,返回{"code":11,"message":"接口流控"}。可以通过降低查询频次解决。

返回信息:

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

data 格式如下:

参数名称 参数类型 是否必须 参数描述
shop_id String 取货门店id,即合作方向美团提供的门店id
city int 城市ID,见城市代码表
category int 一级品类,见附件品类代码表
second_category int 二级品类,见附件品类代码表
contact_name String 门店联系人
contact_phone String 联系电话
contact_email String 联系邮箱
shop_address String 门店地址
shop_address_detail String 门牌号
shop_lng int 门店经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用),坐标 * (10的六次方),如 116398419
shop_lat int 门店纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用),坐标 * (10的六次方),如 39985005
coordinate_type int 坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标 (默认值为0)
delivery_service_codes String

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

1)服务包

飞速达:4002

快速达:4011

及时达:4012

集中送:4013

例如:4011,4012(多个英文逗号隔开)

2)新服务产品

具体可参考新服务产品列表

delivery_hours String

配送时间

例:[{"beginTime":"00:00","endTime":"24:00"}]

prebook int 是否支持预约单,0:不支持,1:支持
prebook_out_of_biz_time int 是否支持营业时间外预约单,0:不支持,1:支持
prebook_period String 预约单时间段,格式为{"start": "0", "end": "2"},单位为天
pay_type_codes List<Integer>

门店当前可支持的结算方式下的支付方式,支付方式,0、账期支付,1、余额支付;

账期支付请关注月度账单;余额支付请联系运营协助操作账户开通、充值等,开通余额支付时可参与相应营销活动、使用优惠券等。

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

门店状态回调

门店审核驳回、审核通过、门店信息录入完毕、门店首次设置营业、以及修改门店信息时,会对合作方提供的回调url进行回调。

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

六种状态:10-创建审核驳回、20-创建审核通过、30-创建成功、40-上线可发单、50-修改审核驳回、60-修改审核通过

签名算法

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

成功与重试

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

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

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

回调接口说明

请求方式:post

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

参数名称 参数类型 是否必须 参数描述
shop_name String 门店名称
shop_id String 取货门店id,即合作方向美团提供的门店id
status int

10-创建审核驳回

20-创建审核通过

30-创建成功

40-上线可发单

50-修改审核驳回

60-修改审核通过

reject_message String 驳回原因
appkey String 美团配送技术服务合作中心分配的appkey,合作方唯一标识。
timestamp long 时间戳,格式为long,时区为GMT+8,当前距离Epoch(1970年1月1日) 以秒计算的时间,即unix-timestam。
sign String 数据签名
配送员上下班打卡回调

配送员上下班打卡时,会对合作方提供的回调url进行回调。

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

签名算法

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

成功与重试

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

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

回调接口说明

请求方式:post

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

参数名称 参数类型 是否必须 参数描述
rider_id String 配送员ID
rider_name String 配送员姓名
rider_phone String 配送员电话
operate_type int

上下班打卡操作类型:

1-上班,2-下班

operate_time long 时间戳,格式为long,时区为GMT+8,当前距离Epoch(1970年1月1日) 以秒计算的时间,即 unix-timestamp。
取餐码信息下发

客户门店使用自有或三方取餐柜时,可以通过当前接口下发取餐码至骑手,支持骑手通过取餐柜完成取餐;若是骑手已完成取餐,则接口同样返回成功。

方法名:mealCode/saveMealCodeByPkgId

参数名称 参数类型 是否必须 参数描述
mt_peisong_id long 美团配送内部订单ID,最长不超过32个字符;示例:200808080999333
infos String

取餐码业务详情信息,内容为JSON格式,示例如下:

{
	"type": 0,
	"cabinetNum": "xxxxxx",
	"cabinetDoor": "xxxxx,xxxxx",
	"cabinetCode": "xxxxxx"
}
type:取餐类型,int类型,包含0(存餐及更新)、1(撤餐),必填且必须为0或1;
cabinetNum:柜号,String类型,最长不超过100字符,非必填,同步撤餐状态时可为空,若存在多个时可以逗号隔开;
cabinetDoor:门号(取餐柜的格口号),String类型,最长不超过100字符,必填,同步撤餐状态时可为空,若存在多个时可以逗号隔开;
cabinetCode:取餐码,String类型,最长不超过12个字符,必填,同步撤餐状态时可为空,一个配送订单对应一个取餐码;
取餐码信息会同步到骑手侧展示并将取餐码转换为二维码展示。

返回信息:

成功返回

{
	"code":0
}

失败返回

{
	"code":错误码,
	"message": 错误描述
}
								
预发单接口

根据合作方提供的模拟发单参数,确定美团是否可配送,并且实现发单信息预览,适用于门店方式发单预览。

流量控制

同一AppKey每秒超过80次访问将被限流,返回{"code":11,"message":"接口流控"}。可以通过降低查询频次解决。

方法名:order/preCreateByShop

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

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

注:若调用预发单接口后再创建订单时,请将order_id保持一致。

outer_order_source_desc String

订单来源:

101.美团(外卖&闪购)

102.饿了么

103.京东到家

105.抖音

201.商家web网站

202.商家小程序-微信

203.商家小程序-支付宝

204.商家APP

205.商家热线

其他,请直接填写中文字符串,最长不超过20个字符

非「其他」需传代码

outer_order_source_no String 原平台订单号,如订单来源为美团,该字段必填,且为美团平台生成的订单号,最长不超过32个字符
shop_id String

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

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

delivery_service_code int

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

1)服务包

飞速达:4002

快速达:4011

及时达:4012

集中送:4013

跑腿-帮送:4031

2)新服务产品

具体可参考新服务产品列表

receiver_name String 收件人名称,最长不超过256个字符
receiver_address String 收件人地址,最长不超过512个字符
receiver_phone String

收件人电话,最长不超过64个字符;若收件人是港澳台电话,请按{区号}_{手机号}输入,例:852_12345678。

地区 区号
香港 852
澳门 853
台湾 886
receiver_lng int 收件人经度(火星坐标或百度坐标,和 coordinate_type 字段配合使用),坐标 * (10的六次方),如 116398419
receiver_lat int 收件人纬度(火星坐标或百度坐标,和 coordinate_type 字段配合使用),坐标 * (10的六次方),如 39985005
coordinate_type int 坐标类型,0:火星坐标(高德,腾讯地图均采用火星坐标) 1:百度坐标 (默认值为0)
pay_type_code int

支付方式,0、账期支付,1、余额支付;

当前门店可支持的支付方式可以通过查询门店信息接口获取;选择余额支付时,预发单信息预览包含优惠券等信息。

goods_value double

货物价格,单位为元,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为0-5000

跑腿-帮送服务包:范围0-3000

goods_height double 货物高度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为0-45
goods_width double 货物宽度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为0-50
goods_length double 货物长度,单位为cm,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为0-65
goods_weight double

货物重量,单位为kg,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数),范围为0-50

跑腿-帮送服务包:范围0-20

goods_detail String

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

{
	"goods":[
			{
				"goodCount": 1,
				"goodName": "货品名称",
				"goodPrice": 9.99,
				"goodUnit": "个",
				"goodUnitCode":"10008"
			}
		]
	}
goods对应货物列表;
goodCount表示货物数量,int类型,必填且必须大于0;
goodName表示货品名称,String类型,必填且不能为空;
goodPrice表示货品单价,double类型,选填,数值不小于0,精确到小数点后两位(如果小数点后位数多于两位,则四舍五入保留两位小数);
goodUnit表示货品单位,String类型,选填,最长不超过20个字符;
goodUnitCode表示货品标准计量单位,String类型,有特殊计费模式商家请必传;若字段【goodUnit】与当前字段同时传值不一致时,则以当前货品标准计量单位为准;参照货品标准计量单位列表
强烈建议提供,方便骑手在取货时确认货品信息
goods_pickup_info String 货物取货信息,用于骑手到店取货,最长不超过100个字符
goods_delivery_info String 货物交付信息,最长不超过100个字符
expected_pickup_time long

非跑腿-帮送服务包:否

跑腿-帮送服务包-即时单:否

跑腿-帮送服务包-预约单:是

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

跑腿-帮送服务包预约单:发单后60分钟到次日23:50,10的倍数

跑腿-帮送服务包即时单:不允许设置此字段

expected_delivery_time long

即时单(除当天送):否

预约单:是

跑腿-帮送服务包:否

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

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

预约单:以客户传参数据为准(预约时间必须大于当前下单时间+服务包时效+3分钟)

跑腿-帮送服务包传此值不生效

1)服务包

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

2)新服务产品

具体可参考新服务产品列表

order_type int

订单类型,默认为0

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

1: 预约单

跑腿-帮送服务包预约单,会存在骑手提前接单的可能

note String 备注,最长不超过200个字符。

返回信息:

成功返回

{
		"code":0,
		"data": data信息
	}

data 格式如下:

参数名称 参数类型 是否必须 参数描述
delivery_distance int 订单配送距离,参考距离,单位为米,实际配送距离以实际发单时刻为准
delivery_fee double 订单配送价格,参考价格,单位为元,价格受距离、模拟发单时间、配送高峰、特殊天气等不同计费因素影响,实际配送价格以实际发单时刻为准
base_delivery_fee double 优惠可用配送金额,单位为元;使用余额支付时有值;总配送费中可使用优惠券抵扣的部分配送费金额,金额受到不同计费因素以及优惠券使用规则影响
coupons_id String

优惠券ID,使用余额支付时有值;

当前时刻可用的、最优的优惠券ID;实际发单过程中依旧会校验优惠券ID是否可用。

coupons_amount double

优惠券金额,单位为元,使用余额支付时有值,反之无值或为0;

当前时刻可用的、最优的优惠券ID对应的优惠券金额。

失败返回

{
		"code":错误码,
		"message": 错误描述
	}
								
获取配送码

获取配送码适用于商家选择使用骑手扫码配送的场景。通过当前接口获取配送码后,需要门店以二维码的形式将配送码打印在门店取餐小票上,并且在订单创建时将配送码传输至美配侧,以便骑手到门店取餐时可直接扫码取餐、配送;使用扫码配送模式时,订单状态回调时,“已接单”状态不再进行回调。

流量控制

同一AppKey每秒超过50次访问将被限流,返回{"code":11,"message":"接口流控"}。可以通过降低查询频次解决。

方法名:order/createDeliveryCode

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

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

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

order_id String

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

获取配送码适用的订单id与实际发单时使用的订单id请保持一致。

返回信息:

成功返回

{
		"code":0,
		"data": {"business":"peisong-qrfetch","content":"1623988992138003281"}
	}

data 格式如下:

参数名称 参数类型 是否必须 参数描述
content String 配送码code,长度19字符,示例:1623988992138003281
business String

业务线类型,长度15字符,示例:peisong-qrfetch;

示例中data部分:{"business":"peisong-qrfetch","content":"1623988992138003281"} 需要将整个字符串封装到打印到小票上的二维码中,保证美配骑手扫描二维码后获取内容完整;并且订单创建时需要将data部分完整传入;

失败返回

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

接口功能说明

1、此接口可获取一个订单的骑手位置H5链接,可支持内嵌或发送给用户(内嵌时无法保证界面的兼容性,如发现兼容性问题可使用获取骑手位置接口自行开发轨迹H5);

2、此接口针对不同服务包会返回不同H5链接;

3、订单取消后,H5页面不会产生骑手位置信息;

4、骑手已接单至已送达时,都会产生骑手位置;

5、订单完成后8-24小时,骑手位置则不展示(美配会根据流量进行时段控制)。

流量控制

同一AppKey每秒超过10次访问将被限流,返回{"code":11,"message":"接口流控"}。可以通过降低查询频次解决。

方法名:/api/order/rider/location/h5url

请求方式:post

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

请求参数:key = value形式

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

返回信息:

成功返回

{
		"code":0,
		"message": "成功",
		"data": data信息
	}

data 格式如下:

参数名称 参数类型 是否必须 参数描述
riderLocationUrl String 骑手位置 H5 URL。跑腿帮送服务包返回的H5链接中,订单完成8小时后则不再展示骑手位置信息,其他服务包返回的H5链接中,订单完成24小时后则不再展示骑手位置信息;美配会根据访问流量进行时段控制。

失败返回

{
		"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个字符
pickup_goods_code String 取货码
delivery_goods_code String 收货码
appkey String 美团配送技术服务合作中心分配的appkey,合作方唯一标识。
timestamp long 时间戳,格式为long,时区为GMT+8,当前距离Epoch(1970年1月1日) 以秒计算的时间,即 unix-timestamp。
sign String 数据签名
图片上传接口文档

接口描述

商家图片上传。

使用场景

商家可根据该接口用于找店引导图片上传,以便用于「门店创建、门店修改」接口中的门店图片信息参数中,商家上传门店找店引导图片后,骑手可以更快的找到取货门店。

注:图片后缀支持后缀名,如 「jpg、jpeg、png、bmp」,图片不得大于 5M。

流量控制

同一客户每秒超过10次访问将被限流,返回{"code":11,"message":"接口流控"}。可以通过降低查询频次解决。

请求路径

file/image/upload

请求参数

序号 参数名称 字段说明 是否必须 参数类型 默认值 示例值 参数描述
1 image_name 文件名 string -- 37375183__1582979.jpg 图片名称,图片后缀名仅支持 「jpg、jpeg、png、bmp」
2 image_data 文件名 string -- data:image/jpeg;base64,........ 图片base64内容,注意:此字段不参与签名计算。

返回信息

成功返回{"code":0, "message": "成功"}

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

返回结果

序号 字段名称 字段说明 必填 参数类型 默认值 示例值 规则
1 code 响应code int 110 0:表示接口请求成功,其他code均为失败
2 msg 响应描述 string success
3 data 响应结果 object 当code = 0 才有值

data结构

序号 字段名称 字段说明 必填 类型 示例值 参数描述
1 fileName 文件名 string 37375183__1582979.jpg 文件名
2 fileKey 文件 string ISWvZbzsyOPDcoMawiGfQ7ZSA5gHnQM.jpg 文件唯一标识

异常code

代码 描述信息 可能原因及处理建议
401 图片大小超过最大限制,请重新选择图片 请按照「图片上传接口」文档中图片大小要求,重新上传图片
402 不支持的图片后缀,请重新选择图片 图片后缀名仅支持 「jpg、jpeg、png、bmp」,请重新选择图片
405 文件解析失败,请稍后重试
406 文件解析失败,请稍后重试
门店履约信息变更回调

接口描述

门店履约信息变更时,会对合作方提供的URL进行回调请求。包括门店营业时间变更、门店营业状态变更、门店配送服务变更、门店支持的预订单时间变更,后续还会增加类型。

签名算法

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

成功与重试

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

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

接口说明

请求方式:post

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

回调请求参数

字段名称 字段说明 必填 类型 默认值 示例值 规则
shop_id 取货门店id string -- test_0001
appkey 美团配送技术服务合作中心分配给开发者的唯一标识 string -- 2f40fe34835d45f8889f1ef80ea99075
timestamp 时间戳 long -- 1666775301

格式为long,时区为GMT+8,

距离Epoch(1970年1月1日) 以秒计算的时间,即unix-timestamp

sign 签名字段 string -- 3e97705d323ed331db34309094da0e32d6475a70
shop_delivery_infos 门店履约变更信息 string
[
  {
    "reason": "",
    "pre_business_hours": "[{\"beginTime\":\"00:00\",\"endTime\":\"24:00\"}]",
    "shop_delivery_type": "1",
    "utime": "1675391677",
    "current_business_hours": "[{\"beginTime\":\"00:00\",\"endTime\":\"23:59\"}]"
  },
  {
    "current_isOpen": "1",
    "pre_isOpen": "0",
    "reason": "",
    "shop_delivery_type": "2",
    "utime": "1675391677"
  },
  {
    "shop_delivery_type": "3",
    "utime": "1675391677",
    "pre_serviceTypes": "100000,100002,100005,100007,100305,100001",
    "current_serviceTypes": "100000,100001,100002,100005,100007,100305,100006"
  },
  {
    "pre_prebook_status": "0",
    "shop_delivery_type": "4",
    "utime": "1675391677",
    "current_prebook_out_biz_time": "1",
    "current_prebook_time_range": "{\"start\":0,\"end\":6}",
    "pre_prebook_out_biz_time": "0",
    "current_prebook_status": "1",
    "pre_prebook_time_range": "{\"start\":0,\"end\":0}"
  }
]

该字段类型为list转换后的json字符串。list内元素为履约变更信息,

详情见表门店履约信息字段说明。

门店履约信息字段说明

字段名称 字段说明 类型 示例值 规则
shop_delivery_type 履约信息类型 string 1

1:门店营业时间

2:门店营业状态

3:门店配送服务

4:门店支持的预订单时间

注:该枚举值后续还会增加

utime 状态变更时间 1675391677
reason 变更原因 ""
pre_business_hours 变更前门店营业时间 string [{\"beginTime\":\"00:00\",\"endTime\":\"24:00\"}] 对应shop_delivery_type值为1
current_business_hours 当前门店营业时间 [{\"beginTime\":\"00:00\",\"endTime\":\"23:59\"}]
pre_isOpen 变更前门店营业状态 string 0

对应shop_delivery_type值为2

1:营业

0:休息

current_isOpen 当前门店营业状态 1
pre_serviceTypes 变更前配送服务信息 string 100000,100002,100005,100007,100305,100001 对应shop_delivery_type值为3
current_serviceTypes 当前配送服务信息 100000,100001,100002,100005,100007,100305,100006
pre_prebook_status 变更前是否支持预订单 string 0

对应shop_delivery_type值为4

0:不支持

1:支持

current_prebook_status 当前是否支持预订单 1
pre_prebook_out_biz_time 变更前是否支持营业时间外发预订单 0
current_prebook_out_biz_time 当前是否支持营业时间外发预订单 1
pre_prebook_time_range 变更前预订单时间范围 {\"start\":0,\"end\":0}
current_prebook_time_range 当前预订单时间范围 {\"start\":0,\"end\":6}

回调返回信息

客户系统提供的url需返回的信息

字段名称 字段说明 必填 类型 默认值 示例值
code 返回的业务Code码,0代表成功,其他代表失败 int --
message 如果错误,这个字段存放错误信息 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

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

1)服务包

飞速达:4002

快速达:4011

及时达:4012

集中送:4013

2)新服务产品

具体可参考新服务产品列表

返回信息:

成功返回

{
	"code":0
}

失败返回

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

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

模拟操作错误信息:

代码 信息描述
1 系统错误,建议稍后重试或联系美团RD
124 模拟操作失败
配送风险等级变更回调测试

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

接口名称 接口地址 描述
模拟门店配送风险等级变更 /api/test/shop/deliveryRiskLevel/callback 模拟门店配送风险等级变更

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

参数名 类型 必填 描述
shop_id String

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

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

返回信息:

成功返回

{
	"code":0
}

失败返回

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

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

模拟操作错误信息:

代码 信息描述
1 系统错误,建议稍后重试或联系美团RD
124 模拟操作失败
门店状态回调测试

若合作方需要测试门店门店状态的回调,可使用以下接口模拟

接口名称 接口地址 描述
模拟门店状态回调测试 /api/test/shop/status/callback 模拟门店状态回调测试

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

参数名 类型 必填 描述
shop_id String

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

status int

10-审核驳回

20-审核通过

30-创建成功

40-上线可发单

返回信息:

成功返回

{
	"code":0
}

失败返回

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

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

模拟操作错误信息:

代码 信息描述
1 系统错误,建议稍后重试或联系美团RD
124 模拟操作失败
配送员上下班打卡回调测试

若合作方需要测试配送员上下班打卡的回调,可使用以下接口模拟

接口名称 接口地址 描述
模拟配送员上下班打卡回调测试 /api/test/rider/work/callback 模拟配送员上下班打卡回调测试

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

参数名 类型 必填 描述
operate_type int

上下班打卡操作类型:1-上班,2-下班

返回信息:

成功返回

{
	"code":0
}
							

失败返回

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

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

模拟操作错误信息:

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

0为请求成功

1-99为平台错误

100以上为业务错误

代码 描述信息 建议处理方式
0 成功
1 系统错误 三次重试,每次间隔10S
2 缺少系统参数
3 缺少参数,数据不完整
4 参数格式错误
5 app_key不存在或合作方不合作
6 签名验证错误
7 没有权限操作这条数据 检查是否正式账号操作测试账号数据或测试账号操作正式账号数据
8 api版本号不支持
9 请求时间超出最大时限 检查入参的timestamp是否满足:
推单时间 - timestamp < 600秒
10 当前ip不在可访问列表中 联系技术人员排查
11 接口流控 三次重试,每次间隔10S
13 输入参数内容不符合规范,请检查修改 请检查参数的内容,修改后重试
101 订单id正在创建配送订单 三次重试,每次间隔10S
102 订单不存在 检查入参delivery_id、mt_peisong_id
103 货品信息有误,金额过大,体积过大,重量过沉等
104 订单已完成,不能取消
105 订单预计完成时间不在可接受范围
106 所选城市未合作 联系技术人员排查
107 所选配送服务类型无效
108 非合作时间
109 取货地址超区
110 送货地址超区
111 不在美团配送站点营业时间内
112 门店不存在

1.首先找美团运营同事确认shop_id是否已入驻美团系统;

2.其次,检查发单的appkey与shop_id是否类型一致(即用正式appkey发正式门店订单,用测试appkey发测试门店订单)

113

不在门店营业时间内: %s

示例:

发单时间(23:00:00)不在门店营业范围(10:00:00-22:00:00)内

预约单的期望送达时间(23:00:00)不在门店营业时间(10:00:00-22:00:00)内

114 门店非营业状态
115 门店未开通所选服务包
116 超过所选服务包允许的时效限制
117 预约时间超出范围
118 订单类型不符合要求
119 门店不支持预约单
120 预约时间超出范围
121 门店不支持营业时间外发预订单
122 保价服务异常 三次重试,每次间隔10S
123 价格缺失,无法投保
124 模拟操作失败
125 订单尚未完成,不允许进行评价操作
126 订单已评价,不允许重复评价
127 坐标方式发出的订单,不允许评价操作
128 所选位置暂未开通服务
129 订单未调度,请分配骑手后重试
130 订单已送达,无法获取位置信息
131 订单已取消,无法获取位置信息
132 骑手目前没有位置信息,请稍后重试
133 创建订单接口禁用中,请咨询您的销售经理
144 当前区域运力紧张,无法创建订单
145 坐标没有落在区域内
152 因配送范围管控,取货/送货地址超区
163 收件坐标不合法
164 预约取件时间不合法
166 货物价值异常:%s 请按报错说明,调整货物价值字段goods_value赋值
190 接口已降级&【具体原因】 根据具体原因更换调用的相应入参
200 不支持查询跑腿B服务包配送范围,跑腿B帮送服务包配送范围支持导航距离70km以内的订单
201 参数值错误:%s
202 已有骑手接单,不用加小费啦
203 加小费金额已至上限,无法继续添加
204 加小费次数已至上限,无法继续追加小费
205 加小费异常,请稍后重试
210 请核对标准计量单位code码
211 优惠券无效或不符合可用条件 建议使用预发单接口查询可支持的优惠券信息
212 账户余额不足或扣款失败 建议账户充值后重新下单,或更换其他支付方式重新下单
214 不支持该支付方式 建议重新查询门店中可支持的支付方式
215 定价方案异常 请联系销售、运营人员查看定价方案是否维护
216 获取合同异常 请联系销售、运营人员检查合同状态
217 服务产品不可用 请联系销售、运营人员检查服务产品是否有效
220 当前门店未查询到门店配送范围
221 收件地址所在区域暂无支持该配送服务的运力
222 当前门店未查询到门店营业时间 请联系销售、运营人员检查门店配送信息是否完整。
610 当前门店未查询到对应配送城市或配送区域 请联系销售、运营人员检查门店配送信息是否完整。
城市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 因订单异常原因,订单被取消(取消原因:%s)
1203 因系统原因,订单被取消,建议稍后重新发单
1204 订单超时未支付取消,请尝试重新发单
1205 账户余额扣款失败,请尝试重新发单
1299 其他美团配送原因
其他原因 1399 其他原因
订单状态代码列表
订单状态代码 订单状态描述
0 待调度
20 已接单
30 已取货
50 已送达
99 已取消
品类代码列表
一级品类-code 一级品类-名称 二级品类-code 二级品类-名称
110 美食 110001 零食小吃
110002 早餐
110003 香锅/烤鱼
110004 西餐
110005 日韩料理
110006 海鲜/烧烤
110007 快餐/地方菜
110008 匹萨
120 生活超市 120001 便利店
120002 水站/奶站
120003 零食/干果
120004 五金日用
120005 粮油调味
120006 文具店
120007 酒水/茶行
120008 地方特产
120009 进口食品
120011 超市
120012 书店
120013 传统百货
150 生鲜果蔬 150001 果蔬
150002 海鲜水产
150003 冷冻速食
160 电商 160001 电视购物
160002 线上商城
180 鲜花绿植 180001 鲜花
180002 绿植
200 医药健康 200001 OTC
240 母婴 240001 孕婴用品
250 3C家电 250001 手机数码
260 日用品 260002 办公居家用品
260003 票务文件
270 甜点饮品 270001 蛋糕
270002 甜品
270003 奶茶果汁
270004 咖啡
270005 面包/糕点
270006 冰淇淋
280 美妆 280001 日化美妆
330 快递配送 330001 快递包裹
210 其他 210001 其他
新服务产品列表
标准服务产品 光速达 快速达
服务产品名称 臻选型 臻选型-45 时效型 普惠型
服务产品编码 100030 100035 100029 100031
距离 0-1公里 30min 45min 45min 60min
1-2公里 35min 45min 45min 60min
2-3公里 40min 45min 45min 60min
3-4公里 45min 50min 50min 60min
4-5公里 50min 55min 55min 60min
5-6公里 —— 60min 60min 80min
6-7公里 —— —— 65min 80min
履约重量 0-30公斤
履约时段

常规时段:9:00-21:00

加价时段

午高峰:11:00-13:00

夜间:21:00-6:00

货品标准计量单位列表
计量单位代码 计量单位名称
10000
10001 千克
10002 立方厘米
10003 立方米
10004
10005 千米
10006 毫升
10007
10008
10009
10010
10011
10012
10013
10014
10015
10016
10017
10018
10019
10020
10021
10022
10023
10024
10025
10026
10027
10028
10029
【重要通知】美团配送技术服务合作中心新增支付场景接口升级通知

更新时间:2021-08-17 16:10:00

尊敬的合作伙伴:

为了给美团配送的各位合作伙伴提供多样的履约费用支付方式,美团配送新增了”实时支付“场景下的的”余额支付“,美团配送技术服务合作中心接口能力因此做了升级;

接口升级详细内容参考下方。

您需在8月30日前,完成系统能力的兼容性检查或升级,使系统兼容美团配送技术服务合作中心接口返回字段新增的变化;

建议:由于美团配送技术服务合作中心会持续为您提供更优质的系统对接服务,接口能力会不定期持续升级,返回字段的数量也会随接口升级有所增加,请您做好系统兼容。

一、新增接口

接口名:预发单接口
文档地址:https://peisong.meituan.com/open/doc#section2-20

二、变更接口

接口名:订单创建(门店方式)
文档地址:https://peisong.meituan.com/open/doc#section2-20
变更内容:新增4个返回字段(已更新到接口文档):base_delivery_fee、pay_amount、settlement_mode_code、coupons_amount

接口名:查询订单状态
文档地址:https://peisong.meituan.com/open/doc#section2-20
变更内容:新增5个返回字段(已更新到接口文档):delivery_distance、delivery_fee、pay_amount、settlement_mode_code、coupons_amount

迁移前提

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

迁移步骤

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

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

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

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

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

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