МойСклад - Яндекс Маркет. Руководство по настройке.

Краткий старт. Что нужно настроить для новой API-интеграции.

Шаг 1. Подготовьте товары в источнике.

Сначала выберите склады в МойСклад, выполните первую ручную загрузку товаров и при необходимости настройте источник изображений. Подробности ниже в разделе "Подготовка источника".

Шаг 2. Подключите Яндекс Маркет по API.

Откройте страницу "Яндекс Маркет" -> "Подключение API", сохраните API-Key и дождитесь автоматической загрузки кабинета и рабочих магазинов.

Шаг 3. Добавьте категории.

Создайте одну или несколько категорий через официальное дерево Яндекс Маркета. После сохранения у категории автоматически появятся обязательные системные поля.

Шаг 4. При необходимости настройте правила и автозамены.

Общие правила и автозамены настраиваются на странице "Настройки", а локальные переопределения можно добавить прямо внутри конкретной категории.

Шаг 5. Заполните обязательные поля и нужные характеристики.

На странице "Поля" заполните все обязательные поля, затем добавьте дополнительные характеристики из справочника Яндекс Маркета для выбранной категории.

Шаг 6. Настройте магазины.

На странице "Магазины" включите нужные магазины и выберите, из каких полей брать остатки и цены для каждого магазина.

Шаг 7. Запустите интеграцию и проверьте результат.

На странице "Интеграция" выполните первый запуск вручную. После этого проверьте вкладки "Подготовка", "Остатки", "Товары" и "HTTP-логи".

Шаг 8. Включите расписание только после успешного ручного запуска.

Когда убедитесь, что категории, поля, магазины и статусы настроены корректно, включите расписание на стороне источника. Сохранённый режим синхронизации будет использоваться и для запусков по расписанию.

Подготовка источника

Раздел "Яндекс Маркет"

Подключение API

На странице "Подключение API" вы сохраняете API-Key кабинета Яндекс Маркета. После сохранения ключ скрывается, а кабинет и список магазинов обновляются автоматически при открытии страницы и после повторного сохранения.

Чтобы получить API-Key кабинета Яндекс Маркета, перейдите в личный кабинет на вкладку "Api и модули". И нажмите на "Создать новый токен", как показано ниже.

В открывшемся окне введите название для токена, например "Интеграция из личного кабинета". В параметрах доступа укажите "только выбранные" и выберите доступы: Просмотр товаров и карточек, Просмотр цен, Управление товароми и карточками, Управление ценами. Затем нажмите "Создать". Ниже смотрите пример.

После создания токена, он появится у вас на экране. Скопируйте его.

Поздравляем! Вы успешно получили API-Key. Теперь вставьте в личном кабинете на странице "Подключение API" и сохраните, как было сказано в начале.

В этой странице видно, активно ли подключение, какой кабинет найден, его Business ID, валюту и режим цен. Если Маркет сообщает, что кабинет работает только с общей ценой, это тоже будет показано в карточке кабинета.

Здесь же выбирается режим выгрузки: "Обновлять всё", "Цены и остатки", "Только остатки" или "Только заказы". В режиме "Только заказы" товарная выгрузка, цены и остатки не запускаются, а синхронизация заказов продолжает работать через раздел заказов.

Важно: в текущей интеграции поддерживается один основной API-аккаунт. Дополнительные аккаунты отключены, а магазины без рабочего API в интерфейсе не отображаются.

Категории

Категории в Яндекс Маркете создаются только через официальное дерево Маркета. Внутреннее название категории можно задать любое удобное для себя, но отправка в Маркет идёт по выбранной официальной категории.

После сохранения категории сервис сразу создаёт обязательные системные поля. Если категория была создана давно по старой схеме, достаточно открыть её, выбрать официальный раздел Маркета и сохранить заново, чтобы перейти на актуальный API-сценарий.

Из списка категорий можно перейти к изменению, дублированию или удалению категории через меню действий. При удалении удаляются и её связанные поля, правила и автозамены.

