admin9webs/atomk-hermes-skills

Fork 0

Files

T

admin9webs 67aec72faf Add archived/ozon-seller-api

2026-07-10 16:10:31 +08:00

16 KiB

Raw Blame History

name, description, version, tags

name

description

version

Ozon Seller API 操作手册

认证

Ozon Seller API 使用两个 Header 认证：

Client-Id: 店铺的 client_id（数字字符串）
Api-Key: 店铺的 API Key（UUID 格式，36字符）
Content-Type: application/json

无需 Bearer Token，不需要 JWT，直接 Header 传参即可。

店铺凭据（admincao 下）

Store	client_id	说明
Ozon-Hzqjone	3098640	手机 15718853624
Ozon-Hzqjtwo	3103005	手机 13011158945

API Key 存储在 AtomK 后台 store 的 extra_data.api_key 字段，或本地 /home/ubuntu/.hermes/credentials/accounts.md。

API 端点（已验证可用 vs 废弃）

✅ 可用端点

端点	用途	备注
`POST /v3/product/list`	获取产品ID列表	⚠️ last_id 必须是空字符串 `""`
`POST /v3/product/info/list`	批量获取产品详情	⚠️ 响应结构陷阱见下方

❌ 废弃/404 端点

端点	状态	说明
`POST /v2/product/list`	404	已废弃
`POST /v2/product/info`	404	已废弃
`POST /v2/product/info/list`	404	已废弃
`POST /v1/product/info`	404	不存在
`POST /v4/product/info`	404	不存在
`POST /v5/product/info`	404	不存在
`POST /v3/product/info`	404	单个产品查询不存在

Base URL: https://api-seller.ozon.ru

核心陷阱与避坑

陷阱1：v3/product/list 的 last_id 参数

# ❌ 错误 — 整数 0
{"last_id": 0}
# 报错：invalid value for string field last_id: 0

# ❌ 错误 — 字符串 "0"
{"last_id": "0"}
# 报错：invalid base64 data at input byte 0

# ✅ 正确 — 空字符串（首页）
{"last_id": ""}

last_id 是 base64 编码的分页游标，首页必须传空字符串 ""。后续页使用上一次返回的 last_id 值。

陷阱2：v3/product/info/list 响应结构

# ❌ 错误 — 以为在 result.items 下
products = result.get("result", {}).get("items", [])
# 返回空列表，因为 result 键不存在

# ✅ 正确 — items 在顶层
products = result.get("items", [])

与 v3/product/list 返回 {"result": {"items": [...]}} 不同，v3/product/info/list 返回的是 {"items": [...]}，没有 result 包裹层！

陷阱3：v3/product/list 返回结构

{
  "result": {
    "items": [
      {
        "product_id": 2184055159,
        "offer_id": "XRZBQ_HK",
        "has_fbo_stocks": false,
        "has_fbs_stocks": true,
        "archived": false,
        "is_discounted": false,
        "quants": []
      }
    ],
    "total": 145,
    "last_id": "WzM5OTI4Mjk4MTAsMzk5MjgyOTgxMF0="
  }
}

注意：这个接口的响应是在 result 下的。

完整代码模板：获取全部 Active Listing

import urllib.request, json, ssl

ctx = ssl.create_default_context()
ctx.check_hostname = False
ctx.verify_mode = ssl.CERT_NONE

CLIENT_ID = "3098640"
API_KEY = "your-api-key-here"

HEADERS = {
    "Content-Type": "application/json",
    "Client-Id": CLIENT_ID,
    "Api-Key": API_KEY
}

def ozon_request(endpoint, body_dict):
    url = f"https://api-seller.ozon.ru{endpoint}"
    data = json.dumps(body_dict).encode()
    req = urllib.request.Request(url, data=data, headers=HEADERS)
    resp = urllib.request.urlopen(req, timeout=20, context=ctx)
    return json.loads(resp.read())

