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