关于我们

饿了么开放平台拼团订单场景接入方案

发布时间:2025-05-27

 

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

版本说明

版本更新时间更新内容

V1.02024.05创建拼团订单一起收餐对接的方案说明

V2.02024.12.3新增6.3 非拼团单一起收的下单方法和订单处理差异化说明

V2.12024.12.5新增4.1.5 确认接单中的第5点说明:补打或者延迟打印小票处理逻辑

V2.22024.12.30修改4.2 、4.2.2、6.3 中关于拼团+一起送的逆向业务原则:拼团一起收餐售后现在支持部分退金额的,原来不支持

 

一、文档说明

本文档适用于希望接入拼团业务的第三方开发者或者自研商家。文档详细介绍了拼团业务和拼团一起收餐订单在推单、接单、打印、出餐、配送、退款等各业务环节的改造点。本期输出给服务商的属于完整方案,即对服务商而言,无论平台配送商家还是自配商家,是只接单应用还是订单处理全链路应用,都可参照此对接方案做应用的迭代升级,支持拼团一起收餐的业务。

二、业务介绍

2.1 什么是饿了么拼团?

饿了么拼团是针对同一家门店下单,收货地址相同或相近的不同顾客推出由单独购买、拼团各自收餐、拼团一起收餐(对应的点餐价格依次降低)三种方式下单的外卖活动,以较低价格吸引顾客下单购买。

2.2 什么是拼团一起收餐?

 

饿了么拼团一起收餐履约模式:基于C侧一起收餐的机制(同取同送),将多笔一起收订单,转化为同单多篮子作业。

饿了么拼团各自收餐履约模式:与普通外卖餐饮订单相同,只是有拼团单的标识和C端营销上的优惠。

注意:拼团的商家不区分商家类型,所以包含平台配送和自配送商户(选推商户 & 纯自配商户)。

2.3 拼团一起收餐产品定位

在拼团一起收餐模式下,通过将同一个团单下一起收订单,转化为同单多篮子作业。

2.4 拼团一起收餐在开放平台交互链路


接单的服务商需要将主单和子单汇合打印出一张小票。

三、改造概述

一句话总结需要改什么:接单相关老接口字段新增一起收餐的识别,本次新业务对接单、打印、出餐、退款、配送的业务处理逻辑变更。

简化版改造点总结:

a. 接口类:

   i. eleme.order.getOrder、mgetOrders、getAllOrders新增3个拼团字段。

   ii. 其他接口均是对拼团单的后端处理逻辑变更,开发者的应用若不限制这些接口调用,饿侧也会做拦截,返回报错或者查询结果中没有子单的订单号等,需要开发者识别这些报错信息,并理解报错为正常业务处理。

b. 消息类:

   i. 217消息体内新增3个拼团字段。

   ii. 子单将不再发送218订单小票打印消息

   iii. 售中取消订单时,开发者不会收到子单相关的用户申请类的消息:用户发起退单消息推送接口(type = 20、30)、用户申请仲裁(type=24、34),可参见4.2章节详细说明

   iv. 消息补偿类接口也不会返回子单的218消息、用户申请取消类消息(20、30、24、34)

 

3. 标注【必改】的为必须改造的,若接单的服务商不支持拼团业务,而商家又开通了一起送服务包和上架了拼团商品,实际商家履约时,因服务商未改造完成,导致商家实际还是一单单打印和处理,未达到一起收餐、一起送的效果。非必改的,涉及拼团业务逻辑变更,开发者可根据自身应用情况选择性修改,若开发者侧不限制对子单的操作,饿侧也会限制报错。

四、一起收餐改造清单

4.1 正向接口及消息改造

4.1.1 推单消息改造【必改】

涉及接口:217

主要改造点:a. 新增拼团字段(布尔类型)ptOrder,枚举概念如下:false-非拼团单,true-拼团单。b. 新增商家履约作业模式 字段merchantFulfillJobMode:一起送 BATCH , COMMON或者null表示非一起送c. 新增拼团扩展信息字段ptOrderExtraData:i. 当前单主单(团长)or 子单(团员)ii. 团单内所有订单IDiii. 团单内所有订单流水号【说明】:分开送跟普通订单一样,只需要对一起送做识别就可以。且只有merchantFulfillJobMode=BATCH合单模式时,拼团扩展信息字段ptOrderExtraData才有赋值关于一起收餐的识别:饿侧未来还会扩展非拼团的一起收餐业务,因此建议ISV识别到merchantFulfillJobMode是batch的时候就可以认为是一起收餐的业务;一起打印小票时,小票上要不要展示【拼团】字样,可以看ptOrder是否为true。

217订单生效消息结构示例:详见217消息结构

4.1.2 云打印消息改造【必改】

涉及接口:218消息

按照NAPOS小票样式改造,核心改动点:若遇到拼团一起送订单,通过主单打印新小票,子单不打印小票。

主单:点击主单打印小票,只出一张小票(聚合子单商品信息)

子单:不发送218消息

主单小票改动点
(1)涉及小票类型:
a. 商家联、用户联、后厨联
(2)标题:
b. 拼团单:展示「饿了么拼团」
c. 拼团一起收餐单:展示「饿了么拼团」。
(3)将主单全部内容&子单备注、所有菜品、实付金额、营销内容一起打印在主单小票上,按照主单、子单1、子单2的顺序从上往下展示。
后厨联:

顾客联:
顾客联变化:若为拼团⼀起送订单,则⼩票商品区按「1号拼友」「2号拼友」….展示备注、发票、商品、商品⾦额等字段信息。左 1 为顾客联,右 1 为自行配送重新打印顾客联。

4.1.3 订单查询接口改造【必改】

涉及接口:eleme.order.getOrder、mgetOrders、getAllOrders

主要改造点:
a. 新增拼团字段(布尔类型)ptOrder,枚举概念如下:false-非拼团单,true-拼团单。
b. 新增商家履约作业模式 字段merchantFulfillJobMode:一起送 BATCH ,非一起送 COMMON
c. 新增拼团扩展信息字段 ptOrderExtraData:

4.1.4 备注修改消息

涉及接口:type = 214

主单:主单修改备注后,触发主单的214消息回流。

子单:子单修改备注后,触发子单的214消息回流。子单实际在用户C端不会露出的修改备注入口。

4.1.5 确认订单【必改】

涉及接口:确认订单 eleme.order.confirmOrderLite

主单改造:ISV对主单接单,先返回成功,饿了么后台会对主单先接单成功后,再对子单一并接起,若是子单失败,10s后会再次重试(主单接单成功,子一定会成功;主单失败,子单一定失败)

子单改造:ISV对子单接单,接口会返回成功,实际不会处理(饿了么后台不一定是真成功),建议也对子单做接单操作
若开发者一定需要明确订单状态才能做处理的,出现主单和子单状态不一致时,【处理建议】批量查询mgetOrders主子订单状态,若存在子单未接单,每隔20s以上再去查询。

接单后服务商自行打印小票:若遇到拼团一起送订单,通过主单打印新小票,子单不打印小票。
主单:主单打印小票,只出一张小票(聚合子单商品信息)

补打或者延迟打印小票(接单后不立即打印小票):

主单:需要展示打印按钮

子单:自行选择是否屏蔽打印按钮,建议不屏蔽(因会有非拼团一起收餐的场景详见6.3章节)

处理逻辑:需要补打或者延迟打印时,请使用eleme.order.mgetOrders接口重查一起收餐的最新订单信息,依最新接口返回来打印。重查原因是非拼团一起收餐的订单支持售中主子单各自单独取消,如预订单追单#1#2#3合单成功后,#1主单被取消,需要重新打印小票,这时mgetOrders新合单信息里只有#2#3信息,#2单会变成新主单。

 

4.1.6 拒绝接单

涉及接口:取消订单 eleme.order.cancelOrderLite

主单改造:无需改造,主单拒单后,自动将子单也取消

子单改造:接口返回报错,不能对子单拒单

4.1.7 出餐

涉及接口:
a. 商家确认已完成出餐 eleme.order.setOrderPrepared
b. 查询已出餐列表 eleme.order.getPreparedTimesByOrderIds
c. 订单预计出餐时间 eleme.order.orderPredictFinishTime

主单改造:ISV对主单出餐,先返回成功,饿了么后台会对主单先出餐成功后,再对子单自动出餐。

