饿了么开放平台订单推拉结合场景接入方案

一、文档说明

本文档适用于希望接入订单处理的第三方开发者或自研商家。文档详细介绍了新订单消息、消息推送、未处理订单的数据补偿以及针对降级单的处理逻辑。接入后，您可以最大程度地保证订单履约成功，降低客诉率。

二、方案概述

推单：推送消息 type=217(订单生效)，推送的字段定义为 订单履约核心字段，只需要这些字段即可保证订单的履约。

拉单：非核心履约场景，比如活动营销等数据的获取，可以使用现有的 eleme.order.getOrder、eleme.order.mgetOrders(入参订单数量<50) 接口获取所需字段。

数据补偿：为了最大限度地保证消息可达，除了平台的一些主动策略，还提供了订单+推送消息的补偿接口，所有有接单场景的开发者必须对接，以确保订单能被成功接单并履约。

降级场景订单处理：在部分特殊情况下，饿了么订单推送系统会出现降级场景，推送的订单字段会缺少部分价格字段，建议在识别到降级单后优先接单，后续再调用 eleme.order.getOrder、eleme.order.mgetOrders(入参订单数量<50)补齐订单信息

新旧方案对比

接口A：eleme.order.confirmOrderLite接口B：eleme.order.getOrder、eleme.order.mgetOrders(入参订单数量<50)

涉及接口及变动

三、所需接口

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

所属服务是否必接/计费标准接口名称描述备注

订单服务必接/免费eleme.order.getUnprocessOrders查询店铺未处理订单获取店铺未接单订单号

订单服务可选/免费eleme.order.getCancelOrders查询店铺未处理的取消单

订单服务可选/免费eleme.order.getRefundOrders查询店铺未处理的退单

新消息服务必接/免费eleme.msgNew.getPushFailMsg获取未拉取的推送失败消息列表获取履约核心消息

新消息服务必接/免费eleme.msgNew.confirmPullMsg向平台确认已成功拉取推送失败的消息获取履约核心消息

消息服务可选/基础eleme.message.getNonReachedMessages获取未到达的推送消息获取履约非核心消息

四、一句话概述

将 type=10 切换到 type=217，这两个消息包含的字段值不一样，请注意核对字段区别后，在业务低峰期进行切换（切换后会有5~20分钟缓存时间）

如果type=217不满足业务需求，请调用eleme.order.getOrder获取剩余字段，并注意消息推送的字段与查询订单接口获取的数据字段区别，需要兼容后再进行小票打印等业务

接入推送消息数据补偿 & 订单数据补偿，也就是接入这三个接口：eleme.order.getUnprocessOrders、eleme.msgNew.getPushFailMsg、eleme.msgNew.confirmPullMsg。前者是防止开发者服务异常(无法接受平台的消息推送)时订单无法被履约，后者是防止平台异常(无法推送消息)时订单无法被履约，都必须接入，接入方案参考：「六、对接方案」

五、推送消息详情

新增 type=217(订单生效)，触发时机与 type=10 一致，在 管理中心-查看应用-正式环境 处订阅（沙箱环境也支持订阅&推送）

type=217 包含字段列举

eleme.order.getOrder接口字段(type=10)type=217字段

顾客送餐地址addressaddress

下单时间createdAtcreatedAt

订单生效时间activeAt

用户实际支付配送费deliverFee

商家替用户承担的配送费merchantDeliverySubsidy

会员减配送费vipDeliveryFeeDiscount

预计送达时间deliverTimedeliverTime

即时单的预计时间instantOrderDeliverTimeinstantOrderDeliverTime

订单备注descriptiondescription

订单详细类目的列表groupsgroups

发票抬头invoiceinvoice

用户收取发票的邮箱invoiceEmailinvoiceEmail

是否预订单bookbook

是否在线支付onlinePaid

订单Ididid

顾客联系电话phoneListphoneList

店铺IdshopIdshopId

