API Ozon Seller: ключ, методы и ошибки
Ozon разводит продавца по двум разным API с разной авторизацией. Seller API отвечает за товары, заказы, цены, финансы и отзывы, Performance API за рекламу. Ниже: где взять ключи для обоих, что внутри каждого раздела и что означают ошибки, на которые уходит больше всего времени.
Как получить доступ
Seller API: Client-Id и Api-Key
Зайдите в кабинет seller.ozon.ru, откройте Настройки, раздел API-ключи. Ozon выдаёт пару: Client-Id (число) и Api-Key. Оба уходят в заголовки одноимённых имён, хост запроса api-seller.ozon.ru.
Performance API: client_id и client_secret
Рекламный кабинет живёт отдельно и авторизуется по OAuth2: пара client_id и client_secret меняется на токен, хост api-performance.ozon.ru. Ключи Seller API там не работают, и наоборот.
Куда положить, чтобы не хранить в открытую
Сервер спросит ключи при первом запуске и положит их в ~/.marketplace-mcp/cabinets.json с правами chmod 600. В репозиторий и в чат они не попадают. Магазинов можно подключить несколько и переключаться между ними прямо из чата.
Карта методов
Таблицы собраны из того же каталога, который грузит сервер, поэтому они не расходятся с кодом. Колонки показывают, как метод классифицирует safety-гейт: перед записью агент предупреждает, перед необратимым действием требует подтверждения. Оговорка про Ozon: он использует POST и для чтения тоже, поэтому класс тут определяется по последнему сегменту пути, а не по HTTP-глаголу. /v1/report/list читает, /v1/report/create пишет.
| Раздел | Методов | Чтение | Запись | Необратимые |
|---|---|---|---|---|
| Заказы FBS и доставка | 112 | 37 | 73 | 2 |
| Заказы FBO и склады | 64 | 37 | 25 | 2 |
| Товары и карточки | 55 | 30 | 24 | 1 |
| Кросс-док FBP | 45 | 15 | 27 | 3 |
| Акции и продвижение | 31 | 9 | 21 | 1 |
| Возвраты и отмены | 30 | 11 | 19 | 0 |
| Отзывы, вопросы и чаты | 27 | 10 | 16 | 1 |
| Финансы и отчёты | 25 | 11 | 14 | 0 |
| Кабинет и служебное | 22 | 12 | 9 | 1 |
| Цены и остатки | 21 | 11 | 10 | 0 |
| Аналитика | 9 | 7 | 2 | 0 |
| Всего | 441 |
| Раздел | Методов | Чтение | Запись | Необратимые |
|---|---|---|---|---|
| Статистика рекламы | 16 | 16 | 0 | 0 |
| Продвижение в поиске | 11 | 4 | 6 | 1 |
| Кампании и объявления | 9 | 4 | 5 | 0 |
| Товары в рекламе | 5 | 2 | 2 | 1 |
| Вендорская реклама | 4 | 4 | 0 | 0 |
| Всего | 45 |
Курированное ядро выверено на живых кабинетах. Остальное импортировано из спецификаций: пути надёжны, HTTP-глаголы не всегда, считайте такие записи картой для разведки. Официальная документация: docs.ozon.ru/api/seller.
Частые ошибки и что они значат
401 или «Client-Id should be positive integer», хотя ключ верный
Первым делом смотрите не переменные окружения, а ~/.marketplace-mcp/cabinets.json: активный кабинет в этом файле имеет приоритет над env и молча затеняет то, что вы экспортировали в терминале.
404 на методе, который точно существует
Ozon дрейфует по версиям, и разные разделы живут на разных: список товаров на v3, атрибуты на v4, цены на v5. При 404 проверяйте версию в пути раньше всего остального.
405 Method Not Allowed
Скорее всего это метод, импортированный из спецификации: путь у таких записей надёжный, а HTTP-глагол не всегда. Живая проба находила методы, помеченные GET, которые на деле POST. Сверьтесь с документацией или вызовите через call_raw.
То же самое одной фразой
Если разбираться с методами руками не хочется, всё перечисленное выше вызывается из чата обычными словами. Проект и есть MCP-сервер: он отдаёт эти методы ИИ-ассистенту как инструменты, а тот подбирает нужный сам.
Скажите так
покажи продажи на Ozon за неделю по дням какие товары с красным индексом цены вытащи отчёт о начислениях за прошлый месяц собери отзывы ниже 4 звёзд и сгруппируй жалобыЧто для этого нужно
Ключи из первого раздела и одна строка установки. Нужен только Ozon: отдельный пакет ozon-mcp-ru, тот же сервер одним маркетплейсом. Нужны все четыре: npx -y marketplaces-mcp-ru или uvx marketplaces-mcp-ru, а в Claude Desktop бандл .mcpb из релизов ставится в один клик.
Частые вопросы
Как получить API-ключ Ozon?
seller.ozon.ru, раздел Настройки, пункт API-ключи. Ozon выдаёт пару Client-Id и Api-Key, оба нужны. Для рекламы ключи берутся отдельно, в Performance API, и авторизация там по OAuth2.
Чем Seller API отличается от Performance API у Ozon?
Это два разных API с разной авторизацией и разными хостами. Seller API (api-seller.ozon.ru) отвечает за товары, заказы, цены, остатки, финансы и отзывы. Performance API (api-performance.ozon.ru) отвечает только за рекламу. Ключи одного в другом не работают.
Почему API Ozon отвечает 404 на существующий метод?
Ozon дрейфует по версиям путей: список товаров на v3, атрибуты на v4, цены на v5. При 404 проверьте версию в пути раньше всего остального.
Сколько методов Ozon поддерживает marketplaces-mcp-ru?
486: 441 метод Seller API и 45 методов Performance API. Каждый со схемой параметров и пометкой чтение, запись или необратимое действие.
Можно поставить только Ozon, без остальных маркетплейсов?
Да, для этого есть отдельный пакет ozon-mcp-ru: он поднимает один сервер Ozon, без остальных площадок. Внутри тот же код и тот же каталог, что в marketplaces-mcp-ru, они приходят зависимостью. Строка установки лежит в его репозитории.
Каталог методов открыт. Берите, форкайте, улучшайте.
Всё это лежит в репозитории под MIT, включая машиночитаемые каталоги, из которых собраны таблицы на этой странице. Нашли неточность в методе, поправьте или заведите issue.