Магнит Маркет через API и MCP: 36 методов, бывший KazanExpress и барьер без единой траты

Обзор

«Магнит Маркет» — маркетплейс сети «Магнит». Для тех, кто продавал на нём раньше, площадка знакома под другим именем: до покупки «Магнитом» это был KazanExpress. Имя сменилось, а API продавца остался тем же контуром — тем же жизненным циклом FBS-заказа (Fulfillment by Seller): собрать заказ → разбить на посылки → промаркировать → отгрузить.

У площадки нет публичного портала документации в духе docs.ozon.ru — за подробностями API официально отправляют к менеджеру. Но техническое руководство продавца называет вторую, машиночитаемую дорогу: magnit-tech (официальный аккаунт «Магнита» на GitHub) публикует Redoc-страницу с полной спецификацией, а рядом, в том же репозитории — сам файл swagger.yaml, который эта страница показывает. Тот случай, когда «спросите менеджера» и «вот OpenAPI 3.0.3 с точным списком полей» относятся к одному и тому же API: просто вторую дорогу выбирают реже.

Mira подключает Seller API «Магнит Маркета» целиком — 36 операций в семи разделах — и отдаёт его в Claude через MCP.

Что доступно продавцу

Доступ — один ключ, без похода к нам за авторизацией

Ни OAuth, ни обмен пары ключей на токен: продавец выпускает api_key сам, в личном кабинете, и этот ключ идёт заголовком X-Api-Key на каждый запрос — принят или отвергнут, третьего не дано. Ровно тот же класс доступа, что у Wildberries и MPStats, и он на порядок проще, чем у Авито или Ozon Performance: там пара client_id/client_secret сначала обменивается на временный токен отдельным запросом. Здесь обменивать нечего — заявок на подключение ждать тоже не нужно.

Отказ — две формы конверта, одно общее поле

У площадки не один формат ошибки на весь API, а два, и они привязаны к разделам. «Задания на сборку» и «Отгрузка посылок» отвечают простым массивом:

{"errors": [{"message": "Задание уже собрано"}]}

«Товары», «Цены», «Остатки», «Категории» и «Магазины» — тем же массивом, но с более богатым элементом и дополнительным полем на верхнем уровне:

{
  "error": "null",
  "errors": [{"code": "VALIDATION", "message": "Категория не найдена", "detailMessage": "..."}]
}

Общее в обеих формах — errors[].message. Разбор ошибок в коннекторе Mira не различает, из какого раздела пришёл ответ: берёт message из массива, если он есть, и только при пустом массиве откатывается на верхнее поле error. Это сверено по всем 36 путям официальной спецификации — не по паре примеров, которые могли бы ввести в заблуждение насчёт формы, общей для всего API.

Барьер записи — 20 из 36, и ни одной траты

20 из 36 операций меняют данные площадки: отмена задания на сборку, разбиение на посылки, маркировка, создание и отмена посылки, шаги отгрузки, создание и правка СКУ, обновление цены и остатков, создание виртуального склада. Все они требуют у источника разрешения на запись — то же правило, что у остальных коннекторов Mira, выведенное из таблицы вызовов программно, а не отдельным списком, который может с ней разойтись.

Необычно другое: в этом барьере нет ни одного тратящего действия. У Ozon Performance из 15 меняющих 8 списывают деньги или запускают показы — это рекламный кабинет, там есть что тратить. У «Магнит Маркета» рекламы и платного продвижения в API нет вовсе: спецификация не называет ни кампаний, ни ставок, ни бюджетов. Барьер здесь защищает не от расходов, которых негде взять, а от необратимых и внешне видимых действий — отменённое задание на сборку не восстановить (дословно из спецификации: «Это действие нельзя отменить»), удалённый товар пропадает из каталога, а у виртуального склада в API нет метода удаления вовсе — создание становится частью схемы продавца навсегда.

Файлы внутри JSON — этикетки и документы отгрузки

Два метода возвращают не структурированные данные, а файл: этикетки для посылок и документы по отгрузке (акты, лист отгрузки) приходят PDF-ом, закодированным в поле file_content — иногда десятками тысяч символов base64. Содержимое такого файла в переписку с моделью не переносится (тот же приём, что у записи разговора Авито и файла отчёта Ozon Performance) — инструмент возвращает размер и явную пометку, что содержимое осталось за пределами канала, а не молча обрезает ответ.

Живая проверка

Ключей от боевого кабинета «Магнит Маркета» нет — раздел появится, когда продавец выпустит api_key в личном кабинете. Разбор адреса и тела, две формы отказа, барьер записи (проверен мутацией: убранная пометка «меняет» красит тест) и работа с файловым полем проверены перехватом на транспорте — против собственного HTTP-сервера в тестах, а не против b2b-api.magnit.ru.