店铺绑定的外部IDopenIdopenId

店铺名称shopNameshopName

店铺当日订单流水号daySndaySn

订单状态statusstatus

退单状态refundStatus

下单用户的Id（后续将废弃，使用string类型）userId

下单用户的IduserIdStr

订单总价，用户实际支付的金额，单位：元totalPricetotalPrice

订单原始价格originalPrice

订单收货人姓名consigneeconsignee

订单收货地址经纬度(高德地图坐标系)deliveryGeodeliveryGeo

顾客送餐地址deliveryPoiAddress

顾客是否需要发票invoicedinvoiced

店铺实收incomeincome

饿了么服务费率serviceRate

饿了么抽佣服务费（技术服务费）serviceFee

用户使用津贴（随单代收，周期返还）allowanceServiceFee

饿了么基础物流费（物流系统费）baseLogisticsServiceFee

时段加价timeIntervalMarkUpFee

距离加价distanceIncreaseFee

订单中红包金额hongbao

餐盒费packageFee

增值服务费additionServicePrice

价格加价pricePremiums

订单活动总额activityTotal

店铺承担活动费用shopPart

饿了么承担活动费用elemePart

降级标识downgradeddowngraded

保护小号失效时间secretPhoneExpireTime

订单参加活动信息orderActivities

发票类型invoiceTypeinvoiceType

纳税人识别号taxpayerIdtaxpayerId

冷链加价费coldBoxFee

用户取消原因cancelOrderDescription

用户申请取消时间cancelOrderCreatedAt

抽佣orderCommissions

是否饿了么星选来源baiduWaimai

顾客联系电话consigneePhonesconsigneePhones

订单商品额外信息userExtraInfouserExtraInfo

超级会员标识superVipsuperVip

商家确认出餐时间confirmCookingTime

订单业务类型orderBusinessTypeorderBusinessType

到店自取时间pickUpTimepickUpTime

取货码(用户的取餐凭证,为饿了么订单流水号)pickUpNumberpickUpNumber

用户承担部分（特殊合作商户专用）specUserPartspecUserPart

是否是企业订餐订单isBusinessOrder

是否是拼团订单pinTuanOrder(已经废弃，只会返回 FALSE)

扩展信息extraJsonextraJson

订单来源标签orderSourceTag

配送费优惠logisticsActivity

增值服务费（店铺推广）cpcAmount

商户公益捐赠金额(以元为单位)contributionAmount

预计配送时间 是否展示时间片信息timeSlicetimeSlice(后续加入)

时间片开始时间timeSliceStarttimeSliceStart(后续加入)

时间片结束时间timeSliceEndtimeSliceEnd(后续加入)

物流标品iddeliveryProductIddeliveryProductId

品牌会员信息 brandMemberInfo

是否使用x+y服务包的标识xyPackFlagxyPackFlag

履约服务费fulfillServiceFeefulfillServiceFee

总合计金额totalAmounttotalAmount

总优惠金额totalActivityAmounttotalActivityAmount

配送费原价 + 餐盒费deliveryPackageFeedeliveryPackageFee

城市名称cityName

爱心商家捐赠金额publicWelfareGoodsFee

商户和收货人之间的距离,单位米distanceBetweenMerchantsAndConsignee

type=217 消息示例

