Skip to content

nexscope-ai/nexscope-ecommerce-skills / ecommerce-ozon-seller-products

ecommerce-ozon-seller-products

Verified

FileKindSize
SKILL.mdskill md9.0 KB
manifest.jsonconfig287 B
references/api.mdmarkdown8.5 KB
scripts/ozon_seller_products.pyscript6.6 KB

references/api.md

View on GitHub
# Nexscope Ozon Seller Products API Reference

## API Specification

- **Endpoint**: `${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/mpstats/ozon/sellerProducts`
- **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)

## Request Parameters

POST Body (JSON). The following fields are consistent with the currently registered "Nexscope-Ozon-Seller Products" input schema in the tool gateway (sync date 2026-04-30).

| Parameter | Type | Required | Description |
|------|------|------|------|
| sellerId | string | Yes | Ozon seller ID (numeric string), matching the seller identifier in product lists/seller rankings |
| startDate | string | No | Statistics start date `YYYY-MM-DD`; latest is yesterday |
| endDate | string | No | Statistics end date `YYYY-MM-DD`; latest is yesterday |
| page | integer | No | Page number, starting from 1 |
| pageSize | integer | No | Rows per page 1-100, default 100 |
| sortField | string | No | Sort column name (snake_case), e.g., `sales`, `revenue`, `final_price`, `balance`, `rating` |
| sortDirection | string | No | `asc` / `desc` |
| currency | string | No | Currency code, default `RUB`, e.g., `USD` |
| currencyRate | integer | No | Custom exchange rate (for non-default currency) |
| includeFbs | boolean | No | Whether to include FBS data |
| filters | array | No | List of numeric filter conditions, each `{field, op, value, value2?}`, multiple conditions AND |

### filters Sub-fields

  | Sub-field | Type | Required | Description |  
|--------|------|------|------|
| field | string | Yes | Column name (snake_case). Common: `sales`, `final_price`, `rating`, `comments`, `balance`, `revenue`, `days_in_stock`, `turnover_days`, `lost_profit`, `category_position`. |
| op | string | Yes | `GTE` / `LTE` / `GT` / `LT` / `EQ` / `NOT_EQ` / `BETWEEN` |
| value | number | Yes | Main value (lower bound when `BETWEEN`) |
| value2 | number | `BETWEEN` required | Upper bound (closed 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 |
|------|------|------|
| total | integer | Total number of matched products under the seller |
| products | array | Product list (see details below) |
| columns | array | Rendered column definitions |
| costTime | integer | API latency (milliseconds) |
| costToken | integer | Tokens consumed |
| type | string | Response type |

### products[*] Product Object Fields (39 fields)

Per official outputSchema definition (`_mpstats_ozon_sellerProducts`, sync date 2026-05-06). This schema is **fully shared** with `productSearch` / `brandProducts` / `categoryProducts`; the 4 endpoints differ only in query dimension, with an identical set of product card fields returned.

**Identity & Basic Information**

| Field | Type | Description |
|------|------|------|
| productId | integer | SKU ID |
| title | string | Product name (Russian) |
| brand | string | Brand |
| brandId | integer | Brand ID |
| sellerName | string | Seller name |
| sellerId | integer | Seller ID |
| category | string | Category path (Russian, `/` separated) |
| nicheName | string | Niche path (Russian) |
| nicheId | integer | Niche ID |
| country | string | Country of sale, always `RU` for Ozon |
| firstDate | string | Listing date (`yyyy-MM-dd`) |
| imageUrl | string | Main image URL |
| productPageUrl | string | Product page URL |
| sourceTool / sourceType | string | Source tool / data source identifier |

**Price & Currency**

| Field | Type | Description |
|------|------|------|
| price | number | Current selling price |
| oldPrice | number | Original price before discount |
| ozonCardPrice | number | Ozon Card price |
| minPrice / maxPrice / averagePrice | number | Minimum / maximum / average price during the statistics period |
| currency | string | Currency symbol (`₽` / `$` / `€`) |

**Ratings & Reviews**

| Field | Type | Description |
|------|------|------|
| rating | number | Rating, 0-5 |
| reviewCount | integer | Number of reviews |

**Inventory & FBS**

| Field | Type | Description |
|------|------|------|
| balance | integer | Current stock (units) |
| balanceFbs | integer | FBS stock (seller self-ship units) |
| frozenStocks | integer | Slow-moving stock |
| warehousesCount | integer | Number of FBO warehouses |
| isFbs | boolean | Whether shipped via FBS |

**Sales & Turnover**

| Field | Type | Description |
|------|------|------|
| salesPerDay | number | Average daily sales (units/day) |
| monthlySalesUnits | integer | Sales volume during the statistics period (units) |
| monthlySalesRevenue | number | Sales revenue during the statistics period |
| lostProfit | number | Lost revenue (due to stockouts, etc.) |
| daysInSite | integer | Days on sale (statistics period, including out-of-stock days) |
| daysInStock | integer | Days in stock |
| turnoverDays | number | Turnover days (lower is faster) |

**Ranking & Revenue Share**

| Field | Type | Description |
|------|------|------|
| position | integer | Ranking within the current query dimension (seller for this endpoint) |
| categoryPosition | integer | Ranking within the category |
| revenueSharePercent | number | Revenue share of this SKU within the current query dimension, 0-100 |

## 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 |
|---|---|
| Authentication failed | HTTP 401 or authorized error: Follow the **## Resolving Authentication and Credit Issues** section in SKILL.md. |
| Insufficient credits or balance | 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/mpstats/ozon/sellerProducts \
  -H "Authorization: Bearer ${NEXSCOPE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "sellerId": "3628678",
    "sortField": "revenue",
    "sortDirection": "desc",
    "pageSize": 100
  }'
```

---

## 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