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

版本说明

版本更新时间更新内容

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消息，开发者都可以通过以上方式识别到一起收餐的所有订单号。