---
name: ozon-seller-api
description: Ozon Seller API 操作手册 — 产品导入、审核、价格、分类、属性。含v3/import实测避坑（分类用desc_cat_id+type_id、属性用id不用attribute_id、字典属性需dict_id、价格必须CNY、审核检查图片匹配分类）。
version: 0.2
tags: [ozon, seller-api, api, listings, cross-border-ecommerce]
---

# Ozon Seller API 操作手册

## 认证

Ozon Seller API 使用两个 Header 认证：
- `Client-Id`: 店铺的 client_id（数字字符串）
- `Api-Key`: 店铺的 API Key（UUID 格式，36字符）
- `Content-Type: application/json`

无需 Bearer Token，不需要 JWT，直接 Header 传参即可。

## 店铺凭据（admincao 下）

| Store | client_id | 说明 |
|-------|-----------|------|
| Ozon-Hzqjone | 3098640 | 手机 15718853624 |
| Ozon-Hzqjtwo | 3103005 | 手机 13011158945 |

API Key 存储在 AtomK 后台 store 的 `extra_data.api_key` 字段，或本地 `/home/ubuntu/.hermes/credentials/accounts.md`。

## API 端点（已验证可用 vs 废弃）

### ✅ 可用端点

| 端点 | 用途 | 备注 |
|------|------|------|
| `POST /v3/product/list` | 获取产品ID列表 | ⚠️ last_id 必须是空字符串 `""` |
| `POST /v3/product/info/list` | 批量获取产品详情 | ⚠️ 响应结构陷阱见下方 |

### ❌ 废弃/404 端点

| 端点 | 状态 | 说明 |
|------|------|------|
| `POST /v2/product/list` | 404 | 已废弃 |
| `POST /v2/product/info` | 404 | 已废弃 |
| `POST /v2/product/info/list` | 404 | 已废弃 |
| `POST /v1/product/info` | 404 | 不存在 |
| `POST /v4/product/info` | 404 | 不存在 |
| `POST /v5/product/info` | 404 | 不存在 |
| `POST /v3/product/info` | 404 | 单个产品查询不存在 |

Base URL: `https://api-seller.ozon.ru`

## 核心陷阱与避坑

### 陷阱1：v3/product/list 的 last_id 参数

```python
# ❌ 错误 — 整数 0
{"last_id": 0}
# 报错：invalid value for string field last_id: 0

# ❌ 错误 — 字符串 "0"
{"last_id": "0"}
# 报错：invalid base64 data at input byte 0

# ✅ 正确 — 空字符串（首页）
{"last_id": ""}
```

`last_id` 是 base64 编码的分页游标，首页必须传空字符串 `""`。后续页使用上一次返回的 `last_id` 值。

### 陷阱2：v3/product/info/list 响应结构

```python
# ❌ 错误 — 以为在 result.items 下
products = result.get("result", {}).get("items", [])
# 返回空列表，因为 result 键不存在

# ✅ 正确 — items 在顶层
products = result.get("items", [])
```

与 `v3/product/list` 返回 `{"result": {"items": [...]}}` 不同，`v3/product/info/list` 返回的是 `{"items": [...]}`，没有 `result` 包裹层！

### 陷阱3：v3/product/list 返回结构

```json
{
  "result": {
    "items": [
      {
        "product_id": 2184055159,
        "offer_id": "XRZBQ_HK",
        "has_fbo_stocks": false,
        "has_fbs_stocks": true,
        "archived": false,
        "is_discounted": false,
        "quants": []
      }
    ],
    "total": 145,
    "last_id": "WzM5OTI4Mjk4MTAsMzk5MjgyOTgxMF0="
  }
}
```

注意：这个接口的响应是在 `result` 下的。

## 完整代码模板：获取全部 Active Listing

