atlas-seller-kit/docs/product/api.md

商品编辑 API 契约

接口前缀与鉴权细节待基础架构确认。所有请求由当前用户、工作空间、门店上下文授权；客户端不能跨租户指定 ID。

1. 采集与读取

接口	用途
POST /api/stores/{store_id}/materials	上报采集商品与可选 SKU 数组；无 SKU 数组时创建默认 SKU。
GET /api/products/{product_id}/editor	返回编辑页所需商品、SKU、属性 schema、媒体和草稿版本。
GET /api/products/{product_id}/validation	返回父商品和逐 SKU 的本地发布校验。

采集变体按 platform + source_item_key + source_variant_key 幂等。只有来源明确给出 SKU—图片关联时才能绑定 SKU；其他图片进入商品候选池。未知口径的规格保留原文并标为 ambiguous。

2. 草稿、SKU 与属性

接口	用途
PUT /api/products/{product_id}/editor-draft	原子保存商品、SKU、属性、排序和媒体选择；使用 ETag/版本号冲突控制。
POST /api/products/{product_id}/variants	创建或复制 SKU。
PATCH /api/products/{product_id}/variants/{variant_id}	修改 SKU；可继承字段传 null 恢复默认值。
DELETE /api/products/{product_id}/variants/{variant_id}	软删除未发布 SKU；已发布 SKU 改停用并留给发布流程处理。
GET /api/products/{product_id}/attribute-schema	按门店平台和当前类目返回动态属性 schema/字典。

schema 适配器对 Ozon 调用 /v1/description-category/attribute 和字典值接口，读取 type、is_required、is_collection、max_value_count、dictionary_id、is_aspect。对其他平台提供同一内部 schema 形状。

3. 定价、媒体和 AI

接口	用途
POST /api/products/{product_id}/variants/{variant_id}/pricing/quote	用服务端有效包装规格计算预览，不落价。
POST /api/products/{product_id}/variants/{variant_id}/pricing/confirm	重新计算、校验、保存快照并回填售价/划线价。
GET/PUT /api/products/{product_id}/variants/{variant_id}/media	读取候选媒体/保存 SKU 已选媒体及顺序。
POST /api/products/{product_id}/ai/copy	生成父商品的多语言标题、标签、简介等候选草稿。
POST /api/products/{product_id}/ai/suite-plans	创建显式绑定目标 SKU 的套图规划。
POST /api/products/{product_id}/variants/{variant_id}/ai/dimension-image	创建单 SKU 尺寸图任务，并固化实物规格快照。

确认定价失败（缺失/待确认/无效包装规格或物流校验失败）返回 422，不改写现有价格。AI 返回候选结果，不能未经用户确认覆盖手工内容。

4. 后续发布

未来平台适配器接受“父商品 + 单 SKU”规范化对象。Ozon 实现将每个启用 SKU 转换为一个 /v3/product/import.items[]：复制通用标题、简介、类目和通用属性；填入 SKU offer、价格、包装规格、图片和变体属性。批量按平台限制分组，结果按 SKU 独立保存。