youzan-datahub/docs/餐饮零售数据中台/有赞接口/2.订单批量查询接口 (youzan.trades.sold.get.4.0.4).md

# 订单批量查询接口 (youzan.trades.sold.get.4.0.4)

## 1. 接口基本信息

* **API 名称**：订单批量查询接口
* **API 接口名**：`youzan.trades.sold.get`
* **版本号**：`4.0.4` （注：4.0.2 及以上版本共用同一套底层结构）
* **请求协议**：HTTPS
* **请求方式**：GET/POST (推荐 POST `application/json`)

## 2. 接口描述

用于按条件批量搜索和查询有赞店铺的订单列表数据。该版本接口已全面升级 `yz_open_id` 作为买家唯一标识，**目前不支持返回 `buyer_id`**。

### ⏱️ 核心查询与排序规则

支持基于订单的创建时间、更新时间和完成时间进行获取。

* **创建时间**：可以获取指定时间内所有的订单。
* **更新时间**：可以获取最新更新的订单，但是该范围内的订单是动态变化的。
* **完成时间**：可以获取指定时间内已完成的订单。

**接口内置排序规则（优先级）**：

1. 只有创建时间 `start_created` 和 `end_created`，按 **创建时间** 排序。
2. 只有更新时间 `start_update` 和 `end_update`，按 **更新时间** 排序。
3. 只有完成时间 `start_success` 和 `end_success`，按 **完成时间** 排序。
4. 同时存在创建时间、更新时间，按 **更新时间** 排序。
5. 同时存在创建时间、完成时间，按 **完成时间** 排序。
6. 同时存在更新时间、完成时间，按 **完成时间** 排序。
7. 同时存在创建时间、更新时间、完成时间，按 **完成时间** 排序。
8. **重要提醒**：如创建或更新或完成时间的开始和结束时间不是**成对出现**，则该时间条件无效。

---

## 3. 请求地址

```http
https://open.youzanyun.com/api/youzan.trades.sold.get/4.0.4
```

---

## 4. 请求参数 (全量)

| 参数名称 | 参数类型 | 必填 | 示例值 | 参数说明 |
| :--- | :--- | :---: | :--- | :--- |
| `access_token` | String | **是** | `9b510e232c9...`| 鉴权凭证，用于请求 API |
| `type` | String | 否 | `NORMAL` | 订单类型。`NORMAL`: 普通订单; `PEERPAY`: 代付; `GIFT`: 我要送人; `GROUP`: 拼团; `HOTEL`: 酒店; `TAKE_AWAY`: 外卖; `CATERING_OFFLINE`: 堂食点餐; `CATERING_QRCODE`: 外卖买单; `KNOWLEDGE_PAY`: 知识付费 等 |
| `status` | String | 否 | `WAIT_SELLER...` | 订单状态（一次只能查一种状态）。<br>`WAIT_BUYER_PAY`: 待付款<br>`WAIT_SELLER_SEND_GOODS`: 待发货<br>`WAIT_BUYER_CONFIRM_GOODS`: 待确认收货<br>`TRADE_SUCCESS`: 订单完成<br>`TRADE_CLOSED`: 订单关闭<br>`TRADE_REFUND`: 退款中 |
| `start_created` | Date | 否 | `2023-10-01 00:00:00`| 创建开始时间 |
| `end_created` | Date | 否 | `2023-10-01 23:59:59`| 创建结束时间 |
| `start_update` | Date | 否 | `2023-10-01 00:00:00`| 更新开始时间 |
| `end_update` | Date | 否 | `2023-10-01 23:59:59`| 更新结束时间 |
| `start_success` | Date | 否 | `2023-10-01 00:00:00`| 交易完成开始时间 |
| `end_success` | Date | 否 | `2023-10-01 23:59:59`| 交易完成结束时间 |
| `delivery_start_time` | Date | 否 | `2023-10-01 00:00:00`| 发货/配送/自提 期望开始时间 |
| `delivery_end_time` | Date | 否 | `2023-10-01 23:59:59`| 发货/配送/自提 期望结束时间 |
| `page_no` | Integer| 否 | `1` | 页码，从 1 开始。**页码最大不能超过 100**，如需查询更多数据，必须按时间分段查询。 |
| `page_size` | Integer| 否 | `20` | 每页条数，默认 20 条，**最大不能超过 100**。 |
| `tid` | String | 否 | `E202310011...`| 有赞订单号（精确搜索查询） |
| `yz_open_id` | String | 否 | `V1abcdef123...` | 买家在有赞的唯一标识 ID |
| `receiver_name` | String | 否 | `张三` | 收件人姓名 |
| `receiver_phone` | String | 否 | `13800138000` | 收件人手机号 |
| `offline_id` | Long | 否 | `123456` | 门店/网点 ID，传入后只查归属该网点的订单 |
| `node_kdt_id` | Long | 否 | `88888` | 连锁门店网点店铺 ID（用于多网点/连锁总店拉取特定店单据场景） |
| `goods_id` | Long | 否 | `987654321` | 商品 ID（筛选包含该商品的订单） |
| `goods_title` | String | 否 | `薯片` | 商品标题（模糊搜索包含该标题的订单） |
| `keywords` | String | 否 | `苹果` | 搜索关键字（模糊匹配商品名、订单号等） |
| `express_type` | String | 否 | `EXPRESS` | 物流类型。`EXPRESS`: 快递配送; `LOCAL_DELIVERY`: 同城送; `SELF_FETCH`: 自提 |
| `fans_id` | Long | 否 | `0` | 买家有赞粉丝 ID |
| `fans_type` | Integer| 否 | `1` | 买家粉丝类型 |
| `exclude_order_tag`| String | 否 | `xxx` | 排除包含特定标签的订单 |
| `need_order_url` | Boolean| 否 | `false` | 是否需要返回前端该订单详情的 H5 链接 |
| `star` | Integer| 否 | `1` | 卖家星标备注过滤（1-5 对应标记的星级颜色） |

