< 返回新闻公共列表

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

发布时间：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后重新开放支持。