R524809
4.0 KiB
4.0 KiB
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 |
关键约束
- 类目选择：只有末级类目（
disabled=false）可建品 - 必填字段：
name/description/category/price/尺寸重量/offer_id/images必填且不能为 0 - 图片 URL：必须是 https 公网直链（http 会被拒绝）
- 属性映射：
is_required=true的属性必须填写 - 异步任务：
/v3/product/import返回task_id，需轮询/v1/product/import/info获取最终状态 - 库存必须设置：
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及缓存刷新方案。