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

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 发布集成方案（与本文档配套）
• docs/v2/api.md - V2 后端 API 设计
• docs/v2/database.md - V2 数据库设计