{ "signature": "C16EF9DC5402A0********70951007D8", "requestId": "6110000********3556", "appId": 5****777, "shopId": 111****187, "type": 217, "message": "{\"address\":\"【隐私保护】顾客地址已隐藏，您可登录饿了么商家端或骑手端查看\",\"book\":false,\"consignee\":\"吴**\",\"consigneePhones\":[\"181****8581\"],\"createdAt\":\"2023-06-29T23:59:59\",\"daySn\":154,\"deliverTime\":null,\"deliveryGeo\":\"1**.619996,**.983583\",\"deliveryPackageFee\":7.75,\"deliveryProductId\":58,\"description\":\"依据餐量提供餐具\",\"downgraded\":false,\"extraJson\":\"{\\\"originalDeliverFee\\\":\\\"4.5\\\",\\\"deliveryActivityFee\\\":\\\"0.0\\\"}\",\"fulfillServiceFee\":-2.4,\"groups\":[{\"items\":[{\"activities\":[],\"additions\":[],\"attributes\":[],\"barCode\":\"\",\"categoryId\":1,\"coupons\":[],\"extendCode\":\"\",\"foodGroup\":null,\"foodType\":0,\"id\":2351159723,\"ingredients\":[],\"name\":\"草原大牛肉串·真火炭烤（牛气冲天）.\",\"newSpecs\":[],\"price\":6.0,\"quantity\":1,\"shopPrice\":0.0,\"skuId\":10000********32532,\"total\":6.0,\"uniqueId\":\"6cefe4a4c-ff51-4d40-adb6-a44c4e0b8dd2\",\"userPrice\":0.0,\"vfoodId\":2102426040,\"weight\":1.0},{\"activities\":[],\"additions\":[],\"attributes\":[],\"barCode\":\"\",\"categoryId\":1,\"coupons\":[],\"extendCode\":\"\",\"foodGroup\":null,\"foodType\":0,\"id\":2351063526,\"ingredients\":[],\"name\":\"烤掌中宝\",\"newSpecs\":[],\"price\":5.0,\"quantity\":1,\"shopPrice\":0.0,\"skuId\":100000694184764852,\"total\":5.0,\"uniqueId\":\"32ef5b12c-aadb-4be3-a56c-e35f1a05dbdf\",\"userPrice\":0.0,\"vfoodId\":2102401205,\"weight\":1.0},{\"activities\":[],\"additions\":[],\"attributes\":[],\"barCode\":\"\",\"categoryId\":1,\"coupons\":[],\"extendCode\":\"\",\"foodGroup\":null,\"foodType\":0,\"id\":2351151258,\"ingredients\":[],\"name\":\"烤牛蹄筋.\",\"newSpecs\":[],\"price\":6.0,\"quantity\":1,\"shopPrice\":0.0,\"skuId\":1000********391924,\"total\":6.0,\"uniqueId\":\"23333ab24-****-****-83b1-1dc66e06e130\",\"userPrice\":0.0,\"vfoodId\":2102480226,\"weight\":1.0},{\"activities\":[],\"additions\":[],\"attributes\":[{\"extCode\":null,\"name\":\"任选\",\"value\":\"烤年糕\"}],\"barCode\":\"\",\"categoryId\":1,\"coupons\":[],\"extendCode\":\"\",\"foodGroup\":null,\"foodType\":0,\"id\":2351118250,\"ingredients\":[],\"name\":\"★任意6种烤串#限购1串收藏门店加购哦[烤年糕]\",\"newSpecs\":[],\"price\":2.8,\"quantity\":1,\"shopPrice\":0.0,\"skuId\":1000********849332,\"total\":2.8,\"uniqueId\":\"9ab9d0ab9-****-****-907e-674aaa6e8512\",\"userPrice\":0.0,\"vfoodId\":2102448675,\"weight\":1.0},{\"activities\":[],\"additions\":[],\"attributes\":[],\"barCode\":\"\",\"categoryId\":1,\"coupons\":[],\"extendCode\":\"\",\"foodGroup\":null,\"foodType\":0,\"id\":2351127066,\"ingredients\":[],\"name\":\"烤面筋.\",\"newSpecs\":[],\"price\":4.88,\"quantity\":1,\"shopPrice\":0.0,\"skuId\":100000694128895412,\"total\":4.88,\"uniqueId\":\"1a06a435e-****-****-9fb9-4583e4997e91\",\"userPrice\":0.0,\"vfoodId\":2102391114,\"weight\":1.0},{\"activities\":[],\"additions\":[],\"attributes\":[],\"barCode\":\"\",\"categoryId\":1,\"coupons\":[],\"extendCode\":\"\",\"foodGroup\":null,\"foodType\":0,\"id\":2351098274,\"ingredients\":[],\"name\":\"★★★随机免费10小串（限10串）\",\"newSpecs\":[],\"price\":0.01,\"quantity\":10,\"shopPrice\":0.0,\"skuId\":100000********8884,\"total\":0.1,\"uniqueId\":\"759144821-d3e7-4b0a-a70d-485e7ef4c9f4\",\"userPrice\":0.0,\"vfoodId\":2102470746,\"weight\":1.0},{\"activities\":[],\"additions\":[],\"attributes\":[],\"barCode\":\"\",\"categoryId\":1,\"coupons\":[],\"extendCode\":\"\",\"foodGroup\":null,\"foodType\":0,\"id\":2351107748,\"ingredients\":[],\"name\":\"★微辣#就放一点点辣椒\",\"newSpecs\":[],\"price\":0.0,\"quantity\":1,\"shopPrice\":0.0,\"skuId\":100000********9876,\"total\":0.0,\"uniqueId\":\"51c4355de-ccfd-****-ad36-21deef5fcc22\",\"userPrice\":0.0,\"vfoodId\":2102427141,\"weight\":1.0},{\"activities\":[],\"additions\":[],\"attributes\":[],\"barCode\":\"\",\"categoryId\":1,\"coupons\":[],\"extendCode\":\"\",\"foodGroup\":null,\"foodType\":0,\"id\":2351084652,\"ingredients\":[],\"name\":\"草原大羊肉串·真火炭烤.\",\"newSpecs\":[],\"price\":6.0,\"quantity\":1,\"shopPrice\":0.0,\"skuId\":100000694128886196,\"total\":6.0,\"uniqueId\":\"8e2c17ef6-0f02-4292-9b94-d49ab0d1a543\",\"userPrice\":0.0,\"vfoodId\":2102391105,\"weight\":1.0},{\"activities\":[],\"additions\":[],\"attributes\":[],\"barCode\":\"\",\"categoryId\":1,\"coupons\":[],\"extendCode\":\"\",\"foodGroup\":null,\"foodType\":0,\"id\":2351164988,\"ingredients\":[],\"name\":\"烤牛肚.\",\"newSpecs\":[],\"price\":7.2,\"quantity\":1,\"shopPrice\":0.0,\"skuId\":100000********9492,\"total\":7.2,\"uniqueId\":\"026951760-****-****-b9fd-547d85085bbd\",\"userPrice\":0.0,\"vfoodId\":2102401181,\"weight\":1.0},{\"activities\":[],\"additions\":[],\"attributes\":[],\"barCode\":\"\",\"categoryId\":1,\"coupons\":[],\"extendCode\":\"\",\"foodGroup\":null,\"foodType\":0,\"id\":2351162144,\"ingredients\":[],\"name\":\"烤牛板筋.\",\"newSpecs\":[],\"price\":7.2,\"quantity\":1,\"shopPrice\":0.0,\"skuId\":100000694194835892,\"total\":7.2,\"uniqueId\":\"492d4d58c-d06c-4b06-988f-f5a49754c5ae\",\"userPrice\":0.0,\"vfoodId\":2102469679,\"weight\":1.0}],\"name\":\"1号篮子\",\"relatedItems\":[],\"type\":\"normal\"},{\"items\":[{\"activities\":[],\"additions\":[],\"attributes\":null,\"barCode\":\"\",\"categoryId\":102,\"coupons\":[],\"extendCode\":\"\",\"foodGroup\":null,\"foodType\":0,\"id\":-70000,\"ingredients\":[],\"name\":\"餐盒\",\"newSpecs\":null,\"price\":3.25,\"quantity\":1,\"shopPrice\":0.0,\"skuId\":-1,\"total\":3.25,\"uniqueId\":null,\"userPrice\":0.0,\"vfoodId\":0,\"weight\":null}],\"name\":\"其它费用\",\"relatedItems\":[],\"type\":\"extra\"}],\"id\":\"80043********764905\",\"income\":13.7,\"instantOrderDeliverTime\":\"2023-06-30T00:31:59\",\"invoice\":null,\"invoiceEmail\":null,\"invoiceType\":null,\"invoiced\":false,\"openId\":\"\",\"orderBusinessType\":0,\"phoneList\":[\"17*****4317,634\"],\"pickUpNumber\":0,\"pickUpTime\":\"1970-01-01T08:00:00\",\"shopId\":1110814187,\"shopName\":\"饿了么\",\"specUserPart\":0.0,\"status\":\"unprocessed\",\"superVip\":\"NOT_VIP\",\"taxpayerId\":\"\",\"totalActivityAmount\":-34.9,\"totalAmount\":52.93,\"totalPrice\":18.03,\"userExtraInfo\":{\"giverPhone\":\"\",\"greeting\":\"\"},\"userMarketingDescription\":null,\"xyPackFlag\":true}", "userId": "6385********6481810", "timestamp": 1688054399776 }

