R524809
4.7 KiB
Ozon 商品导入 API（2026-09-30 核对）
官方：创建或更新商品、导入状态、商品信息。Atlas 的产品流程、字段来源和错误契约以 商品编辑与首次上架 为准。
创建或更新商品
POST /v3/product/import，鉴权 Header 为 Client-Id / Api-Key。Ozon 每批最多 100 个 item，Atlas 首期收紧为最多 50 个 SKU。此接口也会更新已存在的货号，不能依赖“重复货号必定返回 409”。Atlas 在提交前查询当前店铺货号，存在时跳过；提交结果不确定时先对账，不能直接重发。
{
"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。