子单改造:ISV对子单出餐,返回成功,实际不会处理(饿了么后台不一定成功)
若开发者一定需要明确订单状态才能做处理的,出现主单和子单状态不一致时,【处理建议】可通过批量查询getPreparedTimesByOrderIds出餐订单,若存在子单未出餐成功,每隔20s以上再去查询。

查询接口无变更

4.1.8 催单相关

C端消费者侧屏蔽子单给骑手发消息的入口

涉及接口:
a. 回复催单 eleme.order.replyReminder
b. 获取店铺未回复的催单 eleme.order.getUnreplyReminders

主单改造:无需改造

子单改造:子单用户不能发催单,所以也不需要回复催单

4.2 逆向接口及消息改造

拼团+一起送的逆向业务原则:

订单售中售后

主单1. 不支持部分退;
2. 支持整单退,退主单时自动退子单;
3. 退款原因:商户或用户真正填写的原因1. 支持部分退金额;
2. 支持整单退,退主单时不会自动退子单;
3. 退款原因:商户或用户真正填写的原因

子单1. 不支持部分退;
2. 不支持整单退;
3. 退款原因:子单由于是系统根据主单联动处理的,出于判责的考虑,子单返回的退款原因是“系统原因”1. 支持部分退金额;
2. 支持整单退;
3. 退款原因:商户或用户真正填写的原因

【一起收餐特殊场景】售中主单发起退款申请后,在退款进行中时,主子单各自的订单状态可能会不一致。
例如:用户申请取消后,主单状态为“退款中”,还未操作同意退款期间,子单状态不是“退款中”,只有主单同意退款后,才会联动将子单退款,子单状态才会更新。
【处理建议】开发者侧在订单售中期间,也直接禁止对子单的任何退款操作,若对子单取消,接口会返回报错。识别主单的退单完成消息(type=22、23、25、26、32、33、35、36、37、38)时,若是对主单和子单查询获取的订单状态不一致,可每间隔20s后再对子单重查。(子单type=20、30、21、31用户发起的动作消息都不会推送给服务商)

拼团+分开送的逆向业务原则:
售中、售后都支持订单整单退和部分退(拼团的部分退仅支持部分退金额)

4.2.1 场景一:用户发起取消

涉及接口改造说明


a. 用户发起退单消息推送接口(type = 20、30)
b. 用户取消退单(type = 21、31)。
c. 商家同意退单接口(type =23、 33)。
d. 商户不同意退单接口(type =22、 32)。
e. 获取订单退款信息接口eleme.order.getRefundOrder
f. 批量获取订单退款信息eleme.order.mgetRefundOrders
g. 批量获取订单退款信息V2 eleme.order.batchGetRefundOrders
h. 查询店铺未处理的退单 eleme.order.getRefundOrders1. 主单改造:当主单商家同意退单or拒绝退单时,主子单均批量处理后,自动触发主单和子单处理结果的消息回流。
2. 子单改造:用户申请取消的时候,不会同步发送子单的退款申请消息(type =20、 30),只会在主单退款成功的时候,一并取消子单,推送子单处理完成的消息给ISV

4.2.2 逆向场景二:商家在开放平台发起取消

涉及接口改造说明


a. 发起部分退款接口:eleme.order.refundPart
b. 同意退单/同意取消单 eleme.order.agreeRefundLite
c. 不同意退单/不同意取消单 eleme.order.disagreeRefundLite
d. 获取订单退款信息接口eleme.order.getRefundOrder
e. 批量获取订单退款信息eleme.order.mgetRefundOrders
f. 批量获取订单退款信息V2 eleme.order.batchGetRefundOrders
g. 查询店铺未处理的退单eleme.order.getRefundOrders1. 主单改造:
a. 售中整单退,联动自动退子单;售中部分退,返回报错;
b. 售后整单退,只退主单;售后部分退,仅支持金额部分退
2.子单改造:
a. 售中整单退/部分退,返回报错,原因(请对拼团主单发起退款);
b. 售后整单退,只退子单;售后部分退,仅支持金额部分退

4.2.3 逆向场景三:商家在饿了么商家端发起取消

对isv来说,这种场景没有改动。

涉及接口改造说明

