关于我们

饿了么开放平台推送消息补偿场景接入方案

发布时间:2025-05-27

 

个人零费用代理店+,日收入3000+,可兼职做

文档说明

针对已接入消息推送服务的所有第三方开发者和自研商家,本文档旨在提供推送消息补偿方案。此方案将作为当出现紧急情况时的“救命稻草”,如果由于未接入此方案而导致订单无法履约,平台将对服务商进行顶格违规处理,请务必注意。

背景说明

保障平台稳定运行以及推送可达性是平台义不容辞的责任,希望高质量的开发者能积极主动对接推送消息补偿接口,以最大程度确保订单能够得到及时处理,同时订单推拉结合也是必须要接入的:(必接)订单推拉结合接入场景方案。

接口详情

接口权限申请路径:管理中心-我的应用-权限升级-数字化工具-推拉结合专项

所属服务 是否必接/计费标准 接口名称 描述 备注
新消息服务 必接/免费 eleme.msgNew.getPushFailMsg 获取未拉取的推送失败消息列表 获取履约核心消息(type=10,12,14,15,17,217,218),其他类型消息如有需求,可用eleme.message.getNonReachedMessages或eleme.message.getNonReachedOMessages获取。调用该接口token传空即可,需要代码调用,API调试台无法调试
新消息服务 必接/免费 eleme.msgNew.confirmPullMsg 向平台确认已成功拉取推送失败的消息 调用该接口token传空即可,需要代码调用,API调试台无法调试
消息服务 可选/基础 eleme.message.getNonReachedMessages或eleme.message.getNonReachedOMessages 获取未到达的推送消息 由于历史原因,调用该接口传入一个正确的Token即可。前者返回 String 类型,后者返回O

 

eleme.msgNew.getPushFailMsg 调用代码示例

入参是应用维度(appId)的接口,token传空字符串即可,否则会提示“token 必须为空”。API调试台调用会报错,需要代码调用,eleme.msgNew.confirmPullMsg同理