```python
import urllib.request, json, ssl

ctx = ssl.create_default_context()
ctx.check_hostname = False
ctx.verify_mode = ssl.CERT_NONE

CLIENT_ID = "3098640"
API_KEY = "your-api-key-here"

HEADERS = {
    "Content-Type": "application/json",
    "Client-Id": CLIENT_ID,
    "Api-Key": API_KEY
}

def ozon_request(endpoint, body_dict):
    url = f"https://api-seller.ozon.ru{endpoint}"
    data = json.dumps(body_dict).encode()
    req = urllib.request.Request(url, data=data, headers=HEADERS)
    resp = urllib.request.urlopen(req, timeout=20, context=ctx)
    return json.loads(resp.read())

# Step 1: 获取全部产品ID（分页）
all_product_ids = []
last_id = ""
while True:
    result = ozon_request("/v3/product/list", {
        "filter": {"visibility": "ALL"},
        "limit": 100,
        "last_id": last_id
    })
    items = result["result"]["items"]
    all_product_ids.extend([i["product_id"] for i in items])
    last_id = result["result"].get("last_id", "")
    if not last_id or len(items) < 100:
        break

# Step 2: 批量获取产品详情（每批50）
all_products = []
for offset in range(0, len(all_product_ids), 50):
    batch = all_product_ids[offset:offset+50]
    detail = ozon_request("/v3/product/info/list", {
        "product_id": batch
    })
    # ⚠️ 注意：items 在顶层，不在 result 下！
    all_products.extend(detail.get("items", []))

# Step 3: 筛选 Active
active = [p for p in all_products if not p.get("is_archived", False)]
```

## 产品详情关键字段

| 字段 | 说明 | 示例 |
|------|------|------|
| `id` | 产品ID，用于构建前台URL | 2184055159 |
| `name` | 产品名称（俄语） | "закладки" |
| `offer_id` | 卖家自定义SKU | "XRZBQ_HK" |
| `price` | 当前售价 | "7.28" |
| `old_price` | 划线价 | "15.61" |
| `currency_code` | 货币 | "CNY" |
| `is_archived` | 是否归档 | false |
| `sources[].sku` | Ozon SKU | 2449791222 |
| `sources[].source` | 发货方式 | "sds" |
| `sources[].shipment_type` | 配送类型 | "SHIPMENT_TYPE_GENERAL" |
| `stocks.has_stock` | 是否有库存 | true |
| `stocks.stocks[].source` | 库存来源 | "fbs" / "fbo" |
| `commissions` | 佣金信息 | 含 FBO/FBS/RFBS/FBP |

## Ozon 前台 URL

```
https://www.ozon.ru/product/{product_id}
```

注意：从中国直接访问 ozon.ru 会被地域封锁（307重定向），需要俄罗斯代理或VPN。

## filter.visibility 选项

| 值 | 说明 |
|----|------|
| `ALL` | 全部产品 |
| `VISIBLE` | 仅可见（有库存+有价格） |
| `IN_SALE` | 在售 |
| `NOT_SALE` | 未在售 |

## 依赖

无额外依赖，使用 Python 标准库 `urllib` + `json` + `ssl` 即可。不需要 requests 或其他第三方库。

## 产品导入 (Product Import) — 已实测

### ✅ 可用的导入相关端点

| 端点 | 用途 | 备注 |
|------|------|------|
| `POST /v3/product/import` | 创建产品 | ✅ 唯一可用的import端点 |
| `POST /v1/product/import/info` | 查询导入状态+审核结果 | 返回validation和moderation状态 |
| `POST /v1/product/import/prices` | 设置产品价格 | ⚠️ 必须指定 `currency_code: "CNY"` |
| `POST /v1/product/archive` | 归档产品 | 传 `{"product_id": [123]}` |
| `POST /v3/product/info/list` | 批量获取产品详情 | ✅ 含分类和属性信息 |

### ❌ 废弃/404 的导入相关端点

| 端点 | 状态 |
|------|------|
| `POST /v1/product/import` | 404 |
| `POST /v2/product/import` | 404 |
| `POST /v2/products/stocks` | 404（stock无法通过API设置） |
| `POST /v1/product/update/stocks` | 404 |
| 所有 `/v*/category/tree` | 404 |
| 所有 `/v*/category/search` | 404 |
| 所有 `/v*/category/attribute` | 404 |
| 所有 `/v*/product/classify` | 404 |
| 所有 `/v*/category/suggest` | 404 |

### 陷阱4：分类必须用 description_category_id + type_id

```python
# ❌ 错误 — 使用 category_id
{"category_id": 12345}

# ✅ 正确 — 使用 description_category_id + type_id
{"description_category_id": 17028733, "type_id": 95421}
```

`category_id` 字段会报 "TypeId must be greater than 0"。必须用 `description_category_id` + `type_id` 组合。

**获取分类的方法**：从现有已审核通过的产品中提取（`/v3/product/info/list` 返回 `description_category_id` 和 `type_id`）。

