feat: 开发采集、采集箱和商品编辑功能

2026-08-15 22:17:26 +08:00
parent c61d1a3154
commit 36357843d0
130 changed files with 18005 additions and 12 deletions
@@ -0,0 +1,102 @@
+# Ozon Seller API 文档总览
+
+> 本目录整理 Ozon Seller API 的核心接口文档，供 ozon-seller-kit 项目集成使用。
+> 官方文档：https://docs.ozon.ru/api/seller/zh/
+
+---
+
+## 目录
+
+| 文档 | 内容 |
+|---|---|
+| [01-authentication.md](./01-authentication.md) | 鉴权方式、请求头、错误码 |
+| [02-category-tree.md](./02-category-tree.md) | 类目树查询 |
+| [03-category-attributes.md](./03-category-attributes.md) | 类目属性与字典值 |
+| [04-product-import.md](./04-product-import.md) | 商品导入（创建/更新） |
+| [05-product-info.md](./05-product-info.md) | 商品信息查询 |
+| [06-product-list.md](./06-product-list.md) | 商品列表 |
+| [07-import-by-sku.md](./07-import-by-sku.md) | 跟卖（按 SKU 复制） |
+| [08-pictures.md](./08-pictures.md) | 图片更新 |
+| [09-stocks.md](./09-stocks.md) | 库存管理 |
+| [10-prices.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` | 价格 | 🟡 待建（二期） |