Ecommerce Ozon Shop Search

Seerfar Ozon Shop Search

This skill lists the products of a specific Ozon shop (seller) from the Seerfar analytics database. Given a shop id, it returns each product's 30-day sales, price, rating, weight, fulfillment model (FBO/FBS), seller type (local / cross-border) and return/cancellation rate, plus the shop's total 30-day sales — the starting point for competitor-shop product analysis, best-seller mining, and seller catalog teardown.

Core Concepts

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

Where the shop id comes from: id is the Seerfar seller/shop identifier — the same sellerId returned by other Seerfar Ozon tools (e.g. product report / product detail search). Negative ids (e.g. -2 Ozon Express, -4 Ozon Fresh) are Ozon's own platform sellers; positive ids are third-party sellers. If the user only has a shop name or product, first obtain the sellerId from a product-level Seerfar Ozon source, then call this skill.

Seller type: each product carries sellerType — 0 local (local), 1 cross-border (cross-border). A shop is typically all one type; use it to judge whether a competitor is a domestic or cross-border seller.

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

Parameters

Only id and page are required.

Calling the Tool

• API Endpoint: /seerfar/ozon/shopSearch (full parameters/responses/error codes in references/api.md)
• Python Script: python scripts/ozon_shop_search.py '<JSON params>' [--inline]
• Cost constraint: This tool consumes credits. Within the same session and same parameter combination, it defaults to a single call with a 24-hour local cache. Do not automatically retry with different keywords, pagination, or parameters on failure/empty results. Inform the user of additional credit consumption before continuing retrieval.

Output strategy (script default behavior):

• Always write the full response to <cwd>/nexscope/<YYYY-MM-DD>/<session>/data/ecommerce-ozon-shop-search-<timestamp>.json (<cwd> is the working directory when the script executes, which in Claude Code is the current project directory; <session> is taken from the SESSION_ID environment variable, automatically grouped by user task; do not write to /tmp; error if the current directory is not writable)
• Response body <= 8 KB: write to disk then print full JSON to stdout
• Response body > 8 KB: write to disk then print only a summary to stdout (top-level fields, common counts like total/costToken, length of the largest list field + first 3 samples)
• Add --inline to force full output to stdout (still writes to disk)

Reading data: Check the summary first to determine if it is sufficient. When specific fields are needed, use jq or ConvertFrom-Json to extract from the saved JSON file as needed, avoiding loading the entire JSON into context.

Authentication & Credits

If you encounter authentication or credit issues:

Error conditions

• API Key not configured: The NEXSCOPE_API_KEY environment variable is not set.
• HTTP 401 or 402 status code
• Insufficient credits/balance: Response message indicates credit balance exhausted, quota exceeded, subscription expired, or recharge required.

Resolution steps

1. Set the NEXSCOPE_API_KEY environment variable with a valid API key.
2. If credits are insufficient, visit https://www.nexscope.ai/pricing?co-from=skillNS to top up your balance.
3. For onboarding and setup guidance, refer to https://www.nexscope.ai/help/skills-external-access?co-from=skillNS

Usage Examples

1. A shop's best-sellers (sort by 30-day sales)

{"id": 1362816, "page": {"page": 1, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

2. A shop's newest listings (sort by upload time)

{"id": 1362816, "page": {"page": 1, "pageSize": 20, "orders": [{"field": "upTime", "direction": "DESC"}]}}

3. A shop's highest-priced products

{"id": 1362816, "page": {"page": 1, "pageSize": 20, "orders": [{"field": "price", "direction": "DESC"}]}}

4. Page deeper into a shop's catalog

{"id": 1362816, "page": {"page": 2, "pageSize": 20, "orders": [{"field": "sales", "direction": "DESC"}]}}

How to Build Queries

1. Always pass page.orders: the catalog can be large — sort by the metric you care about (sales DESC for best-sellers, upTime DESC for new arrivals, price DESC for premium SKUs).
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 shop id first: if the user gives a shop/product name rather than an id, obtain the sellerId from a product-level Seerfar Ozon source before calling this skill.
4. Use totalSales for shop-level context: the response's totalSales is the shop's total 30-day sales — a quick health indicator for the whole shop, independent of the current page.

Display Rules

1. Present data only: show the shop's product metrics in a clear table without subjective advice.
2. Lead with shop context, then product columns: state totalSales (shop 30-day total) first, then a table of sku, price, sales, reviewRating, weight, sellerType, fulfillment, returnCancellationRate.
3. Seller type label: render sellerType as local/cross-border (0/1) so the user reads it at a glance.
4. Fulfillment: fulfillment is an array (e.g. ["FBO"]); join multiple values with /.
5. Missing returnCancellationRate: for Ozon platform sellers (negative id) this field is often absent — show - rather than failing.
6. Pagination guidance: when hasNextPage is true, tell the user more pages are available via page.page; remind them pageSize is capped at 20.
7. Empty shop: a non-existent id returns success with total=0 and no data — tell the user the id may be wrong rather than reporting a system error.
8. Error handling: when code is not "200" (or errcode is not 200), explain the reason from msg / errmsg and suggest fixes (add page, lower pageSize, retry on rate-limit).

Important Limitations

• id and page are both required; omitting either returns errcode 400.
• pageSize max 20: exceeding it returns errcode 1002.
• total is the page row count, not the shop's full catalog size — use hasNextPage to decide whether to fetch more pages.
• No text/keyword filter: this endpoint filters by shop only; to find a shop by name, use another Seerfar Ozon source first.
• Field variance by seller type: returnCancellationRate is populated for third-party sellers but frequently absent for Ozon platform sellers (negative id). Schema-defined productPageUrl, monthlySalesRevenue, brand are not returned (upstream has no source, omitted rather than null).

User Expression & Scenario Quick Reference

Applicable — analyzing one Ozon shop/seller's catalog:

Not applicable — Needs beyond one shop's catalog:

• Discovering Ozon keywords by market metrics → use the Seerfar Ozon market keyword search skill.
• A single product's full detail → use a product-level Seerfar Ozon source (this skill returns catalog-level fields only).
• Browsing the category tree → use a category-level Seerfar Ozon source.
• Finding which shop sells a given product → use a product-level Seerfar Ozon source to get the sellerId first.

Boundary judgment: if the user already has a shop/seller ID (or a sellerId obtained from a product lookup) and wants to enumerate or rank that shop's products by sales/price/rating, start here. If they want market-level keyword discovery or a single product's deep detail, route to the corresponding Seerfar Ozon skill.