### 陷阱5：属性格式必须用 id（不是 attribute_id）

```python
# ❌ 错误 — 使用 attribute_id
{"complex_id": 0, "attribute_id": 9048, "values": [{"value": "text"}]}

# ✅ 正确 — 使用 id
{"complex_id": 0, "id": 9048, "values": [{"value": "text"}]}
```

### 陷阱6：字典属性需要 dict_id

某些属性（如 attr 9163 "Пол"/性别）是字典类型，需要传 `dict_id` 和 `value`：

```python
# ❌ 错误 — 只传 value 字符串
{"id": 9163, "values": [{"value": "унисекс"}]}

# ✅ 正确 — 传 dict_id + value
{"id": 9163, "values": [{"dict_id": 1, "value": "унисекс"}]}
```

但问题是：**无法通过API查询字典值列表**（所有attribute端点都404）。只能从已有产品的属性中反推，或试错。

### 陷阱7：价格API必须指定货币

```python
# ❌ 错误 — 不指定货币或用 RUB
{"prices": [{"offer_id": "SKU1", "price": "5.99"}]}
# 报错："Неверно указана валюта"（货币指定错误）

# ✅ 正确 — 指定 CNY
{"prices": [{"offer_id": "SKU1", "price": "5.99", "old_price": "9.99", "currency_code": "CNY"}]}
```

### 陷阱8：审核(Moderation)会检查图片与分类匹配

**最重要的坑！** 即使 validation: success，Ozon 的人工审核仍可能 declined 产品。

常见拒因：
- "Фото товара не соответствует его типу" — 产品图片与分类类型不匹配
- "Необходимо изменить тип" — 需要更改类型

**这意味着**：选错分类的产品100%会被审核拒绝，即使所有属性都填对了。必须找到与产品图片内容匹配的分类。

### 陷阱9：Stock 无法通过 API 设置

`/v2/products/stocks` 和所有 stock 相关端点均返回 404。库存可能需要在 Ozon Seller 后台手动设置，或通过 FBS/FBO 仓库管理。

### 完整产品导入代码模板

```python
import requests
from urllib3.exceptions import InsecureRequestWarning
requests.packages.urllib3.disable_warnings(InsecureRequestWarning)

OZON_H = {
    "Client-Id": "3103005",
    "Api-Key": "your-api-key",
    "Content-Type": "application/json"
}

# Step 1: Import product
import_payload = {
    "items": [{
        "name": "Солнцезащитные рукава для спорта",
        "offer_id": "SUNSLV668",
        "description": "Описание товара",
        "description_category_id": 17028733,  # ⚠️ 不是 category_id
        "type_id": 95421,
        "images": ["https://example.com/image.jpg"],
        "attributes": [
            {"complex_id": 0, "id": 9048, "values": [{"value": "текст"}]},  # ⚠️ 用 id 不是 attribute_id
        ],
        "vat": "0"
    }]
}

r = requests.post("https://api-seller.ozon.ru/v3/product/import",
                   headers=OZON_H, json=import_payload, timeout=15, verify=False)
result = r.json()
# result.result[0].product_id — 新产品ID
# result.result[0].errors — 导入错误列表

# Step 2: Check import status (repeat until status != "pending")
import time
task_id = result["result"][0]["task_id"]
for _ in range(20):
    r = requests.post("https://api-seller.ozon.ru/v1/product/import/info",
                      headers=OZON_H, json={"task_id": task_id}, timeout=15, verify=False)
    status = r.json()["result"]["items"][0]["status"]
    if status != "pending":
        break
    time.sleep(3)

# Step 3: Set price
r = requests.post("https://api-seller.ozon.ru/v1/product/import/prices",
    headers=OZON_H,
    json={"prices": [{
        "offer_id": "SUNSLV668",
        "price": "5.99",
        "old_price": "9.99",
        "currency_code": "CNY"  # ⚠️ 必须指定！
    }]},
    timeout=15, verify=False)

# Step 4: Check moderation result
product_id = result["result"][0]["product_id"]
r = requests.post("https://api-seller.ozon.ru/v3/product/info/list",
    headers=OZON_H,
    json={"product_id": [product_id]},
    timeout=15, verify=False)
product = r.json()["items"][0]
# product.status — "Не продается" = not for sale (declined)
# moderation — "declined" = 审核被拒
```

### 已知分类统计（从现有产品提取）

