# 商品导入（创建/更新）API

> 官方文档：https://docs.ozon.ru/api/seller/zh/#operation/ProductAPI_ImportProductsV3

---

## 接口信息

| 项 | 值 |
|---|---|
| 方法 | POST |
| 路径 | `/v3/product/import` |
| 鉴权 | 需要 `Client-Id` + `Api-Key` |
| 用途 | **创建或更新商品**（Ozon 核心接口） |
| 异步 | ✅ 返回 `task_id`，需轮询 `/v1/product/import/info` 获取最终状态 |

---

## 1. 请求体结构

### 完整示例

```json
{
  "items": [
    {
      "offer_id": "MY-THERMOS-001",
      "name": "Термокружка Thermos из нержавеющей стали 500 мл",
      "description": "Термокружка из высококачественной нержавеющей стали. Сохраняет температуру до 6 часов.",
      "description_category_id": 17033876,
      "type_id": 97114,
      "price": "2990",
      "old_price": "3490",
      "currency_code": "RUB",
      "vat": "0",
      "depth": 80,
      "width": 80,
      "height": 200,
      "dimension_unit": "mm",
      "weight": 320,
      "weight_unit": "g",
      "images": [
        "https://cdn.example.com/thermos-main-1.jpg",
        "https://cdn.example.com/thermos-main-2.jpg"
      ],
      "primary_image": "",
      "images360": [],
      "color_image": "",
      "barcode": "",
      "attributes": [
        {
          "complex_id": 0,
          "id": 85,
          "values": [
            {
              "dictionary_value_id": 971082156,
              "value": "Thermos"
            }
          ]
        },
        {
          "complex_id": 0,
          "id": 8505,
          "values": [
            {
              "value": "Нержавеющая сталь"
            }
          ]
        }
      ],
      "complex_attributes": []
    }
  ]
}
```

---

## 2. 字段说明

### 基本信息

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| **offer_id** | string | ✅ 是 | **自己的货号**（唯一标识，用于更新）。最长 255 字符 |
| **name** | string | ✅ 是 | 商品名称。最长 500 字符 |
| **description** | string | ✅ 是 | 商品描述。最长 5000 字符，支持 HTML 标签 |
| **description_category_id** | integer | ✅ 是 | 类目 ID（从类目树获取） |
| **type_id** | integer | ✅ 是 | 商品类型 ID（从类目树获取） |

### 价格

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| **price** | string | ✅ 是 | 销售价（字符串格式，如 `"2990"` = 2990 卢布） |
| old_price | string | 可选 | 划线价（原价），用于展示折扣 |
| **currency_code** | string | ✅ 是 | 币种，通常 `"RUB"`（卢布）。也可 `"CNY"` 等 |
| **vat** | string | ✅ 是 | 增值税率：`"0"` / `"0.1"` / `"0.2"`。俄罗斯默认 `"0"` |

### 尺寸与重量

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| **depth** | number | ✅ 是 | 长度（包装尺寸）。**不能为 0** |
| **width** | number | ✅ 是 | 宽度（包装尺寸）。**不能为 0** |
| **height** | number | ✅ 是 | 高度（包装尺寸）。**不能为 0** |
| **dimension_unit** | string | ✅ 是 | 尺寸单位：`"mm"` / `"cm"` |
| **weight** | number | ✅ 是 | 重量（包装重量）。**不能为 0** |
| **weight_unit** | string | ✅ 是 | 重量单位：`"g"` / `"kg"` |

⚠️ **硬约束**：尺寸和重量必须 **> 0**，否则 API 返回 400 错误。

### 图片

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| **images** | array | ✅ 是 | **主图数组**（最多 15 张）。顺序即展示顺序，第一张为主图 |
| primary_image | string | 可选 | 主图（单独指定）。若使用则 `images` 最多 14 张 |
| images360 | array | 可选 | 360° 图片数组 |
| color_image | string | 可选 | 营销色图（部分类目支持） |