六、对接方案

6.1 订单履约(必接)

在 管理中心-查看应用-正式环境 处订阅 type=217 消息，当消息推送后，根据业务按需将关键字段落库，并根据订单号调用 eleme.order.confirmOrderLite 接口进行接单操作，建议只需要该消息体中的字段即可完成接单操作，避免过多的业务校验与强依赖导致拒单。

完成上述流程并开发测试验收完毕后，在系统版本上线前可以将 type=10 取消订阅，以节省成本，不需要两个消息同时订阅。

6.2 对接推送消息数据补偿(必接)

具体接入方案可查看该文档：推送消息补偿接入场景方案

6.3 对接订单数据补偿(必接)

具体接入方案可查看该文档：订单数据补偿接入场景方案

6.4 降级场景订单处理方案(必接)

具体接入方案可查看该文档：降级场景订单处理方案

七、验收标准

改造完成后可采用灰度策略(如有)分批上线，全量上线后联系「保障宝 daily」告知「应用ID」即可进行验收（需先加入保障宝，然后钉钉直接搜索 保障宝daily 即可）。

7.1 消息推送

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

7.2 接口调用

以下接口有调用

接口调用频率符合要求(具体调用频率在「五、对接方案」有详细说明)

八、 注意事项

type=10 与 type=217 只要订阅了就都会推送，推送时机相同，基本同时推送；