| description_category_id | type_id | 名称 | approved数 | 备注 |
|-------------------------|---------|------|-----------|------|
| 17028733 | 95421 | Декор/装饰品 | 35 | 通过率高但分类要匹配 |
| 17027904 | 93338 | 运动配件A | 19 | 需性别属性(dict_id) |
| 17027904 | 970575517 | 运动配件B | 12 | 需性别属性(dict_id) |
| 17027929 | 592744673 | Ледоступы/冰爪 | - | ❌ 防晒袖被declined |
| 17027904 | 93866 | Солнцезащитные очки/太阳眼镜 | - | 运动防护类，可能适合防晒用品 |
| 41777465 | 93258 | Солнцезащитная шляпа/太阳帽 | - | ❌ 4个必填字典属性，无法通过API填写 |

### 找正确分类的方法

1. **从Ozon前台搜索**：用Jina Reader抓取 `ozon.ru/search/?text=关键词`，找竞品的分类
2. **从现有产品统计**：用 `/v3/product/info/list` 获取所有产品，按 `description_category_id` 分组统计approved率
3. **AtomK前端编辑器**：通过 `atomlisting.com/editor/:id` 选择Ozon平台，AI可能推荐正确分类
4. **多分类并行测试**：用同一产品数据同时提交到3-4个候选分类，看哪个validation先通过且无缺失属性

### 审核(Moderation)被拒的实战经验

**即使 validation: success，审核仍可能 declined！** Validation 只检查格式，审核检查内容。

实测被拒记录：
- 分类 17028733/95421（装饰品）→ "Необходимо изменить тип"（改类型）
- 分类 17027929/592744673（冰爪）→ "Фото товара не соответствует его типу"（照片与类型不匹配）
- 分类 41777465/93258（太阳帽）→ 4个必填字典属性无法填写，validation都无法通过

**结论：分类名称必须与产品图片内容语义匹配。** Ozon审核员是真人，会看图片判断分类是否正确。"防晒袖"放在"冰爪"分类下100%被拒。

### 字典属性(dict_id)暴力破解法

当无法通过API查询字典值时（所有 /v*/category/attribute 端点404），可以暴力枚举 dict_id：

```python
# 试错法找 dict_id — 从1开始递增
for dict_id in range(1, 200):
    test_attrs = [{"complex_id": 0, "id": 9163, "values": [{"dict_id": dict_id, "value": "унисекс"}]}]
    # 提交到 /v3/product/import，检查返回错误
    # 如果错误从 "attribute 9163 is missing" 变成别的，说明 dict_id 正确
```

实测结果（分类 17027904/970575517）：
- dict_id=1 → 通过import检查，但后续验证报错（不适用于此分类）
- dict_id=49 → 通过import检查，但验证仍报错
- **不同分类的字典值不同**，一个分类下有效的dict_id在另一个分类下可能无效

### offer_id 长度限制

```python
# ❌ 错误 — offer_id 超过50字符
{"offer_id": "SUNSLV668G929X_17027904_970575517"}
# 报错：offer_id_invalid

# ✅ 正确 — offer_id 保持在50字符以内
{"offer_id": "SUNSLV668"}
```

### 产品生命周期状态流转

```
import → pending → validation:success/error → moderate:in_process → moderate:approved/declined
                                                    ↓
                                              如果approved → 需要stock+price → 在售
                                              如果declined → 必须改分类重新import（无法修改已declined产品的分类）
```

**已declined的产品只能归档后重新导入到新分类。** 无法修改已提交产品的分类。每次重新导入会生成新的 product_id。

### 归档大量测试产品的快捷方法

```python
# 批量归档
requests.post("https://api-seller.ozon.ru/v1/product/archive",
    headers=OZON_H,
    json={"product_id": [4575426716, 4575556247, 4575793963, ...]},
    timeout=15)
```

### v3/product/import/info 返回结构

```json
{
  "result": {
    "items": [{
      "product_id": 4576116662,
      "status": "imported",     // pending / imported / failed
      "errors": [],
      "offer_id": "SUNSLV668"
    }],
    "task_id": 12345678
  }
}
```

注意：`task_id` 在 import 返回，用于查询状态。但也可以用 `product_id` 通过 `/v3/product/info/list` 查询最终状态。

## 依赖

无额外依赖，使用 Python `requests` 即可（标准库 `urllib` 也可）。