⚠️ **硬约束**：
- 图片 URL 必须是 **https 公网直链**（http 会被拒绝）
- 图片需可访问（Ozon 服务器会主动拉取）
- 建议尺寸：≥ 700×700 px，白底，主体占画面 80%+

### 属性

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| **attributes** | array | ✅ 是 | 商品属性数组（从类目属性获取） |
| attributes[].complex_id | integer | ✅ 是 | 复杂属性 ID，通常填 `0` |
| attributes[].id | integer | ✅ 是 | 属性 ID |
| attributes[].values | array | ✅ 是 | 属性值数组 |
| values[].dictionary_value_id | integer | 条件 | 字典值 ID（属性有字典时必填） |
| values[].value | string | ✅ 是 | 属性值文本 |

### 复杂属性

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| complex_attributes | array | 可选 | 复杂属性（视频、尺码表等） |

### 其他

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| barcode | string | 可选 | 条形码 |
| pdf_list | array | 可选 | PDF 文件 URL 列表 |

---

## 3. 响应

### 成功响应（200）

```json
{
  "result": {
    "task_id": 123456789
  }
}
```

| 字段 | 类型 | 说明 |
|---|---|---|
| task_id | integer | **任务 ID**（用于轮询状态，见下节） |

⚠️ **此时商品尚未创建**，需轮询 `/v1/product/import/info` 获取最终结果。

---

## 4. 轮询任务状态

### 接口信息

| 项 | 值 |
|---|---|
| 方法 | POST |
| 路径 | `/v1/product/import/info` |
| 鉴权 | 需要 `Client-Id` + `Api-Key` |

### 请求

```json
{
  "task_id": 123456789
}
```

### 响应

```json
{
  "result": {
    "items": [
      {
        "offer_id": "MY-THERMOS-001",
        "product_id": 987654321,
        "status": "imported",
        "errors": []
      }
    ]
  }
}
```

### 状态值

| status | 含义 | 处理 |
|---|---|---|
| **imported** | ✅ 导入成功 | 保存 `product_id`，标记商品为 `published` |
| **pending** | ⏳ 排队中 | 继续轮询（间隔 5s） |
| **processing** | ⏳ 处理中 | 继续轮询（间隔 5s） |
| **moderation** | ⏳ 审核中 | 继续轮询（间隔 30s，审核可能需几小时） |
| **failed** | ❌ 失败 | 读取 `errors` 数组，展示错误给用户 |

### 错误结构

```json
{
  "offer_id": "MY-THERMOS-001",
  "product_id": 0,
  "status": "failed",
  "errors": [
    {
      "code": "INVALID_ATTRIBUTE",
      "message": "Attribute 'Бренд' is required",
      "field": "attributes"
    }
  ]
}
```

---

## 5. 轮询策略

### 推荐策略

```python
import asyncio

async def wait_for_import(task_id: int, timeout=300):
    """轮询导入状态，最多等待 5 分钟"""
    start = time.time()
    interval = 5  # 初始间隔 5s
    
    while time.time() - start < timeout:
        resp = await ozon_client.get_import_info(task_id)
        item = resp["result"]["items"][0]
        status = item["status"]
        
        if status == "imported":
            return {"success": True, "product_id": item["product_id"]}
        
        if status == "failed":
            return {"success": False, "errors": item["errors"]}
        
        if status == "moderation":
            interval = 30  # 审核阶段降低频率
        
        await asyncio.sleep(interval)
    
    # 超时：不算失败，标记为"审核中"继续后台轮询
    return {"success": None, "status": "timeout"}
```

### 后台轮询（推荐）

```python
# 用户提交发布后立即返回，后台协程轮询
# 状态变化时通知前端（WebSocket / 长轮询 / 前端定时刷新）

async def background_poll_task(task_id: int, product_id: str):
    """后台协程，轮询直到完成或失败"""
    result = await wait_for_import(task_id, timeout=3600)  # 最多 1 小时
    
    # 更新数据库
    await db.execute(
        update(Product)
        .where(Product.id == product_id)
        .values(
            stage="published" if result["success"] else "failed",
            ozon_product_id=result.get("product_id"),
            published_at=datetime.utcnow() if result["success"] else None
        )
    )
    
    # 记录任务结果
    await db.execute(
        update(PublishTask)
        .where(PublishTask.ozon_task_id == task_id)
        .values(
            status=result.get("status"),
            errors=result.get("errors"),
            completed_at=datetime.utcnow()
        )
    )
```