无1. 主单改造:无需改造。
2. 子单改造:售中不能发起不会触发消息推送、售后发起时按照普通订单触发消息推送。

4.2.4 逆向场景四:客服发起取消/仲裁

涉及接口改造说明

a. 用户申请仲裁 (type=24、34)b. 仲裁有效 (type=25、35)c. 仲裁无效36(type=26、36)1. 主单改造:无需改造。
2. 子单改造:
a. 售中:由于由系统根据主单仲裁申请自动关联处理子单退款,给ISV推送仲裁结果消息,不会推24、34的消息。
b. 售后:可正常发起退款。

4.3 配送接口及消息改造

4.3.1 配送信息回流消息

涉及接口改造说明

a. 待分配配送商(type = 51);b. 待分配配送员(type = 52);c. 配送员待取餐(type = 53);d. 配送员已到店(type = 54);e. 配送员配送中(type = 55);f. 配送成功(type = 56);g. 配送取消,商户取消(type = 57);h. 配送取消,用户取消(type = 58);i. 配送取消,物流取消(type = 59);j. 配送失败,呼叫配送晚(type = 60);k. 配送失败,餐厅出餐问题(type = 61);l. 配送失败,商户中断配送(type = 62);m. 配送失败,用户不接电话(type = 63);n. 配送失败,用户退单(type = 64);o. 配送失败,用户地址错误(type = 65);p. 配送失败,超出服务范围(type = 66);q. 配送失败,快递员标记异常(type = 67);r. 配送失败,系统自动标记异常;(type = 68);s. 配送失败,其他异常(type = 69);t. 配送失败,系统标记异常;(type = 70);u. 商家自行配送(type = 71);v. 商家不再配送(type = 72);w. 只支持在线订单(type = 73);x. 超出服务范围(type = 74);y. 请求配送过晚(type = 75);z. 系统异常(type = 76);1. 主单改动点:无需改动。
2. 子单改造:因为子单是以主单状态更新为触发源,主单状态变化时同步子单一起变化,所以子单再发生上述节点更新时候也会触发对应消息发给isv。

4.3.2 配送相关接口

涉及接口主单子单

呼叫配送 eleme.order.callDelivery若门店签约蜂鸟专送等平台配送服务包,支持呼叫;
若门店签约蜂鸟跑腿服务包,不支持呼叫;
--这个规则是拼团的业务就是这样的,不区分是否一起送。不支持,直接报错,去主单操作

获取订单配送记录 eleme.order.getDeliveryStateRecord支持,不变支持,不变(和主单一样)

配送异常或者物流拒单后选择自行配送(推荐) eleme.order.deliveryBySelfLite支持,主单会联动自动处理子单不支持,直接报错,去主单操作

配送异常或者物流拒单后选择不再配送eleme.order.noMoreDeliveryLite支持,主单会联动自动处理子单不支持,直接报错,去主单操作

订单加小费 eleme.order.addDeliveryTipByOrderId不支持,会报错不支持,提示加不成功

批量获取订单加小费信息eleme.order.mgetDeliveryTipInfos支持,只是返回里会告知不支持加小费支持,只是返回里会告知不支持加小费

众包订单询价,获取配送费eleme.order.getDeliveryFeeForCrowd若门店签约蜂鸟专送等平台配送服务包,支持调用;
若门店签约蜂鸟跑腿服务包,不支持调用;不支持,子单询价会报错,跟呼单一样

评价骑手 eleme.order.evaluateRider支持不支持

自配送商家同步运单的位置信息eleme.order.selfDeliveryLocationSync支持,主单的骑手位置变化,饿侧会自动同步子单支持,接口不报错,但实际饿侧不处理

自配送商家同步运单的状态信息eleme.order.selfDeliveryStateSync支持,主单配送信息更新时触发子单配送更新,更新节点(骑手接单、骑手到店、骑手取餐、骑手送达)支持,接口不报错,但实际饿侧不处理
本期子单不接受来自商家开放平台、物流开放平台的配送状态回流,返回success,实际吃掉。

获取订单配送轨迹 eleme.order.delivery.getDeliveryRoutes支持支持查询(轨迹明细会和主单一样)

4.4 订单数据补偿接口

涉及接口与普通外卖单区别

