Joey
144 lines
4.3 KiB
Markdown
144 lines
4.3 KiB
Markdown
# Ozon Seller API 文档整理完成
|
||
|
||
已完成 Ozon Seller API 的核心接口文档整理，涵盖商品发布、管理的完整流程。
|
||
|
||
## 已完成的文档
|
||
|
||
### 核心文档（9 个）
|
||
|
||
1. **README.md** - 总览与快速索引
|
||
2. **01-authentication.md** - 鉴权方式、Base URL、错误码、限流
|
||
3. **02-category-tree.md** - 类目树查询（选择类目）
|
||
4. **03-category-attributes.md** - 类目属性与字典值（属性映射）
|
||
5. **04-product-import.md** - 商品导入/创建/更新（核心接口）
|
||
6. **05-product-info.md** - 商品详情查询（审核状态、图片、属性）
|
||
7. **06-product-list.md** - 商品列表分页（ID 收集、批量查询）
|
||
8. **09-stocks.md** - 库存管理（必须设置才能上架）
|
||
|
||
### 待补充（二期）
|
||
|
||
- **07-import-by-sku.md** - 跟卖（按 SKU 复制 PDP）
|
||
- **08-pictures.md** - 图片更新
|
||
- **10-prices.md** - 价格批量更新
|
||
|
||
---
|
||
|
||
## 文档特色
|
||
|
||
### 1. 完整的代码示例
|
||
- Python（服务端）示例
|
||
- TypeScript（前端）示例
|
||
- 实际可运行的代码片段
|
||
|
||
### 2. V2 项目集成指引
|
||
- 每个文档都包含"V2 项目集成"章节
|
||
- API 层实现示例（对齐 server/ 结构）
|
||
- 前端组件示例（对齐 studio/ 结构）
|
||
|
||
### 3. 最佳实践与常见问题
|
||
- 缓存策略
|
||
- 错误处理
|
||
- 性能优化
|
||
- 分页/批量操作
|
||
|
||
### 4. 实用场景
|
||
- 发布流程（端到端）
|
||
- 属性映射工作流
|
||
- 库存同步策略
|
||
- 审核状态检查
|
||
|
||
---
|
||
|
||
## 核心流程速查
|
||
|
||
### 完整发布流程
|
||
|
||
```
|
||
① 获取类目树 → 选择类目
|
||
POST /v1/description-category/tree
|
||
|
||
② 获取类目属性 → 映射属性
|
||
POST /v1/description-category/attribute
|
||
POST /v1/description-category/attribute/values/search
|
||
|
||
③ 组装请求体 → 发布商品
|
||
POST /v3/product/import → task_id
|
||
|
||
④ 轮询状态 → 获取 product_id
|
||
POST /v1/product/import/info → status=imported
|
||
|
||
⑤ 设置库存（必须）
|
||
POST /v2/products/stocks → 商品上架
|
||
|
||
⑥ 查询详情（可选）
|
||
POST /v3/product/info/list → 审核状态/图片/库存
|
||
```
|
||
|
||
### 关键约束总结
|
||
|
||
1. **类目**：只有末级类目（`disabled=false`）可建品
|
||
2. **必填字段**：name/description/category/price/尺寸重量/offer_id/images
|
||
3. **图片 URL**：必须 https 公网直链
|
||
4. **属性**：`is_required=true` 的必须填写
|
||
5. **异步任务**：`/import` 返回 task_id，需轮询状态
|
||
6. **库存必须设置**：不设置库存 = 商品不可购买
|
||
|
||
---
|
||
|
||
## 与 V2 项目的对应关系
|
||
|
||
| Ozon API | V2 后端 API | V2 前端页面 | 状态 |
|
||
|---|---|---|---|
|
||
| `/description-category/tree` | `/api/categories/tree` | CategoryPicker | ✅ 已建 |
|
||
| `/description-category/attribute` | `/api/categories/{id}/attributes` | AttributeMapper | ✅ 已建 |
|
||
| `/attribute/values` | `/api/categories/attribute/{id}/values` | - | ✅ 已建 |
|
||
| `/v3/product/import` | `/api/products/{id}/publish` | PublishPanel | ✅ 已建 |
|
||
| `/v1/product/import/info` | (background poll) | - | ✅ 已建 |
|
||
| `/v3/product/info/list` | `/api/products/{id}/ozon-detail` | OzonStatusBadge | 🟡 待建 |
|
||
| `/v3/product/list` | `/api/products/sync-from-ozon` | SyncButton | 🟡 待建 |
|
||
| `/v2/products/stocks` | `/api/products/{id}/set-stock` | StockPanel | 🟡 待建 |
|
||
|
||
---
|
||
|
||
## 使用建议
|
||
|
||
### 阅读顺序（新接入）
|
||
|
||
1. **01-authentication.md** - 了解鉴权与基础
|
||
2. **04-product-import.md** - 核心接口，先看这个
|
||
3. **02-category-tree.md** - 类目选择
|
||
4. **03-category-attributes.md** - 属性映射（难点）
|
||
5. **09-stocks.md** - 库存设置（必须）
|
||
6. 其他按需查阅
|
||
|
||
### 开发时查阅
|
||
|
||
- 看接口契约 → 查对应章节的"请求/响应"
|
||
- 看错误处理 → 查"常见错误"章节
|
||
- 看集成方式 → 查"V2 项目集成"章节
|
||
- 看最佳实践 → 查"使用场景"或"最佳实践"章节
|
||
|
||
---
|
||
|
||
## 下一步
|
||
|
||
### 立即可用
|
||
现有 9 个文档已覆盖 V2 项目一期的所有核心接口，可立即用于：
|
||
- 服务端 `ozon_client.py` 开发
|
||
- API 端点实现参考
|
||
- 前端组件开发参考
|
||
|
||
### 二期补充
|
||
需要时再补充：
|
||
- 跟卖（import-by-sku）
|
||
- 图片单独更新
|
||
- 价格批量更新
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- [docs/v2/ozon-publish.md](../v2/ozon-publish.md) - V2 发布集成方案（与本文档配套）
|
||
- [docs/v2/api.md](../v2/api.md) - V2 后端 API 设计
|
||
- [docs/v2/database.md](../v2/database.md) - V2 数据库设计
|