---

## 6. 创建 vs 更新

### 创建新商品

```json
{
  "offer_id": "NEW-PRODUCT-001",  // 全新 offer_id
  // ... 其他字段
}
```

- 如果 `offer_id` 不存在 → 创建新商品
- 如果 `offer_id` 已存在 → 返回 409 冲突

### 更新已有商品

```json
{
  "offer_id": "EXISTING-001",  // 已存在的 offer_id
  // ... 要更新的字段（可部分更新）
}
```

或使用 `product_id`：

```json
{
  "product_id": 987654321,  // Ozon 商品 ID
  // ... 要更新的字段
}
```

⚠️ **注意**：
- 更新时，未传的字段**保持原值**（非清空）
- 图片数组传空 `[]` 会清空图片（需小心）
- 建议更新前先读取当前值（`/v3/product/info/list`）

---

## 7. 批量导入

单次请求最多 **100 个 item**：

```json
{
  "items": [
    { "offer_id": "PROD-001", /* ... */ },
    { "offer_id": "PROD-002", /* ... */ },
    // ... 最多 100 个
  ]
}
```

响应包含每个 item 的状态：

```json
{
  "result": {
    "items": [
      { "offer_id": "PROD-001", "status": "imported", "product_id": 111 },
      { "offer_id": "PROD-002", "status": "failed", "errors": [...] }
    ]
  }
}
```

---

## 8. 常见错误

### 错误码速查

| code | message | 原因 | 解决 |
|---|---|---|---|
| `INVALID_PARAMETER` | 参数错误 | 必填字段缺失 / 格式错误 | 检查字段完整性 |
| `INVALID_ATTRIBUTE` | 属性错误 | 缺少必填属性 / 字典值不匹配 | 补全必填属性，校验字典值 |
| `INVALID_CATEGORY` | 类目错误 | `description_category_id` 不存在或已禁用 | 重新选择类目 |
| `INVALID_IMAGE` | 图片错误 | URL 不可访问 / 非 https / 格式不支持 | 检查图片 URL 有效性 |
| `OFFER_ID_DUPLICATE` | offer_id 重复 | 该 offer_id 已存在 | 换一个唯一 offer_id 或走更新 |
| `DIMENSION_REQUIRED` | 尺寸必填 | 尺寸/重量为 0 或缺失 | 填写正确尺寸重量 |
| `PRICE_INVALID` | 价格错误 | 价格 ≤ 0 或格式错误 | 检查价格字段 |

### 典型错误示例

#### 错误 1：尺寸为 0

```json
{
  "errors": [
    {
      "code": "DIMENSION_REQUIRED",
      "message": "Dimensions must be greater than 0",
      "field": "weight"
    }
  ]
}
```

**解决**：确保 `depth/width/height/weight` 都 > 0。

#### 错误 2：缺少必填属性

```json
{
  "errors": [
    {
      "code": "INVALID_ATTRIBUTE",
      "message": "Required attribute 'Бренд' (id=85) is missing",
      "field": "attributes"
    }
  ]
}
```

**解决**：补充缺失的必填属性。

#### 错误 3：图片 URL 不可访问

```json
{
  "errors": [
    {
      "code": "INVALID_IMAGE",
      "message": "Image URL is not accessible: https://...",
      "field": "images[0]"
    }
  ]
}
```

**解决**：
1. 检查 URL 是 https（非 http）
2. 检查 URL 公网可访问（Ozon 服务器需能拉取）
3. 检查图片格式（支持 jpg/png/webp）

---

## 9. 发布后操作

### 设置库存（必须）

商品导入成功后**不会自动上架**，需设置库存才能开售：

```http
POST /v2/products/stocks
```

