饿了么开放平台部分退(金额退/加料退)场景接入方案

一、文档说明

本文档适用于希望接入订单部分退款能力的第三方开发者或自研商家。文档详细的介绍了已接入部分退能力的应用如何迭代升级为支持金额退/加料退能力的解决方案，之前未接入部分退能力的应用也可以根据此方案接入部分退能力，提升用户侧体验，降低商家因商品套餐质量、漏加配料等场景，用户要求整个商品退款导致的损失。

二、背景说明

以下几个典型场景中，由于平台现有能力只支持整单退或者商品(SKU)维度退款，有可能会导致商家产生额外损失：

套餐中部分餐品有问题，只需要退其中一个商品的金额给用户

用户下单小龙虾之类的称重类商品，收到后发现与实际标注份量不符，只需要退重量不足的金额

用户下单包含加料的奶茶后，如果商家漏加加料，只需要退加料的金额

对商户价值：

套餐商品中只有部分商品不满足用户要求时，只退该商品金额即可，降低商家损失。比如套餐商品是 50 元，套餐中的可乐不满足用户要求，商家可以选择金额退只输入可乐的金额退给用户;

称重类商品与实际标注重量不符时，只退重量不足的金额即可，降低商家损失。比如买了两斤小龙虾，用户发现只有一斤半，商家可以选择金额退输入半斤的金额退给用户；

奶茶漏加加料时，只退加料的钱即可，不用整个商品都退款，降低商家损失。比如用户要求双倍加椰果或者加椰果，商家漏加了，商家可以可以选择加料退，然后退 2个/1个椰果即可;

三、改造范围

已接入下述场景的应用需配合平台完成能力升级改造并上线，如至截止时间（2024.2.29）未完成改造并上线，造成影响较大的服务商/商家，平台将按照违规管理规范进行处罚。

未接入下述场景的应用可以根据自身业务特性选择是否接入

需要改造的应用业务描述	对应接口/消息推送	改造备注
有主动发起部分退款能力的应用	eleme.order.refundPart	改造后商家可以发起金额退/加料退
有查询退款信息并使用的应用	eleme.order.batchGetRefundOrders	改造后商家能查看金额退/加料退相关结构数据。发起部分退能力可以根据自身业务特性选择是否接入
订阅退款相关消息并处理退款业务的应用	type=30、31、32、33、34、35、36、39	改造后商家能查看金额退/加料退相关结构数据。发起部分退能力可以根据自身业务特性选择是否接入

 

四、新旧方案能力对比

本次改造不涉及售中退款/取消，只涉及售后退款链路的两个流程，本次改造完成后：

售后阶段退款模式分三种：整单退、按份数退（配料退、按商品退）、指定金额退；

最多支持发起三次部分退款（之前为两次）。

4.1 三次部分退能力支持说明

第一次发起按份数退	第一次发起指定金额退
第二次发起按份数退	支持（现有能力）	支持
第二次发起按金额退	支持	支持

	第二次发起按份数退	第二次发起指定金额退
第三次发起按份数退	支持	支持
第三次发起按金额退	支持	支持

 

4.2 用户端、商家版(napos)与开放平台(OpenAPI)退款链路改动点

售中（当前支持）	售后（当前支持）	售后（本次改动）
用户端	整单取消	整单退、按份数退（单品）	整单退、按份数退（单品、配料）、指定金额退
商家版	整单取消、按份数取消（单品）	整单退、按份数退（单品）	整单退、按份数退（商品、配料）、指定金额退
开放平台	整单取消(调用eleme.order.cancelOrderLite)	整单退、按份数退（单品）	整单退、按份数退（单品、配料）、指定金额退

 

4.3 新旧版本退款能力说明

开发者可参考下述逻辑对 ERP、自研系统的退款相关流程进行改造

商家发起退款	商家同意退款	商家查看退款信息
当前支持	整单退、按份数退（单品）	整单退、按份数退（单品）	整单退、按份数退（单品）
本次改造后支持	整单退、按份数退（单品、配料）、指定金额退	整单退、按份数退（单品、配料）、指定金额退	整单退、按份数退（单品、配料）、指定金额退

 

五、新旧方案前端对比

5.1 用户端（当前方案）

5.2 用户端（新方案）

5.3 商家版（当前方案）

5.4 商家版（新方案-按份数退）

5.5 商家版（新方案-按金额退）

六、涉及接口及变更

新增接口权限申请路径：管理中心-我的应用-权限升级-数字化工具-聚合订单 or SAAS 系统

SDK依赖版本：Java SDK ≥ V1.30.43