eleme.order.getUnprocessOrders 查询店铺未处理订单接单场景中若是主单联动子单未接单成功时,使用此接口能查到未接单状态的子单。此时,isv若识别为拼团一起收餐的子单,间隔20s后再去查子单状态即可,无需发起对子单的接单操作。

eleme.order.getCancelOrders 查询店铺未处理的取消单(1)若是商家还未对主单做处理,使用此接口只能查到主单,不会返回子单订单号的
(2)用户申请-商家拒绝-用户申请仲裁-客服还未给出仲裁结果时,使用此接口是不会返回子单订单号的

eleme.order.getRefundOrders 查询店铺未处理的退单无变化,因为售后退是主子单单独自己退,与普通外卖单相同

4.5 索赔接口

涉及接口主单子单

批量申请索赔 eleme.order.batchApplyCompensations支持不支持,接口返回里子单会是索赔失败状态

批量查询索赔结果 eleme.order.queryCompensationOrders支持支持

批量查询订单是否支持索赔eleme.order.querySupportedCompensationOrders支持支持

4.6 结算接口

拼团账单没有跟普通账单做标识区分 ,也不区分主单和子单。

五、开发联调

5.1 完成时间

原则上有接单能力的应用都需要升级支持拼团的业务,平台不设置截止时间,开发者可根据业务需求自行排期接入。目前灰度的策略,若是商家授权多家服务商应用中有服务商未改造,商家实际是无法使用一起收餐一起送的能力,会影响您的商家业务拓展。

5.2 饿侧项目的上线节奏

- 5.8日 只有3个查询接口(eleme.order.getOrder、mgetOrders、getAllOrders)和218打印消息, 支持拼团一起收餐字段有返回值赋值,只支持签约平台配送的服务包商家。(217推送时,字段是null值) - 5.15日 支持 217消息推送时拼团一起收餐字段赋值,服务全量上线,支持所有业务接口沙箱环境测试(平台配送相关的接口要线上环境测试)

5.3 isv应用灰度策略

线上正式门店若要支持推送isv拼团一起送的消息,需要满足此门店所有的ISV接单应用均完成改造。ISV开发者改造完成后应用通过饿侧开放平台的验收测试,上线后我们会给应用打标完成改造,不会对开发者的应用再做其他灰度。

C端用户下单后,饿侧会控制拼团的业务在商家履约时是合并订单还是拆分订单处理,保证饿了么商家版和ISV看到的都是一样的。

只饿了么商家端接单只ISV应用接单饿了么商家版+ISV应用在用

合并订单,支持主子单一起批量操作判断所有接单应用是否全部改造完成,若全部改造完成,则合并订单,所有应用都能收到一起收餐的相关赋值; 若未全部改造完成,则拆分订单所有应用收到的消息中ptOrderExtraData、merchantFulfillJobMode赋值是null,商家登录饿了么商家版后台看也是拆单的,只是订单上带着拼团的标签,不能批量操作。同只用ISV接单的商家规则一样只要有应用未改造完的,拼团一起收餐的订单在商家履约时都不会合并订单处理,在饿了么商家版后台看到的订单处理页面,和ISV收到的消息、接口等都是拆分后普通拼团订单,ptOrderExtraData=null、merchantFulfillJobMode=null,ptOrder=true 标识这笔是拼团

六、下单测试方法

6.1 前期准备

1、沙箱店铺需签约拼团一起送的服务包,提交项目集成的工单后,联系保障宝daliy人工签约,或者开发者使用【保障宝】首页-【服务包签约助手】自主完成签约,签约助手默认签约到店自取、自配送、拼团3个服务包。

2、开发者配置拼团商品
沙箱单店操作入口:

饿了么商家版app-商品管理-点击右上角红字【拼】-拼团商品


【说明】:在一起送服务包签约成功后,服务商自行在饿了么商家版app上新建拼团商品(只有签约拼团服务包后才能看见拼团商品新建入口),拼团商品与普通商品不同,创建入口不一样,并且不支持当前开放平台的商品管理接口(eleme.product.item.*)对拼团商品进行增删改。

3、因拼团商品与当前门店商品的创建方式和数据结构不同,因此拼团商品有自己的API对接方案:点此查看

6.2 拼团一起收下单方法