```json
{
  "stocks": [
    {
      "product_id": 987654321,
      "offer_id": "MY-THERMOS-001",
      "stock": 100,
      "warehouse_id": 12345678
    }
  ]
}
```

⚠️ 不设置库存 → 商品在后台但不可购买。

### 查询商品详情

```http
POST /v3/product/info/list
```

```json
{
  "offer_id": ["MY-THERMOS-001"]
}
```

返回商品完整信息（含审核状态、图片、属性）。

---

## 10. V2 项目集成

### API 层（已实现）

```python
# server/api/publish.py

@router.post("/products/{product_id}/publish")
async def publish_product(
    product_id: str,
    shop_id: str = Body(...),
    db: AsyncSession = Depends(get_db)
):
    # 1. 取商品数据
    product = await get_product(db, product_id)
    
    # 2. 校验必填项
    validate_required_fields(product)
    
    # 3. 组装 ImportProductsV3 请求体
    item = build_import_item(product)
    
    # 4. 调用 Ozon API
    shop = await get_shop(db, shop_id)
    resp = await ozon_client.import_products(
        shop.client_id_dec,
        shop.api_key_dec,
        [item]
    )
    
    task_id = resp["result"]["task_id"]
    
    # 5. 记录发布任务
    task = PublishTask(
        product_id=product_id,
        shop_id=shop_id,
        ozon_task_id=task_id,
        status="pending",
        request_payload=item
    )
    db.add(task)
    await db.commit()
    
    # 6. 启动后台轮询
    asyncio.create_task(background_poll_task(task_id, product_id))
    
    return {"task_id": task_id}

def build_import_item(product: Product) -> dict:
    """组装 ImportProductsV3 items[0]"""
    return {
        "offer_id": product.offer_id,
        "name": product.name,
        "description": product.description,
        "description_category_id": product.description_category_id,
        "type_id": product.type_id,
        "price": str(product.price),
        "old_price": str(product.old_price) if product.old_price else "",
        "currency_code": product.currency_code,
        "vat": product.vat,
        "depth": product.depth,
        "width": product.width,
        "height": product.height,
        "dimension_unit": product.dimension_unit,
        "weight": product.weight,
        "weight_unit": product.weight_unit,
        "images": product.images,  # 七牛 URL 数组
        "primary_image": product.primary_image or "",
        "images360": product.images360 or [],
        "color_image": product.color_image or "",
        "barcode": product.barcode or "",
        "attributes": product.attributes or [],
        "complex_attributes": product.complex_attributes or []
    }
```

### 前端（待实现）

```tsx
// studio/src/pages/product/components/PublishPanel.tsx

import { Button, Select, message } from 'antd';

export function PublishPanel({ productId }) {
  const [shops, setShops] = useState([]);
  const [publishing, setPublishing] = useState(false);
  
  const handlePublish = async (shopId) => {
    setPublishing(true);
    try {
      const resp = await fetch(`/api/products/${productId}/publish`, {
        method: 'POST',
        body: JSON.stringify({ shop_id: shopId })
      });
      const data = await resp.json();
      
      message.success('发布任务已提交，轮询中...');
      
      // 轮询状态（或 WebSocket 推送）
      pollPublishStatus(data.task_id);
    } catch (err) {
      message.error(`发布失败: ${err.message}`);
    } finally {
      setPublishing(false);
    }
  };
  
  return (
    <div>
      <Select
        placeholder="选择目标店铺"
        options={shops.map(s => ({ label: s.name, value: s.id }))}
        onChange={handlePublish}
      />
      <Button
        type="primary"
        loading={publishing}
        onClick={() => /* trigger select */}
      >
        发布到 Ozon
      </Button>
    </div>
  );
}
```

---

## 相关文档

- [02-category-tree.md](./02-category-tree.md) —— 获取类目
- [03-category-attributes.md](./03-category-attributes.md) —— 获取属性
- [05-product-info.md](./05-product-info.md) —— 查询商品详情
- [09-stocks.md](./09-stocks.md) —— 设置库存（必须）
- [docs/v2/ozon-publish.md](../v2/ozon-publish.md) —— 发布集成方案