package eleme.openapi.demo; import com.amazonaws.util.json.Jackson; import eleme.openapi.sdk.api.entity.msgNew.MsgQueryRequest; import eleme.openapi.sdk.api.entity.msgNew.MsgQueryResult; import eleme.openapi.sdk.api.exception.ServiceException; import eleme.openapi.sdk.api.service.MsgNewService; import eleme.openapi.sdk.api.service.OrderService; import eleme.openapi.sdk.config.Config; import eleme.openapi.sdk.oauth.response.Token; public class getPushFailMsg { public static void main(String[] args) throws ServiceException { // 变量为true: 沙箱环境 false: 生产环境 boolean isSandbox = false; String appKey = "XXXX"; String appSecret = "XXXX"; Config config = new Config(isSandbox, appKey, appSecret); //使用config对象,实例化一个授权类 Token token = new Token(); String accessToken = ""; token.setAccessToken(accessToken); MsgNewService msgNewService = new MsgNewService(config, token); MsgQueryRequest msgQueryRequest = new MsgQueryRequest(); msgQueryRequest.setAppId("48888888"); MsgQueryResult msgQueryResult = msgNewService.getPushFailMsg(msgQueryRequest); System.out.println(Jackson.toJsonString(msgQueryResult)); } }

接口调用时机

方案A:作为日常任务轮询调用,区分不同场景。调用频率分为 日常 和 故障 两种场景,调用频率规则参考「接口调用频率」段落 A。

或者

方案B:作为日常任务轮询调用,不区分场景。调用频率规则参考「接口调用频率」段落 B。

接口调用频率

方案A:可做成开关形式。默认调用频率:日常,开关打开后切换为 故障 频率:

或者

方案B:不做成开关形式。接口返回数据为空则等待 2 分钟后重试,接口返回数据不为空则间隔 1 秒后重试。

接口使用说明

履约核心消息获取

接口名称:eleme.msgNew.getPushFailMsg

作用:获取过去 10 秒到 300 秒推送失败的 履约核心消息 列表

并发控制:每个应用 (appId 维度)同时只有一个请求能够返回数据,多个请求时接口返回的 msg 为 CONCURRENCY_CONTROL

返回数据:默认 100 条,不可设置。(假设总数据有200条,第一次调用接口获取到前100条,这100条平台会标记为已经获取;第二次调这个接口会取剩下的100条;第三次调用接口则不会返回信息,也就是每条消息只能被拉取到一次)

履约非核心消息获取

接口名称:eleme.message.getNonReachedMessages

调用说明:推送成功的消息系统会给以标记成功,该接口用于获取未标记成功的消息,每次返回最多10条。返回的消息在接口调用后会标记为已经推送。

时序图

业务逻辑处理示例

public void getPushFailMsg() throws InterruptedException { MsgQueryRequest req = new MsgQueryRequest(); req.setAppId("xxx"); while(true){ MsgQueryResult result = getPushFailMsg(req); if(null==result.getMsgList()&&"CONCURRENCY_CONTROL".equals(result.getMsg())){ //如果被并发控制,直接结束 break; } if(null==result.getMsgList()){ //没返回数据,则重试 continue; } if(null!=result.getMsgList()&&result.getMsgList().size()<100){ //数据取完,等一分钟再试 Thread.sleep(60000); } } }

eleme.msgNew.getPushFailMsg 接口返回示例

userId(授权商户的账号id) 不再返回,可以使用 shopId 做匹配判断授权关系

{ "success": true, "msgList": [ { "messageType": "10", "orderId": 8051********4963917, "appId": "77****82", "messageId": 613333********79406, "id": "550062********1850", "gmtCreate": "20230707115724", "message": "{\"activeAt\":\"2023-07-07T11:57:24\",\"activityTotal\":0.0,\"additionServicePrice\":0.0,\"address\":\"上海市崇明区北沿公路2288号东平森林公园1号停车场\",\"allowanceServiceFee\":0.0,\"baiduWaimai\":false,\"baseLogisticsServiceFee\":-0.0,\"book\":false,\"cancelOrderCreatedAt\":null,\"cancelOrderDescription\":null,\"cityId\":1,\"cityName\":\"上海\",\"coldBoxFee\":0.0,\"confirmCookingTime\":null,\"consignee\":\"周**\",\"consigneePhones\":[\"186****5070\"],\"contributionAmount\":0.0,\"cpcAmount\":0.0,\"createdAt\":\"2023-07-07T11:57:24\",\"daySn\":1,\"deliverFee\":0.0,\"deliverTime\":null,\"deliveryGeo\":\"1**.**156,3*.**6031\",\"deliveryPackageFee\":0.0,\"deliveryPoiAddress\":\"上海市崇明区北沿公路2288号东平森林公园1号停车场\",\"deliveryProductId\":0,\"description\":\"不要辣, 不要葱 / 依据餐量提供餐具\",\"distanceIncreaseFee\":0.0,\"downgraded\":false,\"elemePart\":0.0,\"extraJson\":\"{\\\"deliveryActivityFee\\\":\\\"0.0\\\"}\",\"fulfillServiceFee\":0.0,\"grayOrder\":false,\"groups\":[{\"items\":[{\"activities\":[],\"additions\":[],\"attributes\":[{\"extCode\":null,\"name\":\"温度\",\"value\":\"加冰\"},{\"extCode\":null,\"name\":\"辣度\",\"value\":\"微辣\"}],\"barCode\":\"\",\"categoryId\":1,\"coupons\":[],\"extendCode\":\"\",\"foodGroup\":null,\"foodType\":0,\"id\":200102203191,\"ingredients\":[{\"id\":2000000875193003,\"name\":\"西米\",\"quantity\":1,\"skuCode\":\"\",\"uniqueId\":\"009354f0e-0668-4477-9030-c21247eab4fb\"},{\"id\":2000000360257304,\"name\":\"椰果\",\"quantity\":1,\"skuCode\":\"\",\"uniqueId\":\"0a2d678f3-6c5a-4e64-9d79-61e723ef0feb\"},{\"id\":2000000875312119,\"name\":\"芒果\",\"quantity\":1,\"skuCode\":\"\",\"uniqueId\":\"0a3e32186-f85b-416c-acf7-fd6e9ffe3993\"},{\"id\":2000000875287438,\"name\":\"西柚\",\"quantity\":1,\"skuCode\":\"\",\"uniqueId\":\"0e91538b5-af23-4d73-802b-8a6c5119df0e\"}],\"name\":\"珍珠奶茶(Bubbla)又称波霸奶茶简称-大杯[加冰+微辣]\",\"newSpecs\":[{\"extCode\":null,\"name\":\"规格\",\"value\":\"大杯\"}],\"price\":0.01,\"quantity\":1,\"shopPrice\":0.0,\"skuId\":200000497919040258,\"total\":0.01,\"uniqueId\":\"01cff09bc-b303-48b0-8d7e-5d334e774fff\",\"userPrice\":0.0,\"vfoodId\":1597425933,\"weight\":100.0},{\"activities\":[],\"additions\":[],\"attributes\":[],\"barCode\":\"\",\"categoryId\":1,\"coupons\":[],\"extendCode\":\"\",\"foodGroup\":null,\"foodType\":3,\"id\":2000000875193003,\"ingredients\":[],\"name\":\"西米\",\"newSpecs\":[],\"price\":0.01,\"quantity\":1,\"shopPrice\":0.0,\"skuId\":300000896187395842,\"total\":0.01,\"uniqueId\":\"009354f0e-0668-4477-9030-c21247eab4fb\",\"userPrice\":0.0,\"vfoodId\":2000000437281761,\"weight\":1.0},{\"activities\":[],\"additions\":[],\"attributes\":[],\"barCode\":\"\",\"categoryId\":1,\"coupons\":[],\"extendCode\":\"\",\"foodGroup\":null,\"foodType\":3,\"id\":2000000360257304,\"ingredients\":[],\"name\":\"椰果\",\"newSpecs\":[],\"price\":0.0,\"quantity\":1,\"shopPrice\":0.0,\"skuId\":300000368879624962,\"total\":0.0,\"uniqueId\":\"0a2d678f3-6c5a-4e64-9d79-61e723ef0feb\",\"userPrice\":0.0,\"vfoodId\":2000000164011633,\"weight\":1.0},{\"activities\":[],\"additions\":[],\"attributes\":[],\"barCode\":\"\",\"categoryId\":1,\"coupons\":[],\"extendCode\":\"\",\"foodGroup\":null,\"foodType\":3,\"id\":2000000875312119,\"ingredients\":[],\"name\":\"芒果\",\"newSpecs\":[],\"price\":0.01,\"quantity\":1,\"shopPrice\":0.0,\"skuId\":300000896304246530,\"total\":0.01,\"uniqueId\":\"0a3e32186-f85b-416c-acf7-fd6e9ffe3993\",\"userPrice\":0.0,\"vfoodId\":2000000437038422,\"weight\":1.0},{\"activities\":[],\"additions\":[],\"attributes\":[],\"barCode\":\"\",\"categoryId\":1,\"coupons\":[],\"extendCode\":\"\",\"foodGroup\":null,\"foodType\":3,\"id\":2000000875287438,\"ingredients\":[],\"name\":\"西柚\",\"newSpecs\":[],\"price\":0.01,\"quantity\":1,\"shopPrice\":0.0,\"skuId\":300000896284073730,\"total\":0.01,\"uniqueId\":\"0e91538b5-af23-4d73-802b-8a6c5119df0e\",\"userPrice\":0.0,\"vfoodId\":2000000437232043,\"weight\":1.0}],\"name\":\"1号篮子\",\"relatedItems\":[],\"type\":\"normal\"}],\"hongbao\":0.0,\"id\":\"8051640118384963917\",\"income\":0.03,\"invoice\":null,\"invoiceEmail\":null,\"invoiceType\":null,\"invoiced\":false,\"isBusinessOrder\":false,\"logisticsActivity\":null,\"merchantDeliverySubsidy\":0.0,\"onlinePaid\":true,\"openId\":\"\",\"orderActivities\":[],\"orderActivityParts\":[{\"partName\":\"优惠总计\",\"partValue\":-0.0,\"weight\":10}],\"orderBusinessType\":0,\"orderCommissions\":[],\"orderId\":\"8051640118384963917\",\"orderSourceTag\":\"ELEME\",\"originalPrice\":0.04,\"packageFee\":0.0,\"phoneList\":[\"18466813614,727\"],\"pickUpNumber\":0,\"pickUpTime\":\"1970-01-01T08:00:00\",\"pinTuanOrder\":false,\"pricePremiums\":0.0,\"publicWelfareGoodsFee\":0.0,\"railwayAddress\":null,\"refundStatus\":\"noRefund\",\"secretPhoneExpireTime\":\"2023-07-07T18:27:21\",\"serviceFee\":-0.01,\"serviceRate\":0.13,\"shopBrandId\":0,\"shopId\":16****314,\"shopName\":\"饿了么开放平台店铺\",\"shopPart\":-0.0,\"specUserPart\":0.0,\"status\":\"unprocessed\",\"superVip\":\"ELEME_SUPER_VIP\",\"svcPart\":0.0,\"taxpayerId\":\"\",\"tianmaoPart\":0.0,\"timeIntervalMarkUpFee\":0.0,\"totalActivityAmount\":0.0,\"totalAmount\":0.04,\"totalPrice\":0.04,\"umpOrder\":0,\"userExtraInfo\":{\"giverPhone\":\"\",\"greeting\":\"\"},\"userId\":243270083,\"userIdStr\":\"243270083\",\"userMarketingDescription\":null,\"userPart\":0.0,\"vipDeliveryFeeDiscount\":0.0,\"xyPackFlag\":false}" }, { "messageType": "217", "orderId": 8051********4963917, "appId": "77****82", "messageId": 6133********1179406, "id": "55006********08442", "gmtCreate": "20230707115724", "message": "{\"address\":\"上海市崇明区北沿公路2288号东平森林公园1号停车场\",\"book\":false,\"consignee\":\"唐**\",\"consigneePhones\":[\"186****5070\"],\"createdAt\":\"2023-07-07T11:57:24\",\"daySn\":1,\"deliverTime\":null,\"deliveryGeo\":\"1**.**156,3*.**6031\",\"deliveryPackageFee\":0.0,\"deliveryProductId\":0,\"description\":\"不要辣, 不要葱 / 依据餐量提供餐具\",\"downgraded\":false,\"extraJson\":\"{\\\"deliveryActivityFee\\\":\\\"0.0\\\"}\",\"fulfillServiceFee\":0.0,\"groups\":[{\"items\":[{\"activities\":[],\"additions\":[],\"attributes\":[{\"extCode\":null,\"name\":\"温度\",\"value\":\"加冰\"},{\"extCode\":null,\"name\":\"辣度\",\"value\":\"微辣\"}],\"barCode\":\"\",\"categoryId\":1,\"coupons\":[],\"extendCode\":\"\",\"foodGroup\":null,\"foodType\":0,\"id\":200102203191,\"ingredients\":[{\"id\":2000000875193003,\"name\":\"西米\",\"quantity\":1,\"skuCode\":\"\",\"uniqueId\":\"009354f0e-0668-4477-9030-c21247eab4fb\"},{\"id\":2000000360257304,\"name\":\"椰果\",\"quantity\":1,\"skuCode\":\"\",\"uniqueId\":\"0a2d678f3-6c5a-4e64-9d79-61e723ef0feb\"},{\"id\":2000000875312119,\"name\":\"芒果\",\"quantity\":1,\"skuCode\":\"\",\"uniqueId\":\"0a3e32186-f85b-416c-acf7-fd6e9ffe3993\"},{\"id\":2000000875287438,\"name\":\"西柚\",\"quantity\":1,\"skuCode\":\"\",\"uniqueId\":\"0e91538b5-af23-4d73-802b-8a6c5119df0e\"}],\"name\":\"珍珠奶茶(Bubbla)又称波霸奶茶简称-大杯[加冰+微辣]\",\"newSpecs\":[{\"extCode\":null,\"name\":\"规格\",\"value\":\"大杯\"}],\"price\":0.01,\"quantity\":1,\"shopPrice\":0.0,\"skuId\":200000497919040258,\"total\":0.01,\"uniqueId\":\"01cff09bc-b303-48b0-8d7e-5d334e774fff\",\"userPrice\":0.0,\"vfoodId\":1597425933,\"weight\":100.0},{\"activities\":[],\"additions\":[],\"attributes\":[],\"barCode\":\"\",\"categoryId\":1,\"coupons\":[],\"extendCode\":\"\",\"foodGroup\":null,\"foodType\":3,\"id\":2000000875193003,\"ingredients\":[],\"name\":\"西米\",\"newSpecs\":[],\"price\":0.01,\"quantity\":1,\"shopPrice\":0.0,\"skuId\":300000896187395842,\"total\":0.01,\"uniqueId\":\"009354f0e-0668-4477-9030-c21247eab4fb\",\"userPrice\":0.0,\"vfoodId\":2000000437281761,\"weight\":1.0},{\"activities\":[],\"additions\":[],\"attributes\":[],\"barCode\":\"\",\"categoryId\":1,\"coupons\":[],\"extendCode\":\"\",\"foodGroup\":null,\"foodType\":3,\"id\":2000000360257304,\"ingredients\":[],\"name\":\"椰果\",\"newSpecs\":[],\"price\":0.0,\"quantity\":1,\"shopPrice\":0.0,\"skuId\":300000368879624962,\"total\":0.0,\"uniqueId\":\"0a2d678f3-6c5a-4e64-9d79-61e723ef0feb\",\"userPrice\":0.0,\"vfoodId\":2000000164011633,\"weight\":1.0},{\"activities\":[],\"additions\":[],\"attributes\":[],\"barCode\":\"\",\"categoryId\":1,\"coupons\":[],\"extendCode\":\"\",\"foodGroup\":null,\"foodType\":3,\"id\":2000000875312119,\"ingredients\":[],\"name\":\"芒果\",\"newSpecs\":[],\"price\":0.01,\"quantity\":1,\"shopPrice\":0.0,\"skuId\":300000896304246530,\"total\":0.01,\"uniqueId\":\"0a3e32186-f85b-416c-acf7-fd6e9ffe3993\",\"userPrice\":0.0,\"vfoodId\":2000000437038422,\"weight\":1.0},{\"activities\":[],\"additions\":[],\"attributes\":[],\"barCode\":\"\",\"categoryId\":1,\"coupons\":[],\"extendCode\":\"\",\"foodGroup\":null,\"foodType\":3,\"id\":2000000875287438,\"ingredients\":[],\"name\":\"西柚\",\"newSpecs\":[],\"price\":0.01,\"quantity\":1,\"shopPrice\":0.0,\"skuId\":300000896284073730,\"total\":0.01,\"uniqueId\":\"0e91538b5-af23-4d73-802b-8a6c5119df0e\",\"userPrice\":0.0,\"vfoodId\":2000000437232043,\"weight\":1.0}],\"name\":\"1号篮子\",\"relatedItems\":[],\"type\":\"normal\"}],\"id\":\"8051640118384963917\",\"income\":0.03,\"instantOrderDeliverTime\":\"2023-07-07T12:27:24\",\"invoice\":null,\"invoiceEmail\":null,\"invoiceType\":null,\"invoiced\":false,\"openId\":\"\",\"orderBusinessType\":0,\"phoneList\":[\"18466813614,727\"],\"pickUpNumber\":0,\"pickUpTime\":\"1970-01-01T08:00:00\",\"shopId\":16****314,\"shopName\":\"饿了么开放平台店铺\",\"specUserPart\":0.0,\"status\":\"unprocessed\",\"superVip\":\"ELEME_SUPER_VIP\",\"taxpayerId\":\"\",\"totalActivityAmount\":0.0,\"totalAmount\":0.04,\"totalPrice\":0.04,\"userExtraInfo\":{\"giverPhone\":\"\",\"greeting\":\"\"},\"userMarketingDescription\":null,\"xyPackFlag\":false}" } ] }

更新记录

V1.2(2023-04-23)

接口调用频率新增 开关形式。

V1.3(2023-06-26)

接口调用频率 新增 不做成开关形式。

V1.4(2023-06-30)

接口调用频率中的方案B新增需要间隔 1 秒的限制,防止平台侧服务器负载过高。

V1.5(2023-07-07)

新增「eleme.msgNew.getPushFailMsg 接口返回示例」

V1.6(2023-11-13)

方案 B 中的:接口返回数据为空则等待 1 分钟后重试 -> 接口返回数据为空则等待 2 分钟后重试

注意事项

需要对订单号做幂等性校验处理。防止消息推送重试与eleme.msgNew.getPushFailMsg 接口获取到相同订单数据,处理后发生不符合业务的情况。

修改消息订阅无需审核,提交后自动通过,通常 5 分钟左右后即可生效,最长 20 分钟,建议业务低峰期操作。

 

FAQ

Q:推送消息接收失败的定义是什么?

A:应用在消息处理完成后,没有回复 HTTP Response的 code = 200 以及body为{“message”:“ok”}

Q:已经订阅/取消订阅 type=10 或者type=217,为什么下单后不会/会推送

A:修改推送消息订阅后,通常 5 分钟左右后即可生效,最长 20 分钟。另外一定要业务低峰期操作,比如凌晨,切换后需要观察直到符合预期。

Q:推送消息数据补偿有什么作用?

A:当开发者配置的【推送URL】异常时,也就是无法正常处理消息返回{“message”:“ok”},也就无法通过type=217感知新订单并进行接单操作。这时候需要通过该方案提供的两个补偿接口,去获取 type=217或者其他履约核心消息,进行兜底操作,保证订单被履约;

Q:推送消息数据补偿 和 订单数据补偿 有什么区别?

A:前者是防止开发者服务异常(无法接收平台的消息推送)时订单无法被履约,后者是防止平台异常(无法推送消息)时订单无法被履约。两个方案都对接后,则能够保证绝大部分情况下订单都被履约。

Q:管理后台设置的【重试次数】= 3,当平台第一次推送失败,第二次推送成功的时候,eleme.msgNew.getPushFailMsg接口能否拿到数据?

A:可以的,所以需要根据订单号做一下幂等,否则的话当平台第二次推送成功,然后eleme.msgNew.getPushFailMsg也拿到数据,就会重复处理。

Q:消息会推送重试几次?

A:

在3分钟内,平台侧最多推送3次,推送失败间隔一分钟重试。设置路径在【管理中心】-【查看应用】-【正式环境】-【重试次数】,每次推送消息中的 requestId 是一致的;

新订单 90 秒 ~ 120 秒 未接单,补推一次,消息中的 requestId 与上面的不一致。所以新订单业务场景,不仅要用requestid + msgType做消息幂等,还需要用订单号做业务幂等。

Q:如何测试,调用eleme.msgNew.getPushFailMsg才能拿到数据?

A:可以在沙箱环境配置一个测试推送 URL,然后暂停服务 或者 不返回 {“message”:“ok”},都属于推送失败,再下一笔测试订单,这时候平台推送消息会推送失败,再调用eleme.msgNew.getPushFailMsg即可获取到推送失败的消息。

Q:调用eleme.msgNew.getPushFailMsg接口返回{"msg":"SANBOX_CONTROL","success":true}?

A:目前沙箱环境临时限制了该接口调用,20230620后重新开放支持。

/template/Home/AllNew/PC/Static