# Step 1: 获取全部产品ID（分页）
all_product_ids = []
last_id = ""
while True:
    result = ozon_request("/v3/product/list", {
        "filter": {"visibility": "ALL"},
        "limit": 100,
        "last_id": last_id
    })
    items = result["result"]["items"]
    all_product_ids.extend([i["product_id"] for i in items])
    last_id = result["result"].get("last_id", "")
    if not last_id or len(items) < 100:
        break

# Step 2: 批量获取产品详情（每批50）
all_products = []
for offset in range(0, len(all_product_ids), 50):
    batch = all_product_ids[offset:offset+50]
    detail = ozon_request("/v3/product/info/list", {
        "product_id": batch
    })
    # ⚠️ 注意：items 在顶层，不在 result 下！
    all_products.extend(detail.get("items", []))

# Step 3: 筛选 Active
active = [p for p in all_products if not p.get("is_archived", False)]

产品详情关键字段

字段	说明	示例
`id`	产品ID，用于构建前台URL	2184055159
`name`	产品名称（俄语）	"закладки"
`offer_id`	卖家自定义SKU	"XRZBQ_HK"
`price`	当前售价	"7.28"
`old_price`	划线价	"15.61"
`currency_code`	货币	"CNY"
`is_archived`	是否归档	false
`sources[].sku`	Ozon SKU	2449791222
`sources[].source`	发货方式	"sds"
`sources[].shipment_type`	配送类型	"SHIPMENT_TYPE_GENERAL"
`stocks.has_stock`	是否有库存	true
`stocks.stocks[].source`	库存来源	"fbs" / "fbo"
`commissions`	佣金信息	含 FBO/FBS/RFBS/FBP

Ozon 前台 URL

https://www.ozon.ru/product/{product_id}

注意：从中国直接访问 ozon.ru 会被地域封锁（307重定向），需要俄罗斯代理或VPN。

filter.visibility 选项

值	说明
`ALL`	全部产品
`VISIBLE`	仅可见（有库存+有价格）
`IN_SALE`	在售
`NOT_SALE`	未在售

依赖

无额外依赖，使用 Python 标准库 urllib + json + ssl 即可。不需要 requests 或其他第三方库。

产品导入 (Product Import) — 已实测

✅ 可用的导入相关端点

端点	用途	备注
`POST /v3/product/import`	创建产品	✅ 唯一可用的import端点
`POST /v1/product/import/info`	查询导入状态+审核结果	返回validation和moderation状态
`POST /v1/product/import/prices`	设置产品价格	⚠️ 必须指定 `currency_code: "CNY"`
`POST /v1/product/archive`	归档产品	传 `{"product_id": [123]}`
`POST /v3/product/info/list`	批量获取产品详情	✅ 含分类和属性信息

❌ 废弃/404 的导入相关端点

端点	状态
`POST /v1/product/import`	404
`POST /v2/product/import`	404
`POST /v2/products/stocks`	404（stock无法通过API设置）
`POST /v1/product/update/stocks`	404
所有 `/v*/category/tree`	404
所有 `/v*/category/search`	404
所有 `/v*/category/attribute`	404
所有 `/v*/product/classify`	404
所有 `/v*/category/suggest`	404

陷阱4：分类必须用 description_category_id + type_id

# ❌ 错误 — 使用 category_id
{"category_id": 12345}

# ✅ 正确 — 使用 description_category_id + type_id
{"description_category_id": 17028733, "type_id": 95421}

category_id 字段会报 "TypeId must be greater than 0"。必须用 description_category_id + type_id 组合。

获取分类的方法：从现有已审核通过的产品中提取（/v3/product/info/list 返回 description_category_id 和 type_id）。

陷阱5：属性格式必须用 id（不是 attribute_id）

# ❌ 错误 — 使用 attribute_id
{"complex_id": 0, "attribute_id": 9048, "values": [{"value": "text"}]}

# ✅ 正确 — 使用 id
{"complex_id": 0, "id": 9048, "values": [{"value": "text"}]}