名称(描述)	更新类别	更新内容	备注
eleme.order.queryRefundFoodInfos(查询订单退款商品明细)	新增	新增接口	用于商家发起退款之前，查询订单可以进行部分退款的菜品列表(只能查售后订单，售中订单返回的数据不对)
eleme.order.refundPart(商家部分退款)	更新	入参新增 refundOrderMessage.refundGoodsInfos.quantityType、refundOrderMessage.refundGoodsInfos.money
eleme.order.mgetRefundOrders(批量获取订单退款信息) 、eleme.order.getRefundOrder(获取订单退款信息)、eleme.order.batchGetRefundOrders(批量获取订单退款信息V2)	更新	出参新增ORefundOrder.goodsList.quantityType、ORefundOrder.goodsList.money、ORefundOrder.goodsList.batching	统一使用eleme.order.batchGetRefundOrders，另外两个接口会废弃

七、涉及推送消息及变更

7.1 无需兼容

type = 37、38

7.2 需要兼容

type = 30、31、32、33、34、35、36、39，会在goodsList的每一项下新增如下三个字段：

参数名称	参数类型	参数示例	参数描述
quantityType	String	UNIT或AMOUNT	退款单位类型，类型为UNIT取quantity字段，类型为AMOUNT取money字段(注意如果已经退完，此字段为空)
money	double	2.1	退款金额（元）(注意：如果已经退完，此字段为空)
batching	Boolean	true/false	是否为配料(注意：如果已经退完，此字段为空)

 

八、一句话概述

商家主动发起退款：

先调用 eleme.order.queryRefundFoodInfos(查询订单退款商品明细)(新增) ，查询订单可以进行部分退款的菜品列表；

然后调用 eleme.order.refundPart 发起部分退款。

处理用户发起的退款：

消费「消息推送」与「获取订单退款信息」中新增的字段，用于展示给商家，避免商家看不到最新的金额退/加料退 信息导致的资损；

如有资金计算需求，也需要根据自身业务取最新字段重新计算。

九、开发联调

9.1 完成时间

请务必于2024年2月29日前改造完毕，如逾期未完成改造，造成影响较大的服务商/商家，平台将按照违规管理规范进行处罚。

9.2 灰度策略

沙箱门店默认加入白名单内，现在即可进行功能测试。订单完结后(也就是售后订单)，饿了么 APP 点击【申请售后】，可以选择金额退与加料退。非特殊情况统一用沙箱门店测试联调，特殊需求则提供对应门店 shopId 发送给保障宝，额外进行加白。

线上门店只有开放平台验收通过后，商家版和用户端才会透出此功能（门店维度开放）

十、验收标准

整体流程：保障宝申请技术支持 -> 开发者进入开发阶段 -> 开发完成 -> 联系保障宝 daily 进行平台验收 -> 验收通过 -> 次月激励发放(如有)

10.1 申请技术支持

在保障宝的「集成项目」入口进行提交，选择订单场景-部分退(金额退/加料退)场景接入，提交后如需要技术支持，提供【对接ID】给保障宝daily后，会有专人拉群进行技术支持；

需要验收时，联系保障宝daily提供集成项目对接工单 ID + 接口请求 requestId，平台验收通过后，您应用绑定过的生产门店方可使用该功能，操作方法：集成项目使用说明。

10.2 测试流程

开放平台线上测试店铺绑定您的应用(可选，如有自己的测试店铺可用自己的)。店铺信息：shopId：1184782337、店铺地址：澳门–澳门特别行政区石排湾郊野公园，门店二维码：

10.2.1 商家主动发起部分或整单退款(有主动发起部分退款能力的应用)

第1步：查询可退商品（预咨询）

调用目的：此接口用于商家发起部分退款前，查询订单可以进行部分退款的菜品列表，以便于进行退款信息渲染。

接口：eleme.order.queryRefundFoodInfos

入参：订单ID

返回结果：

第2步：发起部分或整单退款

调用目的：对需要退款的商品发起退款

接口：eleme.order.refundPart 商家部分退款

入参：

返回结果：发起成功、发起失败。

第3步：查询退款结果

调用目的：对账、保持订单状态一致、查询发起退款是否成功

接口：eleme.order.batchGetRefundOrders 批量获取订单退款信息V2

入参：订单ID列表

返回结果：新增了退款单位类型（金额退款AMOUNT，份数退UNIT）、配料

10.2.2 用户发起退款商家处理(有查询退款信息并使用的应用&订阅退款相关消息并处理退款业务的应用)

第1步：接受用户发起退款消息

调用目的：用户发起退款申请时，进行同意或拒绝处理

消息：type=30 用户发起退款

改动点：开放平台消息推送需要兼容的，要在goodsList的每一项下新增如下三个字段：quantityType、money、batching

第1-1步：接收用户取消退款消息（如果用户取消）

