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

# 商品编辑 API 契约

> 本文是早期产品级接口草案，部分路径和状态已经被实现契约取代，不应直接作为联调依据。尤其下文的独立 AI 类目/文案接口与逐项人工应用流程已由[统一 AI 填报方案](./ai-autofill-plan.md)取代。当前端点、平台目录缓存和发布预检以 [`../api/product-editor-and-publishing.md`](../api/product-editor-and-publishing.md) 为准；所有请求仍须按当前用户、工作空间和平台/门店上下文授权，客户端不能跨租户指定 ID。浏览器插件采集入口以 [`../requirements/collector-browser-extension.md`](../requirements/collector-browser-extension.md) 为准。

## 1. 采集与读取

| 接口 | 用途 |
|---|---|
| `GET /api/extension/session` | 供插件确认当前 Atlas 登录状态和工作空间是否可用；不返回平台、门店或凭据。 |
| `POST /api/extension/materials` | 扩展上报 `CollectedProductPayload`。服务端从扩展令牌解析工作空间，幂等创建/复用未绑定目标平台/门店的采集记录、商品草稿、真实 SKU 草稿和素材转存任务。请求体不得传入 `workspace_id`、`platform_id` 或 `store_id`。 |
| `POST /api/collection-items/{collection_item_id}/seller-enrichment-observations` | 插件在本地 Seller 观察开关开启时上报第 7.3 节四接口的净化结果；不接收 Cookie。 |
| `GET /api/collection-items/{collection_item_id}` | 返回采集记录、已发现 SKU、素材转存状态、Seller 观察结果摘要与警告。 |
| `POST /api/collection-items/{collection_item_id}/start-editing` | ERP 根据页头当前 `platform_id` 进入编辑。服务端验证平台，取得/创建该商品的平台发布配置并预选当前工作空间在该平台的默认店铺后返回编辑页地址；请求不得传 `store_id`。 |
| `GET /api/products/{product_id}/editor` | 返回编辑页所需商品、SKU、属性 schema、媒体和草稿版本。 |
| `GET /api/products/{product_id}/validation` | 返回父商品和逐 SKU 的本地发布校验。 |

采集记录在同一工作空间内按 `source_platform + source_item_key` 幂等；其变体按 `source_platform + source_item_key + source_variant_key` 幂等。采集阶段不写入目标平台或店铺。只有来源明确给出 SKU—图片关联时才能绑定 SKU；其他图片进入商品候选池。未知口径的规格保留原文并标为 `ambiguous`。扩展的四个 Seller 网页内部接口必须在用户浏览器本地执行，API 只接收净化结果或 `unavailable` 原因。

## 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/字典。 |
| `PUT /api/products/{product_id}/platform-profiles/{platform_id}/target-store` | 更改当前平台发布配置预选的已授权门店；不修改既有 SKU 发布快照。 |
| `POST /api/products/{product_id}/platform-profiles/{platform_id}/ai-category-suggestions` | 基于采集证据和当前平台类目树创建 AI 类目候选任务；返回候选、置信度与依据。 |
| `POST /api/products/{product_id}/platform-profiles/{platform_id}/ai-category-suggestions/{suggestion_id}/apply` | 用户确认后应用一个候选类目，再拉取对应属性 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}/variants/{variant_id}/media/{asset_id}/watermark` | 用用户选择的模板创建水印派生图；确认后替换当前 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 独立保存；成功导入 SKU 不允许由采集箱再次提交。

首期导入不调用库存接口，也不选择目标仓库。`/v3/product/import` 不要求仓库；`/v2/products/stocks` 才要求 `warehouse_id`，且库存 `0` 会令商品不可购买。因此库存由用户在 Ozon 后台设置，采集箱的“上架”仅表示首次导入成功，在线商品另行展示实际 `visible` 和库存状态。

Ozon 导入请求的 `images` 字段需要 HTTPS 公网可访问 URL，但 Atlas 不把该 URL 作为素材的长期主数据。发布适配器从已选 `media_asset` 的 `storage_provider + bucket + object_key` 生成适合 Ozon 拉取的短时或受控分发 URL，并将实际发送值固化在发布快照/请求审计中；素材表本身始终以 `object_key` 为准。