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

Профиль описывает один источник и направление: загрузка на сайт, выгрузка с сайта или обмен в обе стороны. Профилей может быть несколько, например прайс поставщика по 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 отклоняются. Уже загруженные ссылки при повторном импорте не скачиваются. Та же картинка под новым адресом второй раз в галерею не попадает. Если картинка не скачалась, запуск записывает ошибку с причиной и адресом, а следующий запуск пробует её снова.

Картинку больше 20 МБ msCatalyst не скачивает. За один запуск товар получает не больше 20 новых картинок: остальные догрузит следующий запуск, а в отчёте будет пометка об этом.

Переводы

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

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

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

Запуски старше 90 дней msCatalyst удаляет вместе с журналом изменений. Такой запуск уже нельзя откатить, а его правки пропадают из истории товара. Три последних запуска профиля остаются при любом сроке. Срок задаёт настройка mscatalyst_sync_keep_days. При 0 история хранится без срока, но не больше 1000 запусков на профиль.

Расписание

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

Если файл источника не изменился с последнего успешного запуска, запуск по расписанию останавливается сразу после загрузки файла с пометкой «источник не изменился». Товары он не трогает. Ручной запуск и &profile=ID всегда проходят полностью. Источники API и Google Таблицы проверку не проходят и импортируются каждый раз.

Нагрузка на сервер

• Шаг заканчивается вовремя и посреди пачки товаров, если товары с картинками обрабатываются долго.
• Пока шаг скачивает картинки, он продлевает блокировку запуска, и второй cron не начинает тот же запуск параллельно.
• Если шаг трижды подряд оборвался на сервере (кончилась память или время PHP), запуск получает статус «Ошибка» и письмо уходит на адрес из профиля. Иначе cron повторял бы падающий шаг бесконечно.
• Пауза по заголовку Retry-After от API и Google не превышает 30 секунд.
• Обмен с 1С принимает файл до 2 ГБ, распаковывает из архивов до 4 ГБ и до 100 000 файлов. Размер считается по фактически распакованным данным, а не по заголовку архива.
• Ручной запуск и cron не создадут два запуска одного профиля, даже если их нажали одновременно.