调用目的：用户发起退款后，可能会取消退款

消息：type = 31 用户取消退款

改动点：开放平台消息推送需要兼容的，要在goodsList的每一项下新增如下三个字段：quantityType、money、batching

第2步：处理退款

调用目的：处理用户发起的退单，不处理的话订单会到时自动退款

同意接口：eleme.order.agreeRefundLite(同意退单/同意取消单)

拒绝接口：eleme.order.disagreeRefundLite(不同意退单/不同意取消单)

第3-1步：接收商家同意退款消息（如果操作了同意）

调用目的：商家同意退款后，会触发此消息推送

消息：type = 33 商家同意退款

改动点：开放平台消息推送需要兼容的，要在goodsList的每一项下新增如下三个字段：quantityType、money、batching

第4-1步：接收商家拒绝退款消息（如果操作了拒绝）

调用目的：商家同意退款后，会触发此消息推送

消息：type = 32 商家同意退款

改动点：开放平台消息推送需要兼容的，要在goodsList的每一项下新增如下三个字段：quantityType、money、batching

第4-2步：接收拒绝后用户申请仲裁消息（如果用户申请）

调用目的：商家拒绝退款后，用户可以申请仲裁，此时会触发该消息

消息：type=34

改动点：开放平台消息推送需要兼容的，要在goodsList的每一项下新增如下三个字段：quantityType、money、batching

第4-3步：客服仲裁通过

调用目的：用户发起仲裁后，客服同意了退款，触发该消息。

消息：type = 35

改动点：开放平台消息推送需要兼容的，要在goodsList的每一项下新增如下三个字段：quantityType、money、batching

第4-4步：客服仲裁未通过

调用目的：用户发起仲裁后，客服拒绝退款，触发该消息。

消息：type = 36

改动点：开放平台消息推送需要兼容的，要在goodsList的每一项下新增如下三个字段：quantityType、money、batching

第5步：查询退款结果

调用目的：对账、保持订单状态一致、查询发起退款是否成功

接口：eleme.order.batchGetRefundOrders 批量获取订单退款信息V2

入参：订单ID列表

返回结果：新增了退款单位类型（金额退款AMOUNT，份数退UNIT）、配料

十一、注意事项

配料只能份数退，如果batching = true，supportRefundQuantityType 会是 UNIT 或者空集合(超过三次退款、工行渠道、门店不支持)；

部分退可以退剩余全部；

如果订单使用了畅享金、纯享金，不允许金额退。也就是调用eleme.order.queryRefundFoodInfos时，supportRefundQuantityType 只返回UNIT，不返回 AMOUNT；

eleme.order.refundPart 传入的退款商品与加料之间是平铺关系。假设商品 A 下有加料 B、C，需要退加料B，直接传入加料B的 uniqueId 即可

当退到最后一份的时候，只传主品，不传配料，系统会自动退掉下面的配料。假设订单中含有 2 份商品 A ，包含加料 B、C 各两份。第一次部分退款传入 A 的 uniqueId，数量 1 份，那么只会退 A；第二次部分退款传入 A 的 uniqueId，则下面的加料B、C 会自动一起退掉，注意前端联动展示与金额计算，参考【5.4 商家版（新方案-按份数退）】中的图三。商品和加料如何关联可查看该文档：https://open.shop.ele.me/openapi/documents/ingredient_useguide。

十二、处理流程时序图

FAQ

Q：用户申请部分退款后，商家不做任何处理会怎样呢

A：用户发起部分退款后，会倒计时 30 分钟，30 分钟之内不做任何处理，默认会同意退款。

Q：套餐商品支持加料退吗

A：在售后流程中，套餐商品目前只支持金额退，不支持套餐中的子品与加料退。

 

十三、结构体示例

type=30消息，金额退

{ "signature": "17D16D9180A2F93EFBB03B0598FB5000", "requestId": "2401294174911201799", "appId": 45618000, "shopId": 505528000, "type": 30, "message": "{\"goodsList\":[{\"batching\":false,\"money\":0.02,\"name\":\"薯条\",\"price\":0.02,\"quantity\":1,\"quantityType\":\"AMOUNT\",\"skuId\":\"300001078348756883\",\"uniqueId\":\"014f59d22-3739-48af-8b76-4a7965658d6d\",\"vfoodId\":2000000521791005}],\"orderId\":\"8017990064331996640\",\"reason\":\"用户申请退单 \",\"refundImages\":[],\"refundStatus\":\"applied\",\"refundType\":\"part\",\"shopId\":505528000,\"totalPrice\":0.02,\"updateTime\":1706524058}", "userId": "6179136777929458972", "timestamp": 1706524058903 }

type=30消息，加料退