youzan-datahub/docs/餐饮零售数据中台/有赞接口/6.查询售后单列表 (youzan.trade.refund.search.3.0.1).md

查询售后单列表 (youzan.trade.refund.search.3.0.1)

1. 接口基本信息

• API 名称：查询售后单列表
• API 接口名：youzan.trade.refund.search
• 版本号：3.0.1
• 计费规则：基础接口，调用计费
• 接口描述：用于按条件（如时间范围、订单号、状态等）分页查询店铺内的退款及售后单据列表。注意：如果入参没有设置查询时间范围，接口默认查询创建时间为近 3 个月的单据。

---

2. 请求说明

• 请求协议：HTTPS

• 请求方式：POST (请求体传参，application/json 格式)

• 请求地址：

  https://open.youzanyun.com/api/youzan.trade.refund.search/3.0.1
  

---

3. 请求参数

在请求体（Body）中传入以下 JSON 参数：

参数名称	类型	是否必填	参数说明
access_token	String	是	鉴权凭证，用于请求 API
tid	String	否	有赞订单号（E开头+年月日时分秒+随机数，长24位）
refund_id	String	否	售后退款单号
yz_open_id	String	否	(3.0.1新增) 有赞用户 ID，买家在有赞的唯一身份标识
create_time_start	Long	否	创建起始时间，Unix时间戳（单位：秒）。不传则默认近3个月
create_time_end	Long	否	创建截止时间，Unix时间戳（单位：秒）
update_time_start	Long	否	更新起始时间，Unix时间戳（单位：秒）
update_time_end	Long	否	更新截止时间，Unix时间戳（单位：秒）
page_no	Integer	否	分页数，page_no > 100 会报错“查询页数超过100”
page_size	Integer	否	每页显示个数，page_no * page_size > 3000 会报错“超过ES搜索最大深度”
status	String	否	退款状态： WAIT_SELLER_AGREE: 等待卖家同意 WAIT_BUYER_RETURN_GOODS: 等待买家退货 WAIT_SELLER_CONFIRM_GOODS: 等待卖家确认收货 SELLER_REFUSE_BUYER: 卖家拒绝退款 CLOSED: 退款关闭 SUCCESS: 退款成功 CUSTOMER_SERVICE_IN: 客满介入 SELLER_REFUSE_BUYER_RETURN_GOODS: 卖家拒绝收货，待买家处理 SELLER_RETURN_GOODS: 商家确认收货并发送换货
type	Integer	否	退款流程类型：1(买家申请退款), 2(商家主动退款), 3(一键退款), 4(零售门店换货), 5(微商城换货)
demand	Integer	否	退款诉求：1(仅退款), 2(退货退款), 3(换货)
phase	Integer	否	退款阶段：1(售中), 2(售后)
refund_mode	Integer	否	退款资金类型：0(原路退), 1(现金退), 2(标记退)
search_tag	Integer	否	退款单列表查询 Tag：0(待商家处理), 1(待买家处理), 2(客服介入中)
delivery_status	Integer	否	发货状态：1(未发货), 2(已发货)
sku_no	String	否	商品规格编码
goods_title	String	否	商品名称（支持模糊搜索）
delivery_no	String	否	物流单号
node_kdt_id	Long	否	分店店铺 ID（连锁场景使用）
sale_way	Integer	否	销售渠道：1(门店), 2(网店)
return_stock_status	Integer	否	退货归还库存状态：0(无需入库), 10(待入库), 20(归还库存成功)
cs_status	Integer	否	客服介入状态：1(不需要), 2(需要), 3(介入结束)
buyer_phone	String	否	买家电话
invalid	Integer	否	是否为无效的退款单：1(true无效), 0(false有效)
pay_type / pay_way	Integer	否	支付类型与支付渠道（如微信、支付宝、储值卡等细分枚举，详见官方码表）

---

4. 响应参数

响应主体包裹在 data 中，返回当前搜索条件下的退款单总数和详情列表。

根级参数名称	类型	描述说明
success	Boolean	请求是否成功 (true/false)
code	String / Int	成功失败状态码，200 表示成功
message	String	成功或错误提示信息
data	Object	查询结果总包
└─ total	Integer	匹配到的单据总数
└─ refunds	Array	退款信息明细列表

4.1 refunds 数组内核心业务字段解构

内部参数名称	类型	核心说明
refund_id	String	退款 ID / 售后单号
tid	String	关联的有赞订单号
kdt_id	Long	产生该单据的店铺 ID
node_kdt_id	Long	产生该单据的子店/网点 ID
status	String	退款状态。枚举同请求入参 status
return_goods	Boolean	是否退货
refund_fee	String	申请退款的金额（如 "0.01" 元）
reason	Integer	退款原因代码。 常见：54(未按约定时间发货), 11(质量问题), 104(拍错/不喜欢) 等。系统退款：204(订单关闭), 208(拼团未成团) 等。
created	String	退款申请创建时间（格式 "yyyy-MM-dd HH:mm:ss"）
modified	String	退款申请最后修改时间（格式 "yyyy-MM-dd HH:mm:ss"）
cs_status	Integer	客满介入状态：1(客满未介入)，2(客满介入中)
delivery_status	Integer	发货状态：1(未发货)，2(已发货)

---

5. ⚠️ 开发者防坑指南与注意事项（核心对账与排错必看）

1. 版本升级核心变化 (yz_open_id 替代 buyer_id)： 在 3.0.1 最新版本中，废弃了原有的 buyer_id，全面拥抱 yz_open_id 作为用户的全网唯一标识。在进行 CRM 对账或跨接口（如用户详情查询接口）数据互通时，必须使用 yz_open_id。
2. 时间戳参数单位陷阱（必须是秒）： 有赞的大多数接口时间戳为 13位毫秒级，但是该版本接口明确标注 create_time_start / update_time_end 等字段的单位为：秒（10位）！ 如果错误传入了 13 位时间戳，会导致报错或过滤结果为空。
3. ES 搜索引擎的深度翻页限制（报错码 53002）： 受限于底层 Elasticsearch 架构，请严格遵守以下分页限制，否则会报错 page_size type error 或导致接口熔断：
   • page_no 不能大于 100。
   • page_no * page_size 乘积不能超过 3000。
   • 排错方案：大店单据多时，绝不可用大分页数无脑遍历。请按更新时间将范围切分得更细（如每次只查 1 小时的数据），来保持总条数低于限制阈值。
4. 单据默认时间范围（3 个月内）： 如果您在请求时不加任何时间限制直接查询，系统会自动添加默认过滤条件，仅返回最近 3 个月创建的退款单。对于旧账对账或初始化历史数据同步，务必显式传入准确的时间范围边界。
5. 网点/门店单据的隔离（node_kdt_id）： 如果是连锁商家总部进行数据拉取，通过总部的 Token 默认只能拉取总部的单据。必须通过循环传递 node_kdt_id 才能精准拉取到各分店发生的维权与退款记录，切勿遗漏导致财务对账不平。