订单批量查询接口 (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。

⏱️ 核心查询与排序规则

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

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

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

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

3. 请求地址

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

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

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

9.4 KiB Raw Blame History Unescape Escape