Правила категории

У каждой категории есть собственная вкладка "Правила категории". Эти правила применяются только внутри выбранной категории и помогают отфильтровать товары или преобразовать числовые значения именно для неё.

Здесь удобно собирать отдельные категории на основе пути товара, бренда, сезонности, остатка, цены и любых других полей, которые уже были загружены из источника. Доступны сравнения, поиск по тексту, арифметика и формулы.

Автозамены категории

Автозамены категории работают по тому же принципу, что и общие автозамены, но затрагивают только товары выбранной категории. Это удобно, когда одно и то же поле из источника должно по-разному преобразовываться для разных категорий Маркета.

Например, можно исправить варианты написания бренда, нормализовать материал, сезонность, типоразмер или любые другие текстовые значения перед отправкой в Маркет.

Настройки

Страница "Настройки" теперь содержит только актуальные инструменты для API-интеграции: общие правила, общие автозамены и дубли полей. Настройка заголовка YML/XML больше не нужна и из рабочего сценария убрана.

Общие правила и автозамены применяются ко всем товарам до того, как они попадут в конкретную категорию. Дубли полей помогают использовать одно исходное значение в нескольких сценариях, например отдельно для цены, старой цены, остатков или дополнительных вычислений.

Поля

На странице "Поля" работа идёт отдельно по каждой категории. В начале списка всегда стоят обязательные поля, ниже идут необязательные. Обязательные поля нельзя удалить: их можно только заполнить и при необходимости скорректировать значение.

Для новой API-интеграции обязательно должны быть заполнены поля offerId, name, marketCategoryId, pictures, vendor и description. Поле marketCategoryId сервис получает автоматически из выбранной категории Маркета, а вот offerId должен быть уникальным кодом товара в вашей системе.

Лучше всего использовать для offerId стабильный артикул или код, который не меняется и не повторяется между товарами. На странице список колонок показывает, что поле обязательно, а при открытии редактирования видно описание, параметры API, ограничения и допустимые значения.

Дополнительные характеристики теперь добавляются только из официального API-списка характеристик выбранной категории. Ручной ввод произвольной категории или ручных неофициальных полей больше не используется.

• offerId — уникальный код товара в вашей системе. Именно по нему Маркет связывает карточку, цену и остаток.
• name — название товара для Маркета.
• marketCategoryId — идентификатор официальной категории Маркета. Заполняется автоматически.
• pictures — одна или несколько ссылок на изображения товара.
• vendor — бренд или производитель.
• description — описание товара без рекламных вставок, контактов и лишних ссылок.

Если у вас несколько категорий с похожей структурой, используйте кнопку "Скопировать значения", чтобы быстро перенести заполненные значения из одной категории в другую.

Магазины

Страница "Магазины" показывает только те магазины Яндекс Маркета, у которых API реально доступен. Если магазин нерабочий или Маркет вернул его как недоступный для API, он в актуальном интерфейсе не отображается и не участвует в синхронизации.

Для каждого магазина можно сразу на одной странице:

• включить или выключить участие магазина в синхронизации;
• выбрать поле источника для остатка;
• выбрать поле источника для цены;
• сохранить все настройки одной кнопкой.

Ассортимент и контент товаров отправляются один раз на кабинет, а магазины отличаются остатками и, если кабинет это разрешает, ценами. Поэтому страницу магазинов нужно воспринимать как настройку остатков и цен по магазинам, а не как отдельные категории товаров.

Интеграция

Основная работа с запуском и контролем интеграции происходит на странице "Интеграция". Здесь есть одна основная кнопка "Запустить", текущий статус синхронизации, сводные счётчики по товарам и вкладки для детальной диагностики.

Переключатель режима теперь работает как сохранённый режим аккаунта. Вы выбираете, что запускать: "Обновлять всё", "Цены и остатки", "Только остатки" или "Только заказы". Это значение сохраняется в подключении и потом используется и для запусков по расписанию.

