Linkfox Seerfar Ozon Category Search

Seerfar Ozon Category Search

This skill lists the products of a specific Ozon category from the Seerfar analytics database. Given a categoryId, it returns category-level aggregates (total sales, total revenue, average price, average rating, seasonality) plus each product's sales, price, rating, review count, brand and seller — the starting point for category selection analysis, best-seller mining within a category, and category capacity / price-band analysis.

Core Concepts

Unit of data is the product, scoped to one category: pass a single categoryId and receive that category's product list with performance metrics, alongside category-level aggregates. This is a category-level view, not a shop or keyword view.

Where the categoryId comes from: categoryId is the Ozon category identifier — a hierarchical path joined by _ (e.g. 15621032_15621049_115951147), obtained from the Ozon category document or from other Seerfar Ozon tools. If the user only has a category name, first resolve it to a categoryId from an upstream Seerfar Ozon source before calling this skill.

Category aggregates vs product rows: the response carries both category-level totals (totalSales, totalRevenue, avgPrice, rating, seasonalityAmplitude, seasonalityCoef, startDate/endDate) and a paginated product list (data / products). Use the aggregates for category sizing and the rows for individual product analysis.

Sales & price currency: sales / monthlySalesUnits are units; price / revenue are in Russian rubles (₽), indicated by currency.

Time window: by default the data covers the last 30 days (startDate / endDate show the actual range). Pass date as yyyy-MM (e.g. 2026-02) to query a historical month snapshot.

Parameters

Only categoryId and page are required.

调用方式

• API 端点：POST /seerfar/ozon/categorySearch（完整参数/响应/错误码见 references/api.md）
• Python 脚本：python scripts/seerfar_ozon_category_search.py '<JSON 参数>' [--inline]
• 成本约束：本工具会消耗算力；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。

输出策略（脚本默认行为）：

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-seerfar-ozon-category-search-<timestamp>.json（<cwd> 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；<session> 取自环境变量 SESSION_ID，按用户任务自动聚合；禁止写入 /tmp，当前目录不可写则报错）
• 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout
• 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 total/costToken、最大列表字段的长度 + 前 3 条样本）
• 加 --inline 强制全量打印到 stdout（同样落盘）

读数据建议：先看摘要判断是否足够；需要具体字段时优先用 jq或ConvertFrom-Json 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。

解决认证和算力问题

发生以下异常情况时，采用 references/onboarding.md 引导解决问题：

异常情况

• 未配置API Key：环境变量未配置 LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY。
• 响应401或402状态码
• 响应提示算力或余额不足：消息含"算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。

Usage Examples

1. Category best-sellers (sort by 30-day sales)

{"categoryId": "15621032_15621049_115951147", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

2. Category top-revenue products

{"categoryId": "15621032_15621049_115951147", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "revenue", "direction": "DESC"}]}}

3. Category premium price band (highest-priced)

{"categoryId": "15621032_15621049_115951147", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "price", "direction": "DESC"}]}}

4. Historical month snapshot

{"categoryId": "15621032_15621049_115951147", "date": "2026-02", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

5. Filter to FBO-fulfilled products only

{"categoryId": "15621032_15621049_115951147", "fulfillment": "FBO", "page": {"page": 1, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

6. Page deeper into the category

{"categoryId": "15621032_15621049_115951147", "page": {"page": 2, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

How to Build Queries

1. Always pass page.orders: categories can contain many products — sort by the metric you care about (sales DESC for best-sellers, revenue DESC for top revenue, price DESC for the premium band, reviewRating DESC for best-reviewed).
2. Keep pageSize ≤ 20: the gateway caps page size at 20. Use page.page to paginate; check hasNextPage to know whether more pages exist.
3. Resolve the categoryId first: if the user gives a category name rather than an id, obtain the categoryId from an upstream Seerfar Ozon source before calling this skill.
4. Use category aggregates for sizing: totalSales, totalRevenue, avgPrice and rating describe the whole category at a glance — use them for capacity and price-band assessment before drilling into rows.
5. Use date for historical comparison: pass date as yyyy-MM to compare a past month against the current 30-day window.
6. fulfillment is a single string: pass one of FBO / FBS / RFBS / FBP / OZON, not an array.