Единый каталог

Инструкция для разработчика по синхронизации номенклатуры для Maxma API

Терминология (важное примечание)

Для избежания путаницы в терминах, используемых в интеграции:

АРТИКУЛ товара в рамках Maxma передается в поле skuID товара в рамках Maxma передается в поле externalIdВ рамках 1С ID товара имеет значение GUID = externalid

• В API Maxma этот идентификатор передается в поле externalId.
• Это поле является обязательным для сопоставления товаров в рамках единого каталога платформы.

• В API Maxma артикул передается в поле sku
• Почему это важно: В личном кабинете Maxma можно настраивать акции и промокоды не только по конкретному товару (через externalId), но и по группе товаров через артикул (например, "Применить скидку на все товары с артикулом ABC-123").
• Статус: В отличие от externalId, синхронизация sku является опциональной, но настоятельно рекомендуемой. Если артикулы будут различаться в разных системах, то настройка акций по артикулам будет невозможна или некорректна.

Выберите главную систему, которая будет источником истины для товарного каталога. В данном контексте — это 1С.
Процесс синхронизации:

• При создании или изменении товара в 1С ему присваивается уникальный externalId и корректный sku.
• Эти данные экспортируются во все остальные интегрированные системы (веб-сайт, другие кассовые приложения).
• Веб-сайт и другие системы не должны генерировать свои собственные ID externalId для товаров, которые пришли из 1С. Они обязаны использовать переданные значения.
• Для sku: Также рекомендуется использовать артикулы из 1С, чтобы обеспечить возможность настройки акций по артикулам.

• При выгрузке товаров на веб-сайт или в другие системы эти поля (ID и АРТИКУЛ) должны быть включены в выгрузку.
• В методах API Maxma гарантируйте, что передаются корректные externalId и sku из 1С.

• При импорте номенклатуры из 1С необходимо сохранять полученные ID и АРТИКУЛ в соответствующих полях товара в базе данных сайта/системы.
• В методах API Maxma гарантируйте, что передаются те самые externalId и sku, которые были получены из 1С.

{
  "calculationQuery": {
    "rows": [
      {
        "product": {
          "externalId": "b27b505e-6a5c-11ec-ab4b-00155d017001", // <-- ID из 1С
          "sku": "00-00000242", // <-- Артикул из 1С
          "title": "Пример товара",
          // ... другие поля ...
        }
      }
    ]
  }
}

{
  "calculationQuery": {
    "rows": [
      {
        "product": {
          "externalId": "b27b505e-6a5c-11ec-ab4b-00155d017001", // <-- Тот же ID, что и в 1С
          "sku": "00-00000242", // <-- Тот же артикул, что и в 1С
          "title": "Пример товара",
          // ... другие поля ...
        }
      }
    ]
  }
}

{
  "calculationQuery": {
    "rows": [
      {
        "product": {
          "externalId": "1C_SYSTEM_ID_12345", // <-- Формат ID товара в 1С
          "sku": "001-242", // <-- Формат артикула в 1С
          "title": "Пример товара",
          // ...
        }
      }
    ]
  }
}

{
  "calculationQuery": {
    "rows": [
      {
        "product": {
          "externalId": "WEBSITE_PRODUCT_ID_67890", // <-- Формат ID товара на сайте
          "sku": "242", // <-- Другой формат артикула на сайте
          "title": "Пример товара",
          // ...
        }
      }
    ]
  }
}

• Акции не работают в одной из интеграци
• Акция "Купи 2 товара 'Пример товара' в одном из каналов - получи скидку" не сработает из-за разных externalId.
• Акция "Скидка 10% на все товары с артикулом 001-242" не сработает на сайте из-за другого формата sku.
• Некорректная аналитика: В отчетах вы не сможете получить общую статистику по продажам конкретного товара, придется формировать 2 разных отчета по одному и тому же товару.
• Невозможность сквозного учета: Нельзя отследить историю покупок конкретного товара конкретным клиентом across всех каналов.

Авторизуйтесь в своем личном кабинете MAXMA.
Перейдите по прямой ссылке:  https://my.maxma.com/#/app/settings/shops 

• Альтернативный способ: В левом боковом меню выберите пункт «Настройки», а затем в открывшемся списке — «Точки продаж».



Add a caption...

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

После выбора точки на экране появится всплывающее окно (поп-ап) с настройками.
В этом окне найдите и выберите пункт «Каталог товаров».
Перед вами откроется выпадающий список, в котором будут все загруженные в систему каталоги. Выберите из списка тот каталог, который соответствует товарам, продающимся в данной точке (или выбранных точках).
После выбора каталога не забудьте нажать кнопку «Сохранить», чтобы применить изменения.



Add a caption...

• Убедитесь, что каждой точке продаж назначен правильный каталог. Это критически важно для корректной работы программы лояльности.





Связка 1С и 1C bitrix

1. Предварительные требования

• Настроен обмен данными между 1С и 1С-Битрикс (выгрузка номенклатуры).
• Настроен обмен данными между 1С и MAXMA через comercML

2. Выгрузка номенклатуры в Maxma

• Откройте план обмена данными с Maxma.
• Настройте выгрузку справочника «Номенклатура»   по инструкции⁠ 
• Запустите полноценную выгрузку номенклатуры.

3. Синхронизация номенклатуры с 1С-Битрикс

• Перейдите в раздел «Магазин» → «Обмен с 1С».
• Настройте профиль обмена для выгрузки товаров:
• Убедитесь, что в карточках товаров в Битрикс передаются внешние ID из 1С.



Add a caption...

4. Активация передачи внешних ID в Maxma

• Перейдите в настройки модуля («Настройки модуля Maxma»).
• Активируйте опцию:«Передавать в операциях внешний ID» (галочка).
• Сохраните изменения.



Add a caption...

5. Проверка работоспособности

• Создайте тестовый заказ в 1С-Битрикс.
• Убедитесь, что в Maxma передаются корректные данные:
• Внешние ID товаров совпадают с выгруженными из 1С.
• Заказ отображается в Maxma с правильными товарными позициями.

6. Возможные проблемы и решения