Синхронизация

Профиль описывает один источник и направление: загрузка на сайт, выгрузка с сайта или обмен в обе стороны. Профилей может быть несколько, например прайс поставщика по API и остатки из Google Таблицы.

Источники

Источник	Что настраивается
CSV	Загрузка файла или ссылка. Разделитель и кодировку (UTF-8, Windows-1251) msCatalyst определяет сам.
Excel (XLSX)	Загрузка файла или ссылка, лист по названию или номеру. Файл читается построчно, без сторонних библиотек.
API (JSON или XML)	Адрес, метод, заголовки, тело запроса, авторизация Bearer, Basic или ключом. Путь к списку товаров (data.items). Постраничность по номеру страницы, смещению, курсору или ссылке на следующую страницу.
Google Таблицы	Ссылка на таблицу или её ID. Для чтения открытой таблицы хватает API-ключа. Для записи нужен ключ сервисного аккаунта (JSON), которому вы дали доступ к таблице. Ключ хранится на сервере и в ответах админки не показывается.
1С (CommerceML 2)	Логин и пароль для 1С, тип цены, соответствие статусов заказов ({"Отгружен": 3}).

Адрес для обмена с 1С:

https://site.ru/assets/components/mscatalyst/1c.php?profile=ID

Профиль с выгрузкой получает адрес фида:

https://site.ru/assets/components/mscatalyst/feed.php?profile=ID&token=...&format=csv

Форматы фида: csv, xlsx, json, xml. Фид отдаёт товары раздела профиля. Модификации идут отдельными строками, если включить это в профиле. Ответ кэшируется на время из настройки профиля «Кэш фида».

Мастер настройки

1. Источник. Тип, направление, доступ, расписание в минутах (0 означает запуск вручную) и адреса для писем, если запуск остановился.
2. Поля. msCatalyst читает образец и показывает все поля источника с типом, примерами, долей пустых и числом уникальных значений. Он предлагает поле-ключ и находит модификации: общий артикул родителя, колонки характеристик или вложенные предложения. Здесь же задаётся корневой каталог: новые категории msCatalyst создаёт внутри него. Для каждого поля предлагается пара на сайте с уверенностью в процентах. Если пары нет, можно создать опцию: при записи msCatalyst привяжет её к категориям товаров.
3. Сопоставление. Категории, производители, опции и значения источника стоят рядом с сайтом: найденные, новые, неоднозначные. Похожие значения встают в пару (Чёрн. и «Чёрный»), неоднозначные вы выбираете вручную.
4. Утверждение. Правила записи: что делать с пропавшими товарами, пороги предохранителей, какие изменения структуры принимать без остановки, как искать товары на сайте. Схема сохраняется версией.
5. План и запуск. Пробный прогон показывает, сколько товаров msCatalyst создаст, обновит и снимет с публикации, и каждое поле в виде «было → станет». Запись идёт только после вашего подтверждения.

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

Правила преобразования

trim, strip_tags, replace, split, join, first, number, bool, markup, multiply, round, default, template, lower, ucfirst.

Флажок «Ведёт сайт» заполняет поле только у новых товаров. Правки менеджера на сайте импорт не перезаписывает.

Ключ и пустые ячейки

Ключом может быть артикул, любое поле товара или ресурса, опция, TV или ID ресурса. Товар ищется по ключу, даже если связи профиля ещё нет. Поэтому первый импорт по существующему каталогу находит товары, а не создаёт копии.

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

Предохранители и пропавшие товары

В профиле задаются три порога. Запуск останавливается и ждёт подтверждения, если:

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

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

Модификации, категории и картинки

Модификации msCatalyst пишет в msOptionsPrice2 на MODX 2 и в ms3Variants на MODX 3. Недостающие категории по пути «Обувь/Кроссовки», производителей и опции он создаёт сам. Разделители /, >, \ и » равнозначны, регистр букв при поиске категории не важен.

Картинки скачиваются в папку из настройки mscatalyst_sync_images_path. В ячейке может быть:

• полная ссылка https://cdn.ru/1.jpg или ссылка без протокола //cdn.ru/1.jpg;
• относительный путь photos/1.jpg или /photos/1.jpg. Он считается от поля профиля «Адрес картинок». Там можно указать ссылку (https://supplier.ru/images/) или папку на сайте (assets/import/). Если поле пустое, путь считается от адреса источника.

Пути с .. и другие схемы (file:, php:) msCatalyst не принимает. Файл проверяется по сигнатуре: сохраняются JPEG, PNG, GIF, WebP и AVIF. HTML-страница вместо картинки и SVG отклоняются. Уже загруженные ссылки при повторном импорте не скачиваются. Та же картинка под новым адресом второй раз в галерею не попадает. Если картинка не скачалась, запуск записывает ошибку с причиной и адресом, а следующий запуск пробует её снова.

Переводы

Синхронизация пишет переводы Localizator и связанные ресурсы Babel, см. Мультиязычность.

Откат и история

Каждый запуск хранит прежние значения полей. Кнопка «Откатить» возвращает цены и поля, а созданные запуском товары, категории, производителей и опции удаляет. В истории видно, какой профиль, когда и что поменял.

Расписание

Запуски по расписанию и продолжение незаконченных запусков выполняет сниппет msCatalystSync из cron или планировщика.