Во время активной синхронизации интерфейс обновляется автоматически, поэтому вручную перезагружать страницу и отдельно нажимать кнопки проверки больше не нужно.

Подготовка

Во вкладке "Подготовка" вы видите товары до отправки в Маркет. Секция разделена на два подтаба: "Подготовлено" и "Ошибки". Количество здесь считается по товарам, а не по отдельным payload-запросам.

В подтабе "Подготовлено" можно найти товар по коду, увидеть, в каких группах и магазинах он участвует, и открыть модальное окно с payload-данными, разбитыми по вкладкам. В подтабе "Ошибки" показаны товары, которые не удалось корректно подготовить, с последней ошибкой и подробностями по каждому случаю.

Эта вкладка нужна, чтобы понять проблемы до отправки: не хватает обязательных полей, у поля невалидное значение, не найден код товара, не собраны данные по цене или остатку.

Остатки

Во вкладке "Остатки" отображается результат проверки остатков после отправки в Маркет. Проверка идёт по связке товар + магазин, поэтому один и тот же товар может появляться здесь в нескольких строках, если он участвует в нескольких магазинах.

В таблице доступны поиск, фильтр по статусу, фильтр по магазину и сортировка без перезагрузки страницы. В модальном окне строки можно увидеть ожидаемый остаток, фактический остаток, время проверки, комментарий и разбивку по складам, которую вернул Маркет.

• Совпало — остаток в Маркете соответствует ожидаемому значению.
• Расхождение — Маркет вернул другое значение остатка.
• Не найдено — Маркет не вернул остаток по товару для этого магазина.
• Ошибка проверки — Маркет вернул ошибку на этапе проверки.
• Ожидает — проверка ещё не завершилась.

Товары

Во вкладке "Товары" показывается уже итоговая реакция Маркета на отправленные товары. Здесь также работают поиск, фильтры по состоянию и магазину, сортировка и открытие подробностей в модальном окне.

В модальном окне можно посмотреть карточку статуса товара, текст ошибок или предупреждений, а также все основные payload-данные: отправленный контент, размещение, цену, остаток и ответы Маркета по товару и цене.

• Опубликовано — по товару нет замечаний.
• Предупреждение — товар обработан, но Маркет вернул предупреждения.
• В обработке — товар ещё не завершил обработку на стороне Маркета.
• Ошибка — Маркет отклонил товар или часть данных по нему.

HTTP-логи

Ниже на странице интеграции доступен блок "Подробные HTTP-логи интеграции". Здесь можно выбрать день, затем конкретный запуск и скачать группу запросов для детального разбора.

Этот раздел особенно полезен, если нужно передать техническую информацию в поддержку или сравнить, что именно было отправлено в Маркет в конкретном запуске.

Раздел "Синхронизация заказов Яндекс Маркета"

В этом подразделе настраивается передача заказов из Яндекс Маркета в МойСклад. Система получает заказы через API Маркета, сохраняет их в личном кабинете, создаёт по ним заказы покупателя в МойСклад и, когда статус подходит для отгрузки, создаёт отгрузки.

Важно: переключатель вверху страницы включает или выключает только автоматический запуск по расписанию. Настройки остаются доступными всегда, а ручной запуск можно выполнить на вкладке "Интеграция" даже при выключенном расписании.

Для работы заказов API-Key Яндекс Маркета должен иметь доступ "Обработка заказов и учёт товаров". Если нужно только видеть заказы без создания документов, подойдёт доступ "Просмотр информации о заказах". Если ключ был создан раньше только для товаров, цен и остатков, создайте новый ключ с правами на заказы и сохраните его на странице "Подключение API".

Переключатель автозапуска по расписанию

Если переключатель включён, синхронизация заказов Яндекс Маркета будет запускаться автоматически вместе с плановым обновлением МойСклад. Если выключен, расписание не будет запускать синхронизацию заказов, но настройки и ручной запуск останутся доступны.