陷阱6：字典属性需要 dict_id

某些属性（如 attr 9163 "Пол"/性别）是字典类型，需要传 dict_id 和 value：

# ❌ 错误 — 只传 value 字符串
{"id": 9163, "values": [{"value": "унисекс"}]}

# ✅ 正确 — 传 dict_id + value
{"id": 9163, "values": [{"dict_id": 1, "value": "унисекс"}]}

但问题是：无法通过API查询字典值列表（所有attribute端点都404）。只能从已有产品的属性中反推，或试错。

陷阱7：价格API必须指定货币

# ❌ 错误 — 不指定货币或用 RUB
{"prices": [{"offer_id": "SKU1", "price": "5.99"}]}
# 报错："Неверно указана валюта"（货币指定错误）

# ✅ 正确 — 指定 CNY
{"prices": [{"offer_id": "SKU1", "price": "5.99", "old_price": "9.99", "currency_code": "CNY"}]}

陷阱8：审核(Moderation)会检查图片与分类匹配

最重要的坑！ 即使 validation: success，Ozon 的人工审核仍可能 declined 产品。

常见拒因：

"Фото товара не соответствует его типу" — 产品图片与分类类型不匹配
"Необходимо изменить тип" — 需要更改类型

这意味着：选错分类的产品100%会被审核拒绝，即使所有属性都填对了。必须找到与产品图片内容匹配的分类。

陷阱9：Stock 无法通过 API 设置

/v2/products/stocks 和所有 stock 相关端点均返回 404。库存可能需要在 Ozon Seller 后台手动设置，或通过 FBS/FBO 仓库管理。

完整产品导入代码模板

import requests
from urllib3.exceptions import InsecureRequestWarning
requests.packages.urllib3.disable_warnings(InsecureRequestWarning)

OZON_H = {
    "Client-Id": "3103005",
    "Api-Key": "your-api-key",
    "Content-Type": "application/json"
}

# Step 1: Import product
import_payload = {
    "items": [{
        "name": "Солнцезащитные рукава для спорта",
        "offer_id": "SUNSLV668",
        "description": "Описание товара",
        "description_category_id": 17028733,  # ⚠️ 不是 category_id
        "type_id": 95421,
        "images": ["https://example.com/image.jpg"],
        "attributes": [
            {"complex_id": 0, "id": 9048, "values": [{"value": "текст"}]},  # ⚠️ 用 id 不是 attribute_id
        ],
        "vat": "0"
    }]
}

r = requests.post("https://api-seller.ozon.ru/v3/product/import",
                   headers=OZON_H, json=import_payload, timeout=15, verify=False)
result = r.json()
# result.result[0].product_id — 新产品ID
# result.result[0].errors — 导入错误列表

# Step 2: Check import status (repeat until status != "pending")
import time
task_id = result["result"][0]["task_id"]
for _ in range(20):
    r = requests.post("https://api-seller.ozon.ru/v1/product/import/info",
                      headers=OZON_H, json={"task_id": task_id}, timeout=15, verify=False)
    status = r.json()["result"]["items"][0]["status"]
    if status != "pending":
        break
    time.sleep(3)

# Step 3: Set price
r = requests.post("https://api-seller.ozon.ru/v1/product/import/prices",
    headers=OZON_H,
    json={"prices": [{
        "offer_id": "SUNSLV668",
        "price": "5.99",
        "old_price": "9.99",
        "currency_code": "CNY"  # ⚠️ 必须指定！
    }]},
    timeout=15, verify=False)

# Step 4: Check moderation result
product_id = result["result"][0]["product_id"]
r = requests.post("https://api-seller.ozon.ru/v3/product/info/list",
    headers=OZON_H,
    json={"product_id": [product_id]},
    timeout=15, verify=False)
product = r.json()["items"][0]
# product.status — "Не продается" = not for sale (declined)
# moderation — "declined" = 审核被拒

已知分类统计（从现有产品提取）