type=10 与 type=217 切换尽量选择夜间业务低峰期进行操作；

前期 type=10 和 type=217 可以同时订阅，避免type=217 处理失败后订单无法处理（开关形式，默认只接受 type=10消息但不处理，如type=217 处理异常，则开始处理 type=10消息）；

正式环境切换到 type=217后，需要在当日午高峰、晚高峰盯盘，当出现异常时能够快速切换到type=10进行止血；

正式上线后业务稳定运行无其他异常，可以将 type=10 取消订阅，以节省成本，不需要两个消息同时订阅；

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

九、处理流程时序图

十、售前集成申请

如果在对接中遇到困难，需要平台侧技专项术支持，可以在保障宝的「集成对接」入口进行申请，操作方法：保障宝集成对接功能使用指导

更新记录

V1.0（2023-04-25）

新增文档

V1.1（2023-06-27）

新增 FAQ 部分

V1.2（2023-07-03）

新增 注意事项 部分

V1.3（2023-07-07）

新增 一句话概述 部分

V1.4（2023-07-1）

新增 售前集成申请 部分

FAQ

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

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

Q：推送消息数据补偿有什么作用？

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

Q：订单数据补偿 有什么作用？

A：当平台的消息推送服务出现异常时，无法推送消息给开发者，这时候则需要通过该方案提供的接口去获取待接单订单，进行兜底操作，保证订单被履约；