Рекомендуемый порядок: сначала выключите автозапуск, заполните параметры, магазины, склады и статусы, затем выполните ручной запуск и проверьте один-два заказа в МойСклад. После проверки можно включить расписание.

Вкладка "Параметры"

Атрибут с offerId Яндекс Маркета - поле товара, по которому система ищет товар МойСклад для позиции из заказа. Значение выбранного атрибута у товара МойСклад должно совпадать с offerId, который приходит в заказе Яндекс Маркета.

Пример: в заказе пришёл товар с offerId SHINA-001. В МойСклад у нужного товара в выбранном атрибуте тоже должно быть указано SHINA-001. Тогда товар попадёт в заказ покупателя и будет зарезервирован. Если значения не совпадают, заказ сохранится с ошибкой "Не найден товар".

Период, дней - сколько последних дней система будет повторно проверять при обновлении заказов. API Яндекс Маркета ограничивает один запрос периодом до 30 дней, поэтому максимальное значение здесь тоже 30.

Загружать новые заказы - система будет получать новые заказы, которые ещё не были сохранены ранее.

Обновлять заказы за период - система будет повторно проходить по недавним заказам и подтягивать актуальные статусы, подстатусы, даты и изменения состава заказа.

Создавать заказы в МойСклад - если включено, по заказу Маркета будет создан заказ покупателя в МойСклад. Если выключено, заказ будет только загружен и показан в личном кабинете.

Создавать отгрузки в МойСклад - если включено, при подходящем статусе заказа система создаст отгрузку по уже созданному заказу покупателя. Для Яндекс Маркета такими статусами считаются этапы передачи в доставку, выдачи и доставки покупателю.

Вкладка "Магазины и склады"

На этой вкладке выбирается, какие магазины и склады Яндекс Маркета участвуют в синхронизации заказов. Заказы из выключенных строк будут сохранены только после включения соответствующего магазина или склада.

Организация МойСклад - ваша организация, от имени которой будет создан заказ покупателя и отгрузка. Это обязательное поле для включённой строки.

Контрагент МойСклад - покупатель/контрагент, который будет указан в заказе покупателя. Обычно для маркетплейса создают отдельного контрагента, например Яндекс Маркет FBS или Яндекс Маркет.

Если API Маркета не возвращает отдельные склады, система создаёт строку "Все склады магазина". В этом случае настройка применяется ко всем заказам выбранного магазина.

После настройки нажмите "Сохранить магазины и склады". Кнопка есть сверху и снизу таблицы, чтобы длинный список можно было сохранить без лишней прокрутки.

Вкладка "Статусы"

В этой таблице сопоставляются статусы Яндекс Маркета и статусы заказов МойСклад. Когда система создаёт или обновляет заказ в МойСклад, она берёт статус Маркета, ищет выбранное соответствие и ставит нужный статус в документ МойСклад.

Если статус не сопоставлен, заказ сохранится локально, но документ МойСклад не будет создан или обновлён, пока вы не укажете соответствие. Обычно достаточно начать со статусов PROCESSING, DELIVERY, PICKUP, DELIVERED и CANCELLED.

Служебные кнопки

Обновить склады Маркета - загружает актуальные магазины и склады из API Яндекс Маркета. Используйте после изменения магазинов, складов или прав API-Key.

Обновить организации - загружает организации из МойСклад, чтобы они появились в списках выбора.

Обновить контрагентов - загружает контрагентов из МойСклад.

Обновить статусы - загружает статусы заказов покупателя из МойСклад.

Создать организацию и Создать контрагента - быстрые действия, чтобы добавить нужную сущность в МойСклад прямо со страницы настройки синхронизации.

Страница "Интеграция"

На странице интеграции можно запустить синхронизацию вручную, посмотреть текущий статус задачи, количество локально сохранённых, обработанных и проблемных заказов.