description_category_id	type_id	名称	approved数	备注
17028733	95421	Декор/装饰品	35	通过率高但分类要匹配
17027904	93338	运动配件A	19	需性别属性(dict_id)
17027904	970575517	运动配件B	12	需性别属性(dict_id)
17027929	592744673	Ледоступы/冰爪	-	❌ 防晒袖被declined
17027904	93866	Солнцезащитные очки/太阳眼镜	-	运动防护类，可能适合防晒用品
41777465	93258	Солнцезащитная шляпа/太阳帽	-	❌ 4个必填字典属性，无法通过API填写

找正确分类的方法

从Ozon前台搜索：用Jina Reader抓取 ozon.ru/search/?text=关键词，找竞品的分类
从现有产品统计：用 /v3/product/info/list 获取所有产品，按 description_category_id 分组统计approved率
AtomK前端编辑器：通过 atomlisting.com/editor/:id 选择Ozon平台，AI可能推荐正确分类
多分类并行测试：用同一产品数据同时提交到3-4个候选分类，看哪个validation先通过且无缺失属性

审核(Moderation)被拒的实战经验

即使 validation: success，审核仍可能 declined！ Validation 只检查格式，审核检查内容。

实测被拒记录：

分类 17028733/95421（装饰品）→ "Необходимо изменить тип"（改类型）
分类 17027929/592744673（冰爪）→ "Фото товара не соответствует его типу"（照片与类型不匹配）
分类 41777465/93258（太阳帽）→ 4个必填字典属性无法填写，validation都无法通过

结论：分类名称必须与产品图片内容语义匹配。 Ozon审核员是真人，会看图片判断分类是否正确。"防晒袖"放在"冰爪"分类下100%被拒。

字典属性(dict_id)暴力破解法

当无法通过API查询字典值时（所有 /v*/category/attribute 端点404），可以暴力枚举 dict_id：

# 试错法找 dict_id — 从1开始递增
for dict_id in range(1, 200):
    test_attrs = [{"complex_id": 0, "id": 9163, "values": [{"dict_id": dict_id, "value": "унисекс"}]}]
    # 提交到 /v3/product/import，检查返回错误
    # 如果错误从 "attribute 9163 is missing" 变成别的，说明 dict_id 正确

实测结果（分类 17027904/970575517）：

dict_id=1 → 通过import检查，但后续验证报错（不适用于此分类）
dict_id=49 → 通过import检查，但验证仍报错
不同分类的字典值不同，一个分类下有效的dict_id在另一个分类下可能无效

offer_id 长度限制

# ❌ 错误 — offer_id 超过50字符
{"offer_id": "SUNSLV668G929X_17027904_970575517"}
# 报错：offer_id_invalid

# ✅ 正确 — offer_id 保持在50字符以内
{"offer_id": "SUNSLV668"}

产品生命周期状态流转

import → pending → validation:success/error → moderate:in_process → moderate:approved/declined
                                                    ↓
                                              如果approved → 需要stock+price → 在售
                                              如果declined → 必须改分类重新import（无法修改已declined产品的分类）

已declined的产品只能归档后重新导入到新分类。 无法修改已提交产品的分类。每次重新导入会生成新的 product_id。

归档大量测试产品的快捷方法

# 批量归档
requests.post("https://api-seller.ozon.ru/v1/product/archive",
    headers=OZON_H,
    json={"product_id": [4575426716, 4575556247, 4575793963, ...]},
    timeout=15)

v3/product/import/info 返回结构

{
  "result": {
    "items": [{
      "product_id": 4576116662,
      "status": "imported",     // pending / imported / failed
      "errors": [],
      "offer_id": "SUNSLV668"
    }],
    "task_id": 12345678
  }
}

注意：task_id 在 import 返回，用于查询状态。但也可以用 product_id 通过 /v3/product/info/list 查询最终状态。

依赖

无额外依赖，使用 Python requests 即可（标准库 urllib 也可）。

16 KiB Raw Blame History Unescape Escape