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