Ниже расположен отдельный блок "Подробные HTTP-логи синхронизации заказов". Это не логи товарной интеграции: здесь скачиваются только запросы по заказам Яндекс Маркета, складам и созданию документов в МойСклад.

Страница "Заказы"

На странице заказов отображаются все заказы, полученные из Яндекс Маркета. Поиск работает по ID заказа, внешнему ID, магазину, складу, статусу, названию товара и offerId.

Во вкладке "Поля" можно выбрать, какие колонки показывать в таблице. Из строки заказа можно открыть подробную карточку: в ней видны товары, статусы выгрузки, ссылка на заказ покупателя в МойСклад и отгрузки, если они были созданы.

Наглядный пример работы

Допустим, автозапуск включён, период обновления - 14 дней, атрибут товара - "offerId Маркета", магазин включён, организация - ООО Альфа, контрагент - Яндекс Маркет FBS, статус PROCESSING сопоставлен со статусом МойСклад "Новый Яндекс", а создание заказов и отгрузок включено.

В Яндекс Маркете появляется заказ 100500 на 2 штуки товара с offerId SHINA-001. При запуске система получает заказ, проверяет магазин и склад, находит в МойСклад товар с атрибутом "offerId Маркета" = SHINA-001 и создаёт заказ покупателя YM-100500.

В созданном заказе МойСклад будет организация ООО Альфа, контрагент Яндекс Маркет FBS, товар SHINA-001, количество 2, резерв 2 и статус "Новый Яндекс". Когда Маркет переведёт заказ в статус доставки или выдачи, следующий запуск обновит локальный заказ и создаст отгрузку по заказу покупателя.

Если в МойСклад нет товара с нужным offerId, заказ останется в списке с ошибкой. После того как вы заполните правильный атрибут у товара, следующий запуск попробует обработать заказ снова.

Режим и расписание

Режим синхронизации выбирается на странице "Интеграция" и сохраняется в аккаунте. Это значит, что если вы оставили режим "Только остатки", "Цены и остатки" или "Только заказы", именно он будет использоваться и для следующего запуска по расписанию.

Первая рекомендация всегда одна: сначала выполните ручной запуск, убедитесь, что вкладки "Подготовка", "Остатки" и "Товары" показывают ожидаемый результат, и только после этого включайте расписание.

Само расписание настраивается на стороне МойСклад: "МойСклад" -> "Расписание".

Товары интеграции

В каждом маркетплейсе есть подраздел "Товары". Он показывает результат последней подготовки товаров именно для выбранной площадки: какие товары прошли общие настройки, какие не прошли правила категории, где были выполнены автозамены, формулы, арифметические операции или дублирование полей.

Если товар не попал в выгрузку, в этом разделе будет указана причина: отсутствовало поле, выбранное в правиле, товар не подошёл под условие фильтрации, не удалось заполнить обязательное поле маркетплейса или не получилось собрать данные для отправки. Один проблемный товар не останавливает всю интеграцию: он пропускается, а остальные товары продолжают обрабатываться.

На странице можно переключать статус "Прошёл" / "Не прошёл", этап проверки, категорию и наличие изменений. Поиск работает по названию, коду товара, offer_id и названию категории. Если у маркетплейса подключено несколько аккаунтов, например в Ozon, сверху появится переключатель аккаунта, и результаты разных аккаунтов не смешиваются.

В строке товара есть значок просмотра. Он открывает обычную карточку товара из раздела "Товары", чтобы можно было сразу проверить исходные поля и исправить данные в источнике или настройках маркетплейса.

Частые вопросы

Техподдержка

Если после проверки категорий, полей, магазинов, вкладок интеграции и HTTP-логов вопрос всё ещё остался, перейдите в раздел "Техподдержка" и приложите максимум конкретики: код товара, магазин, вкладку, на которой видна проблема, и время запуска.

Чем точнее будут указаны offerId, магазин и статус из интерфейса, тем быстрее получится проверить конкретный запуск и помочь с проблемой.