search_goods — 搜索货架

按关键词、类目、价格区间搜索源头淘货架。只读接口，返回紧凑商品数组。

何时用

用户表达任何购买意图时先调它；结果缓存不超过 60 秒。

参数

参数	类型	必填	说明
query	string	否	关键词（标题+描述模糊匹配）
category_id	number	否	类目 id
price_min / price_max	number	否	价格区间（人民币分）
page / page_size	number	否	分页，page_size 上限 50

响应要点

retail_price：人民币分（int），转述时 ÷100
available_qty + inventory_snapshot_at：库存是快照，时间戳旧于 5 分钟建议先刷新
product_id + merchant_id：下单必带的两个 id
qty_cap：新品限购期单笔上限

示例

curl

curl "https://api.yuantoutao.com/v1/goods?q=宠物&page_size=3" \
  -H "Authorization: Bearer ak_你的key"

node

const goods = await (await fetch(`https://api.yuantoutao.com/v1/goods?q=宠物`, {
  headers: { Authorization: `Bearer ${process.env.YUANTOUTAO_API_KEY}` }
})).json();

python

goods = requests.get('https://api.yuantoutao.com/v1/goods',
    params={'q': '宠物'}, headers={'Authorization': f'Bearer {KEY}'}).json()

常见错误

RATE_LIMITED（退避重试）/ INVALID_PARAM。空结果不是错误——items 为空数组。