---

## 5. 响应参数 (全量展开)

返回主体内以 `data` 包裹，核心业务数据在 `full_order_info_list` 中以数组形式返回。

| 根级参数名称 | 参数类型 | 描述说明 |
| :--- | :--- | :--- |
| `total_results` | Integer | 搜索条件匹配到的订单总数 |
| `has_next` | Boolean | 是否还有下一页（用于辅助判定分页） |
| `full_order_info_list`| Array | 完整的订单信息列表集合 |

### 5.1 `full_order_info_list` 内部对象全量解构

列表内的每一项包裹了一个 `full_order_info` 对象，内部包含了关于这笔交易各个维度的子结构体：

| 子结构体名称 | 内部包含的核心全量字段与说明 |
| :--- | :--- |
| **`order_info`**<br>*(交易基础信息)* | `tid`(有赞订单号)；<br>`status`(主订单状态枚举，如 `WAIT_SELLER_SEND_GOODS`)；<br>`status_str`(状态中文描述文字)；<br>`type`(主订单类型：`0`普通 `10`拼团 等)；<br>`backstage_order_type`(后台订单类型标识，如 `NORMAL`、`CROSS_BORDER`)；<br>`pay_type`(支付方式枚举值) |
| **`buyer_info`**<br>*(买家信息)* | `yz_open_id`(买家有赞唯一身份标识，**对账核心**)；<br>`buyer_phone`(买家手机号，可能存在脱敏加密)；<br>`fans_id`(粉丝ID)；`fans_type`(粉丝类型)；<br>`fans_nickname`(粉丝昵称)；<br>`outer_user_id`(外部用户ID)<br>*(⚠️ 注：此接口文档明确不返回原版 `buyer_id`)* |
| **`pay_info`**<br>*(支付与金额信息)* | `total_fee`(订单总金额)；`post_fee`(运费)；<br>`payment`(实付总金额)；`real_payment`(实际支付现金)；<br>`deduction_pay`(虚拟抵扣金额，如积分/余额抵扣)；<br>`deduction_real_pay`(实际抵扣金额)；<br>*(注：金额类型字段为 String 格式，单位：**元**)* |
| **`address_info`**<br>*(收件与物流信息)* | `receiver_name`(收件人姓名)；`receiver_tel`(收件人电话)；<br>`delivery_province`(省份)；`delivery_city`(城市)；<br>`delivery_district`(区县)；`delivery_address`(详细地址)；<br>`delivery_postal_code`(邮编)；<br>`address_extra`(JSON 格式的经纬度扩展，如 `{"lon":120.1,"lat":30.4}`)；<br>`self_fetch_info`(自提点门店详情)；<br>`delivery_start_time`/`delivery_end_time`(期望配送或提货时间) |
| **`remark_info`**<br>*(备注与评价信息)* | `buyer_message`(买家留言)；<br>`trade_memo`(卖家内部备注)；<br>`star`(订单星标等级 0~5) |
| **`orders`** (Array)<br>*(商品明细列表)* | **包裹在该订单内的所有独立商品 SKU 数组：**<br>`item_id`(商品ID)；`sku_id`(规格ID)；<br>`outer_item_id`(外部商品/SPU商家编码)；<br>`outer_sku_id`(外部规格/SKU商家编码)；<br>`title`(商品名称)；`price`(单价，单位元)；<br>`num`(购买数量)；`discount_fee`(优惠分摊金额)；<br>`payment`(该商品最终实付金额)；`is_cross_border`(是否海淘商品) |
| **`child_info`**<br>*(子单信息)* | 包含 `child_orders` 数组。当出现订单因拆包或部分发货时会产生关联的子订单号（通常取自其内部的 `tid` 用于局部发货接口）。 |
| **`invoice_info`**<br>*(发票信息)* | `taxpayer_id`(买家填写的发票税号/抬头等) |

---

## 6. ⚠️ 开发者防坑指南与注意事项

1. **接口同步延时（非常重要）**：
   批量接口底层数据有一定的同步延时。**强烈建议：在收到订单相关的交易消息推送（Webhook）后，间隔大于 30 秒再调用此接口查询**。如果是主动定时轮询拉取订单，同样建议将查询时间范围整体向后延迟 30 秒（例如当前是 10:00:00，只查 09:59:30 之前的数据）。如果刚付款立刻查可能返回为空，遇到返回空可以实施重试机制。
2. **分页与深度翻页限制**：
   `page_no` 和 `page_size` 乘积代表查询深度，单页最大 100 条且**页码不能超过 100 页**。在系统对接进行大批量拉取时，必须采用**时间切片法**（如每 1 小时或每 30 分钟为一个区间，循环请求），不能单靠增加页码来拉取海量历史数据。
3. **退款订单的特殊性**：
   按 `start_success` (完成时间) 搜索，查到的是状态为“交易成功”的订单。如订单发生全额退款，其状态会变为 `TRADE_CLOSED`（交易关闭）。若需处理售后退单业务，须配合有赞退款 API（如 `youzan.trade.refund.search`）或交易消息服务使用。
4. **老订单降级说明**：
   由于该版本数据架构调整，若需查询 **2020 年以前的极早期订单数据**，请降级调用 `youzan.trades.sold.get.4.0.0` 接口，新版接口无法查出早于 2020 年的历史数据。