Skip to content

nexscope-ai/nexscope-ecommerce-skills / ecommerce-ozon-category-search

ecommerce-ozon-category-search

Verified

FileKindSize
SKILL.mdskill md13.3 KB
manifest.jsonconfig275 B
references/api.mdmarkdown12.6 KB
scripts/ozon_category_search.pyscript6.6 KB

references/api.md

View on GitHub
# Nexscope Ozon Category Product Search API Reference

## API Specification

- **Endpoint**: `${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/seerfar/ozon/categorySearch`
- **HTTP Method**: POST, Content-Type: application/json
- **Authentication**: Header `Authorization: <api_key>`, api_key is read from the environment variable `NEXSCOPE_API_KEY` (if not configured, follow the **## Resolving Authentication and Credit Issues** section in SKILL.md)
- **User-Agent**: `Nexscope-Skill/1.0`; HTTP timeout 60s

## Request Parameters

POST Body (JSON). The following fields are consistent with the interface `inputSchema`. `categoryId` and `page` are required, the rest are optional.

| Parameter | Type | Required | Description |
|------|------|------|------|
| categoryId | string | Yes | Ozon category ID, obtained from Ozon category documentation or other Nexscope Ozon tools. Format like `15621032_15621049_115951147` (multi-level categories joined by `_`) |
| page | object | Yes | Pagination & sorting: `{page, pageSize, orders[]}` |
| page.page | integer | No | Page number, starting from 1, default 1 |
| page.pageSize | integer | No | Items per page, default 20, **maximum 20** (invalid values produce a platform error) |
| page.orders | array | No | Sort rules, elements `{field, direction}` (both required); `direction` takes `DESC` (descending) / `ASC` (ascending). Common sort fields: `sales`, `price`, `revenue`, `reviewRating` |
| date | string | No | Query historical month, format `yyyy-MM` (e.g., `2026-02`); defaults to last 30 days if omitted |
| fulfillment | string | No | Fulfillment method filter, fixed options: `FBO`, `FBS`, `RFBS`, `FBP`, `OZON`; queries all if omitted. **Note: single string, not an array** |
| uId | string | No | User ID (max 1000) |
| memberId | string | No | Member ID (a unique member identifier; a user can belong to multiple teams; data is attributed to memberId, max 1000) |

> **Required constraints**: `categoryId` and `page` are both required; missing required input produces a nonzero platform code.
> **Pagination limit**: `page.pageSize` has a maximum of 20; paginate via incrementing `page.page`.
> **Sorting**: Recommended to sort by core metrics via `page.orders` (e.g., `sales` DESC for hot products, `revenue` DESC for high revenue, `price` DESC for high price tier) to avoid paging through unsorted results.
> **Historical month**: Passing `yyyy-MM` in `date` queries the snapshot for that month; omitting returns the last 30 days of data, with `startDate`/`endDate` in the response indicating the actual statistics interval.

## Nexscope response envelope

These research endpoints return a platform object with numeric `code`, nullable `msg`, and business `data`. Only outer `code: 0` means success; `200`, string codes, missing codes, and HTTP 200 alone do not. A nonzero code is a platform error: show `msg` and do not interpret the payload as a successful result.

`msg` preserves the upstream message when available; Chinese messages are translated to English by Nexscope. A successful response without a message has `msg: null`. Do not infer success or retry behavior from the message text. On both success and failure, the direct fields `code`, `errcode`, `errorCode`, `msg`, `errmsg`, `message`, and `errorMsg` are removed from public `data`. Read the message only from outer `msg`; deeper business fields are preserved, including nested `code` and `status`.

Business field tables and abbreviated business examples below describe `data`, unless explicitly labeled as a complete platform response. For example, a business `products` field is at HTTP `data.products`, and a business `data` array is at HTTP `data.data`. The research endpoints already had this outer envelope; no additional wrapper is added.

```json
{"code":0,"msg":null,"data":{}}
```

Metadata includes string `ts` (epoch milliseconds), string `cost` (elapsed milliseconds, not credits), `time`, and nullable `traceId`. Handle network/HTTP failures before the platform code; gateway failures may not be platform JSON. Keep the existing billing-header guidance separate from elapsed time.

## Response Structure

| Field | Type | Description |
|------|------|------|
| id | string | Echoed category ID |
| total | integer | **Number of records returned on this page** (equals the current page `data` count, not total category product count) |
| totalSales | integer | Total category sales volume (within the statistics interval) |
| totalRevenue | number | Total category sales revenue (RUB) |
| avgPrice | number | Average category product price (RUB) |
| rating | number | Average category product rating |
| seasonalityAmplitude | string | Seasonality intensity, e.g., `STRONG_SEASONALITY` |
| seasonalityCoef | string | Seasonality phase, e.g., `OFF_SEASON` |
| startDate | string | Statistics start date |
| endDate | string | Statistics end date |
| sellerType | object | **Fulfillment method distribution** (not seller domestic/cross-border type), keys are fulfillment methods and values are product counts for that method, e.g., `{"FBO":218,"RFBS":528,"FBP":5,"FBS":240,"OZON":1}` |
| categoryInfo | object | Category metadata, structure see "categoryInfo Structure" below |
| data | array | Category product list (see details below) |
| products | array | Category product list, content identical to `data` |
| hasNextPage | boolean | Whether there is a next page |
| columns | array | Column definitions, elements contain `{field, title, cellType, sortable, filterable}` |
| type | string | Response display type |
| costTime | integer | API latency (milliseconds) |
| costToken | integer | Tokens consumed |

### data[*] / products[*] Category Product Object Fields

| Field | Type | Description |
|------|------|------|
| sku | integer | Product SKU |
| productId | integer | Unified product ID, mapped from `sku` |
| title | string | Product title |
| price | number | Product price (RUB) |
| currency | string | Currency, always `₽` |
| sales | integer | Product sales volume |
| monthlySalesUnits | integer | Unified monthly sales, mapped from `sales` |
| revenue | number | Product sales revenue |
| monthlySalesRevenue | number | Unified monthly revenue, mapped from `revenue` |
| reviewRating | number | Product rating |
| rating | number | Unified rating, mapped from `reviewRating` |
| reviewCount | integer | Number of reviews |
| brandName | string | Brand name |
| brand | string | Unified brand, mapped from `brandName` |
| sellerName | string | Seller name |
| fulfillment | array | Product fulfillment methods, e.g., `["FBO"]`, may contain multiple values |
| imageUrl | string | Product image URL |
| productUrl | string | Product URL |
| productPageUrl | string | Unified product page URL, mapped from `productUrl` |
| categoryInfo | object | Product category attribution information, structure see "categoryInfo Structure" below |
| sourceType | string | Data source, always `ozon` |
| sourceTool | string | Source tool, e.g., `Seerfar-Ozon-查类目` |

> **Unified fields vs original fields**: `productId`/`rating`/`brand`/`monthlySalesUnits`/`monthlySalesRevenue`/`productPageUrl` are backend unified mapping fields, equivalent to the original `sku`/`reviewRating`/`brandName`/`sales`/`revenue`/`productUrl`; choose either one for display, original fields are recommended (semantically more intuitive).

### categoryInfo Structure (returned at top level and for each product)

| Field | Type | Description |
|------|------|------|
| cnTitlePath | string | Chinese category path, e.g., `鞋类 > 运动鞋和工作鞋 > 举重鞋` |
| enTitlePath | string | English category path, e.g., `Footwear > Sports and Work Footwear > Weightlifting Shoes` |
| titlePath | string | Russian (front-end) category path, e.g., `Обувь > Спортивная и рабочая обувь > Штангетки` |
| fullCategoryId | array | Array of category IDs at each level, e.g., `["15621032","15621032_15621049","15621032_15621049_115951147"]` |
| category | object | Terminal category object, containing `cnTitle`/`enTitle`/`title`(Russian)/`level`/`crossBorderSellable`(whether cross-border sales are allowed)/`pid`/`disabled`/`id` |

> `categoryInfo` is returned identically at both the top level and in each `data[*]`, and can be used to verify category names (CN/EN/RU) and cross-border salability (`category.crossBorderSellable`).

## Error Codes

HTTP 200 does not prove business success. Read only the numeric outer platform `code`: `0` succeeds and any other value fails. Show outer `msg`; never test removed provider codes or nested business `code` as the platform status. Authentication, permissions, balance, and validation failures may be platform errors even with HTTP 200; also handle non-2xx HTTP and non-JSON responses.

### Recovery guidance

| Condition | Action |
|---|---|
| Parameter error | Check `msg`; common causes include missing `categoryId`, missing `page` |
| Pagination parameter exceeded limit | `page.pageSize` maximum is 20, reduce and retry |
| Too many requests | Rate limited, retry later |
| Authentication failed | HTTP 401 or authorized error: Follow the **## Resolving Authentication and Credit Issues** section in SKILL.md. |
| Billing failed | HTTP 402: Follow the **## Resolving Authentication and Credit Issues** section in SKILL.md. |

## curl Example

```bash
curl -X POST ${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/seerfar/ozon/categorySearch \
  -H "Authorization: Bearer ${NEXSCOPE_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Nexscope-Skill/1.0" \
  -d '{
    "categoryId": "15621032_15621049_115951147",
    "page": {"page": 1, "pageSize": 5, "orders": [{"field": "sales", "direction": "DESC"}]}
  }'
```

## Response Example (abbreviated)

```json
{
  "id": "15621032_15621049_115951147",
  "total": 5,
  "totalSales": 2066,
  "totalRevenue": 12973043,
  "avgPrice": 7228.0,
  "rating": 4.9,
  "seasonalityAmplitude": "STRONG_SEASONALITY",
  "seasonalityCoef": "OFF_SEASON",
  "startDate": "2026-06-01",
  "endDate": "2026-07-01",
  "hasNextPage": true,
  "type": "productWorkbenches",
  "costTime": 1415,
  "costToken": 16000,
  "sellerType": {"FBO": 218, "RFBS": 528, "FBP": 5, "FBS": 240, "OZON": 1},
  "categoryInfo": {
    "cnTitlePath": "鞋类 > 运动鞋和工作鞋 > 举重鞋",
    "enTitlePath": "Footwear > Sports and Work Footwear > Weightlifting Shoes",
    "titlePath": "Обувь > Спортивная и рабочая обувь > Штангетки",
    "fullCategoryId": ["15621032", "15621032_15621049", "15621032_15621049_115951147"],
    "category": {
      "cnTitle": "举重鞋", "enTitle": "Weightlifting Shoes", "title": "Штангетки",
      "level": 3, "crossBorderSellable": true, "pid": "15621032_15621049",
      "disabled": false, "id": "15621032_15621049_115951147"
    }
  },
  "data": [
    {
      "sku": 1546459445,
      "productId": 1546459445,
      "title": "Штангетки YOUNGS",
      "price": 6481.0,
      "currency": "₽",
      "sales": 21,
      "monthlySalesUnits": 21,
      "revenue": 122635.0,
      "monthlySalesRevenue": 122635.0,
      "reviewRating": 4.8,
      "rating": 4.8,
      "reviewCount": 524,
      "brandName": "YOUNGS",
      "brand": "YOUNGS",
      "sellerName": "YoungS shoes",
      "fulfillment": ["FBO"],
      "imageUrl": "https://ir.ozone.ru/s3/multimedia-1-j/wc300/7000839379.jpg",
      "productUrl": "https://www.ozon.ru/product/1546459445",
      "productPageUrl": "https://www.ozon.ru/product/1546459445",
      "categoryInfo": { "...": "same as top-level categoryInfo" },
      "sourceType": "ozon",
      "sourceTool": "Seerfar-Ozon-查类目"
    }
  ],
  "products": [ "..." ],
  "columns": [ { "field": "sku", "title": "商品SKU", "cellType": "number", "sortable": true, "filterable": true } ]
}
```

> `products` content is identical to `data`, represented as `"..."` in the example to indicate omission. `total` is the number of records returned on this page (5 in this example), not total category product count; `hasNextPage=true` indicates more pages exist. `sellerType` is fulfillment method distribution (not seller domestic/cross-border type).

---

## API Key request rate and retries

All API Keys of one Nexscope user share the public API execution request-rate allowance, measured in any rolling 1-second window. The allowed RPS depends on that user's entitlements; it is not a universal 1 RPS. One Skill operation may issue multiple public API requests, each of which uses the allowance.

HTTP 429 with Nexscope outer code `13012` means request-rate exhaustion: honor the response's `Retry-After`. Outer code `13013` means concurrent-request exhaustion, not rate exhaustion; honor `Retry-After` when supplied. Check the HTTP status and outer JSON code separately. Do not automatically replay writes or requests with uncertain outcomes; first reconcile the operation's state.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall