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

## 1. 接口基本信息

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

---

## 2. 请求说明

* **请求协议**：HTTPS
* **请求方式**：POST (请求体传参，`application/json` 格式)
* **请求地址**：

  ```http
  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 | 否 | 退款状态：<br>`WAIT_SELLER_AGREE`: 等待卖家同意<br>`WAIT_BUYER_RETURN_GOODS`: 等待买家退货<br>`WAIT_SELLER_CONFIRM_GOODS`: 等待卖家确认收货<br>`SELLER_REFUSE_BUYER`: 卖家拒绝退款<br>`CLOSED`: 退款关闭<br>`SUCCESS`: 退款成功<br>`CUSTOMER_SERVICE_IN`: 客满介入<br>`SELLER_REFUSE_BUYER_RETURN_GOODS`: 卖家拒绝收货，待买家处理<br>`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 | 退款原因代码。<br>常见：`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` 才能精准拉取到各分店发生的维权与退款记录，切勿遗漏导致财务对账不平。