会在保障宝上提供一个拼团下单测试工具,可查询到沙箱门店拼团商品的二维码,开发人员可通过饿了么主站app扫码,直接进入商详页去下单。
保障宝使用介绍

6.3  非拼团单一起收的下单方法

1、提供沙箱测试门店id,给饿了么加单独的灰度

2、下单方法:要求满足下列所有要求

   1)同一个人在2min内连续下2个预订单

   2)预计送达时间差距在0-20min内(最好5min内)

   3)同下单账号、同收货人名称、同收货地址、同收货手机号

   4)下单时选未来超过2小时的送达时间

   5)订单实付< 150元

   6)订单的商品要不一样,或者同商品不同数量

3、说明:非拼团单的一起收餐,推送的217和getorder接口,ptOrder不等于true

4、非拼团一起收餐和拼团一起收餐的订单处理不同点:

拼团一起收餐普通订单一起收餐(预订单追单合单)

订单售中取消(订单完结前)·主单:1.取消主单时联动取消子单;2.不支持部分退

·子单:1.不允许子单售中取消;2.不支持部分退·主单:1.取消主单时不会自动取消子单;2.支持部分退

·子单:1.允许子单售中取消;2.支持部分退

订单售后退(订单完结后)·主单:1. 仅支持金额部分退;2. 支持整单退,退主单时不会自动退子单;

·子单:1.仅支持金额部分退;2. 支持整单退;·主单:1. 支持部分退;2. 支持整单退,退主单时不会自动退子单;

·子单:1.支持部分退;2. 支持整单退;

平台配送·主单:1.对主单的所有配送的状态处理,都会自动同样处理子单;

·子单:1.不支持单独对子单进行操作·主单:1.对主单的所有配送的状态处理,都会自动同样处理子单;但若是取消配送主单,则主单取消成功后,会自动再帮子单进行呼叫配送;

·子单:不支持单独对子单进行操作,但若是取消配送子单,则仅是对平台物流侧发送一个部分退消息,子单会取消配送,主单继续配送。

七、验收标准

整体流程:保障宝提交集成项目 -> 申请技术支持 -> 开发者进入开发阶段 -> 开发完成 -> 联系保障宝 daily 进行平台验收 -> 验收通过 -> 开发者系统发布完成 -> 平台打开应用维度开关

7.1 申请技术支持

在保障宝的「集成项目」入口进行提交,选择订单场景-口袋分装订单场景接入方案,提交后如需要技术支持,提供【对接ID】给保障宝daily后,会有专人拉群进行技术支持,操作方法:集成项目使用说明。

FAQ

Q:如何识别是一起收餐的业务订单
A:关于一起收餐的识别:饿侧未来还会扩展非拼团的一起收餐业务,因此建议ISV识别到merchantFulfillJobMode是batch的时候就可以认为是一起收餐的业务;一起打印小票时,小票上要不要展示【拼团】字样,可以看ptOrder是否为true。

Q:ISV上线后是否可以直接收到拼团一起收餐的业务订单
A:若门店只有您一家接单ISV,且门店开通了一起送服务包,并创建了拼团商品,则可以收到。

Q:线上需要验证平台配送相关接口的时候,用于验证的门店要怎么签约一起送服务包呢?
A:要找门店的BD签,拼团一起送的业务由BD申报开通。

Q:拼团支持几个人参团呢?只有两个人拼团也成功了
A:拼团最多拼4人,最少拼2人。发起者下单后有个5分钟的等待时间,若是到了5分钟后,拼团有2人了,会自动成团;若还是1人则拼团失败;5min内但已有第4个人下单,则4人无需再等待会直接成团成功。

Q:BATCH合单模式怎么理解?怎么识别到一起送的所有订单?
A:当收到一笔订单里merchantFulfillJobMode是BATCH时,表示这是一起送的订单,可通过ptOrderExtraData.curOrderInfo里 gatherRole拼团角色来区分再去识别当前这笔订单是创建者还是参团者的,并且通过ptOrderExtraData.groupOrders能获取本团内所有的参与者的订单号,因此不论是主单先推送217消息,还是子单先推送217消息,开发者都可以通过以上方式识别到一起收餐的所有订单号。

/template/Home/AllNew/PC/Static