# Ozon 商品导入 API（2026-09-30 核对）

官方：[创建或更新商品](https://docs.ozon.ru/api/seller/en/#operation/ProductAPI_ImportProductsV3)、[导入状态](https://docs.ozon.ru/api/seller/en/#operation/ProductAPI_GetImportProductsInfo)、[商品信息](https://docs.ozon.ru/api/seller/en/#operation/ProductAPI_GetProductInfoList)。Atlas 的产品流程、字段来源和错误契约以 [商品编辑与首次上架](../../api/product-editor-and-publishing.md) 为准。

## 创建或更新商品

`POST /v3/product/import`，鉴权 Header 为 `Client-Id` / `Api-Key`。Ozon 每批最多 100 个 item，Atlas 首期收紧为最多 50 个 SKU。此接口也会更新已存在的货号，不能依赖“重复货号必定返回 409”。Atlas 在提交前查询当前店铺货号，存在时跳过；提交结果不确定时先对账，不能直接重发。

```json
{
  "items": [{
    "offer_id": "ATLAS-THERMOS-001",
    "name": "Термокружка из нержавеющей стали 500 мл",
    "description_category_id": 17033876,
    "type_id": 97114,
    "price": "2990.00",
    "old_price": "3490.00",
    "currency_code": "RUB",
    "depth": 80,
    "width": 80,
    "height": 200,
    "dimension_unit": "mm",
    "weight": 320,
    "weight_unit": "g",
    "images": ["https://images.example.test/publishing/photo.jpg"],
    "attributes": [{"complex_id": 0, "id": 9048, "values": [{"value": "ATLAS-THERMOS"}]}]
  }]
}
```

示例类目、类型和属性必须替换为目标类目当前有效目录，不可直接作为真实商品输入。

| 字段 | 当前约束 / Atlas 首期处理 |
|---|---|
| `offer_id` | 最多 50 字符；每个 SKU 独立货号，当前店铺唯一 |
| `name` | 最多 500 字符；按已保存的标题模式选择通用或 SKU 标题 |
| `description_category_id` / `type_id` | 当前有效类目、类型数值 ID |
| `price` / `old_price` | 十进制字符串；售价大于零，划线价大于售价时才传 |
| `currency_code` | 与目标店铺实际币种一致 |
| `vat` | 官方俄/英文 OpenAPI 可选，中文版列为必填，存在差异；`0` 表示不征收 VAT，其他列出的值为 `0.05`、`0.07`、`0.1`、`0.2`、`0.22`。Atlas 中国主体跨境 rFBS 首期省略，真实测试后确认，不设置默认税率 |
| 包装规格 | 正整数 mm/g；每个 SKU 合并通用默认值与自己的覆盖值，不传商品本体规格 |
| `images` | JPG/PNG 公网链接，最多 30 张，第一张主图；若额外传 `primary_image`，则 images 最多 29 张。Atlas 首期不另传 `primary_image` |
| `attributes` | 按当前类目定义拼装；字典值用官方 ID 和文本，SKU aspect 属性独立解析。品牌、型号、标签和描述仅映射当前类目有效的固定属性 |
| 商品描述 | 不在 item 顶层传 `description`，应通过描述属性（例如当前类目可用时的 4191）填写 |
| 条码 / 库存 / 仓库 | rFBS 首期不传；不将 SPU 共用条码复制到多个 SKU |
| 视频、富内容、360 图 | 首期不发布 |

返回 `{"result":{"task_id":123456789}}` 只表示受理，商品导入仍需查询任务状态。

## 查询导入结果

`POST /v1/product/import/info` 请求 `{"task_id":123456789}`，返回 `result.items[]`，每项含 `offer_id`、`product_id`、`status`、`errors`。

| 状态 | 处理 |
|---|---|
| `pending` | 继续轮询，等待导入 |
| `imported` | 保存远端 product ID，确认该 SKU 已导入；不等于审核通过、前台可见或有库存 |
| `failed` | 保存脱敏错误，用户修正后可以新建首次发布任务 |
| `skipped` | 对账确认是否已有商品；不能仅凭 skipped 声称导入成功 |

审核状态应从商品信息接口读取，不能将 `processing` / `moderation` 当成此导入任务的 item 状态。

## 查询商品信息与对账

`POST /v3/product/info/list` 可传 `offer_id` / `product_id` / `sku`。当前官方响应为**顶层 `items[]`**，不是 `result.items[]`；每个商品含 `id`、`offer_id`、`vat`、`statuses` 等字段。

Atlas 用它检查远端货号、恢复提交结果和核对 VAT。任务受理后不得因 HTTP 超时就重新发 `/v3/product/import`。无法确认时保持“等待对账”，禁止当前 SKU 再次入队。

## 图片签名与上线验收

素材从 Atlas 正式对象存储交付；10 分钟页面预览 URL 不用于发布。Worker 校验素材 checksum，为本次发布复制固定对象，将 WebP 转 JPEG，并从七牛 HTTPS 下载域名签发独立有效期 URL。URL 及签名不写入数据库、Outbox 或日志。

真实中国主体跨境 rFBS 店铺的 VAT 行为、七牛域名 / 证书 / 过期时间和 Ozon 延迟抓取仍须联调验收。生产默认关闭上架，验收后显式设置 `OZON_PUBLISH_ENABLED=true`。配置参见 `.env.example`。