Ozon Seller API 商品详情全套接口

请求头（所有商品接口必填）

http

复制代码

Client-Id: 你的店铺ClientID
Api-Key: 后台生成的API密钥
Content-Type: application/json

3. 两套核心详情接口分工

表格

接口	地址	用途	可获取数据
商品基础信息列表	`/v3/product/info/list`	批量查商品基础数据（必用）	product_id、offer_id、标题、价格、多仓库存、类目、商品状态、图片、变体 SKU、重量尺寸、品牌
商品完整属性详情	`/v4/product/info/attributes`	拉全量类目参数、规格、详情描述、视频	类目属性、自定义参数、富文本描述、视频链接、证书信息
商品长描述单独接口	`/v1/product/info/description`	仅获取商品详情 HTML 文本	商品长描述、富媒体内容

一、主接口：v3/product/info/list（90% 场景首选）

接口地址

POST /v3/product/info/list

核心能力

单次最多100 个商品批量查询
支持两种查询条件二选一：product_id（平台商品 ID 数组）/ offer_id（商家自定义 SKU 编码数组）
返回商品售卖全基础数据，库存、价格、变体、图片一站式获取

请求 Body 示例

json

复制代码

{
  "product_id": [12345678, 87654321],
  "offer_id": [],
  "visibility": "VISIBLE"
}

参数说明：

product_id：Ozon 平台商品数字 ID，数组
offer_id：你自己的商品货号 SKU，数组
visibility 筛选：
- VISIBLE：在售上架商品
- INVISIBLE：下架 / 审核中
- ALL：全部商品

返回关键字段说明

json

复制代码

{
  "result": [
    {
      "product_id": 12345678,
      "offer_id": "SKU-RED-001",
      "product_id_str": "12345678",
      "name": "商品标题",
      "price": "1990.00",
      "old_price": "2500.00",
      "visibility": "VISIBLE",
      "visibility_details": {"state": "visible"},
      "images": ["https://xxx.jpg","https://xxx2.jpg"], // 主图列表
      "primary_image": "https://xxx.jpg", // 首图
      "brand": {"id": 111, "name": "品牌名"},
      "category": {"id": 5001, "name": "一级类目"},
      "width": 10, "height": 20, "depth": 15, "weight": 0.5, // 包装尺寸重量(cm/kg)
      "stock": [ // 多仓库库存
        {"warehouse_id": 99, "present": 120, "reserved": 5, "available": 115}
      ],
      "skus": [ // 变体SKU数组（多规格商品）
        {"sku_id": "0001", "offer_id": "SKU-RED-001", "price": "1990.00"}
      ],
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-06-10T12:00:00Z"
    }
  ]
}

二、完整属性详情接口：v4/product/info/attributes

接口地址

POST /v4/product/info/attributes

用途

v3 接口只返回基础信息，类目参数、颜色尺寸材质等属性、视频、详情文案全部在这里获取，上架 / 同步商品完整卡片必须调用此接口。

请求 Body

json

复制代码

{
  "product_id": [12345678]
}

返回核心结构

json

复制代码

{
  "result": [
    {
      "product_id": 12345678,
      "offer_id": "SKU-RED-001",
      "attributes": [
        {
          "id": 9999,
          "name": "Цвет", // 属性名（俄语）
          "value": "Красный", // 属性值
          "value_id": 123,
          "type": "SELECT", // 单选/文本/数字
          "is_required": true
        }
      ],
      "videos": [{"url": "https://video.ozon.ru/xxx.mp4"}],
      "description": "商品长描述文本",
      "short_description": "简短卖点",
      "certificates": [] // 商品证书
    }
  ]
}

三、单独获取商品描述接口：v1/product/info/description

接口地址

POST /v1/product/info/description

请求

json

复制代码

{
  "product_id": [12345678]
}

json

复制代码

{
  "result": [
    {
      "product_id": 12345678,
      "description": "<p>富文本HTML详情</p>",
      "short_description": "简短描述"
    }
  ]
}

四、完整调用流程（ERP 同步商品标准逻辑）

拉全店商品列表 POST /v1/product/list 分页获取所有商品 product_id / offer_id
批量拉基础信息 循环调用 /v3/product/info/list，获取价格、库存、图片、尺寸、变体
拉完整属性参数 调用 /v4/product/info/attributes 获取类目规格、视频、详情文案
合并两套接口数据，组装完整商品详情落地库

五、Python 完整调用示例（v3 商品基础详情）

python

运行

复制代码

import requests

headers = {
    "Client-Id": "你的ClientID",
    "Api-Key": "你的API密钥",
    "Content-Type": "application/json"
}

url = "https://api-seller.ozon.ru/v3/product/info/list"
payload = {
    "product_id": [12345678],
    "visibility": "ALL"
}

resp = requests.post(url, headers=headers, json=payload)
data = resp.json()
print(data)

六、高频踩坑说明

401 鉴权失败 ClientID/ApiKey 复制错误；密钥后台删除 / 重新生成过，旧密钥失效
一次最多 100 个 ID product_id/offer_id 数组长度不能超过 100，大批量商品必须分页循环
库存数据在 stock 数组 区分 present 总库存、reserved 锁定库存、available 可售库存
变体商品 skus 数组 多规格（颜色 / 尺寸）商品每个 SKU 独立报价，改价需对应 sku_id
限流规则 商品类接口统一 80 次 / 分钟，批量循环建议加 0.5s 延时，避免 429 限流报错
审核中商品 visibility=INVISIBLE，库存价格不对外展示，API 仍可正常读取数据