atlas-seller-kit/docs/integrations/ozon-seller-api

Ozon Seller API 文档总览

本目录整理 Ozon Seller API 的核心接口资料，并补充 Atlas 当前适配状态。Ozon 接口说明与 Atlas 实现状态必须区分：真正的 Ozon 商品导入 job 尚未实现。 官方文档：https://docs.ozon.ru/api/seller/zh/

---

目录

文档	内容
01-authentication.md	鉴权方式、请求头、错误码
02-category-tree.md	类目树查询
03-category-attributes.md	类目属性与字典值
04-product-import.md	商品导入（创建/更新）
05-product-info.md	商品信息查询
06-product-list.md	商品列表
09-stocks.md	库存管理

跟卖、独立图片更新和价格批量更新尚未形成当前仓库文档，不能使用旧目录链接推断已经实现。

---

快速索引

核心流程

1. 发布新商品：

① 获取类目树 → 选择类目 → 得 description_category_id + type_id
② 获取该类目属性 → 映射属性值
③ 组装 ImportProductsV3 请求体
④ POST /v3/product/import → 得 task_id
⑤ 轮询 POST /v1/product/import/info → 得 product_id

2. 跟卖已有商品：

① POST /v1/product/import-by-sku（传 sku + 基本信息）
② 轮询状态

3. 更新商品：

• 更新商品信息：复用 /v3/product/import（传 product_id 或 offer_id）
• 更新图片：POST /v1/product/pictures/import
• 更新价格：POST /v1/product/import/prices
• 更新库存：POST /v2/products/stocks

---

API 基础信息

项	值
Base URL	https://api-seller.ozon.ru
鉴权方式	请求头 Client-Id + Api-Key
内容类型	application/json
超时建议	30s（常规）/ 90s（import/轮询）
限流	官方未明确公开限流规则，建议控制在 10 req/s

---

关键约束

1. 类目选择：只有末级类目（disabled=false）可建品
2. 必填字段：name/description/category/price/尺寸重量/offer_id/images 必填且不能为 0
3. 图片 URL：必须是 https 公网直链（http 会被拒绝）
4. 属性映射：is_required=true 的属性必须填写
5. 异步任务：/v3/product/import 返回 task_id，需轮询 /v1/product/import/info 获取最终状态
6. 库存必须设置：import 成功后商品在后台，需设置库存才能上架

---

错误码速查

HTTP	含义	处理
400	参数错误	检查请求体字段
403	权限不足	检查 Api-Key 权限级别
404	资源不存在	检查 product_id/category_id
409	冲突（如 offer_id 重复）	改 offer_id 或走更新
429	限流	指数退避重试
500	服务端错误	重试或联系支持

---

Atlas 当前集成状态

Ozon 接口	Atlas 用途	当前状态
/v1/description-category/tree	平台级类目/商品类型树	已实现 Worker 同步；每 7 天自动同步并支持管理员手动同步
/v1/description-category/attribute	平台级类型属性	已实现管理员批次、用户按需刷新和发布预检刷新
/v1/description-category/attribute/values、values/search	平台级字典候选值	已实现单字典同步、按需读取和关键词补齐
/v3/product/import	首次商品导入	尚未实现；当前只完成 publish-preflights
/v1/product/import/info	导入结果轮询	尚未实现
商品列表、详情、库存、价格、跟卖、图片更新	后续商品运营能力	以对应模块交接状态为准，不在平台目录第 1～4 步范围内

Atlas 的平台目录接口、状态机和系统后台契约见平台类目与属性管理 API、商品编辑与发布 API及缓存刷新方案。