ozon-seller-kit/docs/ozon-seller-api/README.md

Ozon Seller API 文档总览

本目录整理 Ozon Seller API 的核心接口文档，供 ozon-seller-kit 项目集成使用。 官方文档：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	商品列表
07-import-by-sku.md	跟卖（按 SKU 复制）
08-pictures.md	图片更新
09-stocks.md	库存管理
10-prices.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	服务端错误	重试或联系支持

---

V2 项目集成清单

接口	用途	实现状态
/v1/description-category/tree	类目树	✅ API 已建（categories.py）
/v1/description-category/attribute	类目属性	✅ API 已建
/v1/description-category/attribute/values	属性值字典	✅ API 已建
/v3/product/import	商品导入	✅ API 已建（publish.py）
/v1/product/import/info	导入状态	✅ API 已建
/v3/product/list	商品列表	🟡 待建
/v3/product/info/list	商品详情	🟡 待建
/v1/product/import-by-sku	跟卖	🟡 待建（二期）
/v1/product/pictures/import	图片更新	🟡 待建（二期）
/v2/products/stocks	库存	🟡 待建（二期）
/v1/product/import/prices	价格	🟡 待建（二期）