Утилиты: Импорт

Пошаговый мастер импорта товаров из CSV.

Назначение

Массово создаёте и обновляете товары из CSV:

• Автоопределение кодировки (UTF-8, Windows-1251, KOI8-R)
• Сопоставление колонок с полями товара
• Обновление по ключевому полю
• TV, опции (option_*), изображения в галерею
• Активные дополнительные поля (msExtraField) для msProduct / msProductData

Пошаговый процесс

Шаг 1: Загрузка файла

Загрузка файла:

• Перетащите CSV-файл в область загрузки или кликните для выбора
• Поддерживаются только файлы с расширением .csv
• Максимальный размер зависит от настроек сервера

Настройки:

Параметр	Описание	По умолчанию
Разделитель	Символ-разделитель колонок	;
Пропустить заголовок	Первая строка = названия колонок	Да

Разделители: ; (точка с запятой, рекомендуем), , (запятая), Tab.

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

Кодировка

Файлы в кодировке Windows-1251 автоматически конвертируются в UTF-8 при обработке.

Шаг 2: Сопоставление полей

На этом шаге нужно указать, какому полю товара соответствует каждая колонка CSV.

Обязательные поля: pagetitle (название), parent (ID категории).

Таблица сопоставления:

Колонка CSV	→	Поле товара	Превью
A: "Название"	→	pagetitle	iPhone 15
B: "Категория"	→	parent	5
C: "Цена"	→	price	99990

Автоматическое сопоставление

Система автоматически сопоставляет колонки по названиям заголовков. Например, колонка "name" сопоставится с полем pagetitle.

Настройки обновления:

Параметр	Описание
Обновлять существующие	Если найден товар по ключу, обновить
Ключ для поиска	Поле для поиска дубликатов

Ключи поиска: article (лучше), pagetitle, id.

Дополнительные поля и Object Extension

Список колонок для маппинга собирает GET /api/mgr/import/fields:

1. Статический каталог config/import-fields.php (ресурс, msProductData, опции).
2. Активные записи msExtraField для моделей msProduct и msProductData, у которых колонка уже есть в БД (column_exists).

Тип виджета ms3-repeater в импорт не попадает: JSON-строки репитера через CSV не маппятся. Простые extra fields (varchar, int, decimal, text, …) и key-value (если колонка есть) выбираются в UI как обычные поля товара.

Зарезервированные имена из статического каталога нельзя перекрыть ключом extra field.

Опции по-прежнему задают префиксом option_ в CSV или явным маппингом на ключ опции.

Шаг 3: Импорт

Сводка перед запуском:

• Имя файла
• Количество строк
• Количество сопоставленных полей

Режимы импорта:

Режим	Описание
Синхронный	Импорт идёт сразу, вы ждёте ответ
Асинхронный	Задача уходит в Scheduler (большие файлы)

Большие файлы

Для файлов более 300 строк рекомендуется использовать асинхронный режим через Scheduler.

Режим отладки:

• Обрабатывает только первую строку
• Полезен для проверки корректности сопоставления

Результаты импорта:

Импорт завершён!
- Всего обработано: 150
- Создано: 120
- Обновлено: 25
- Ошибок: 3
- Пропущено: 2

Доступные поля

Основные поля ресурса

Поле	Описание
pagetitle	Название товара (обязательно)
longtitle	Расширенный заголовок
description	Описание (meta)
introtext	Вводный текст
content	Основной контент
alias	URL-псевдоним
parent	ID родительской категории (обязательно)
template	ID шаблона
published	Опубликован (0/1)
deleted	Удалён (0/1)
hidemenu	Скрыть из меню (0/1)

Поля товара (msProductData)

Поле	Описание
article	Артикул
price	Цена
old_price	Старая цена
weight	Вес
color	Цвет
size	Размер
stock	Остаток (remains — alias в CSV)
vendor	Производитель (имя или ID)
made_in	Страна производства
new	Новинка (0/1)
popular	Популярный (0/1)
favorite	Избранный (0/1)

Специальные поля

Поле	Описание
gallery	Путь к изображению (относительно корня)
tv.{name}	TV-поле по имени (например, tv.brand)
option.{key}	Опция товара (например, option.color)

Формат CSV-файла

Пример структуры

pagetitle;parent;article;price;old_price;vendor;gallery
iPhone 15 Pro;5;IP15PRO;119990;129990;Apple;assets/import/iphone15.jpg
Samsung Galaxy S24;5;SGS24;89990;99990;Samsung;assets/import/galaxy.jpg

Рекомендации

• Используйте точку с запятой (;) как разделитель
• Первая строка: заголовки колонок
• Текст с разделителями заключайте в кавычки
• Для пустых значений оставляйте пустую ячейку
• Для галереи указывайте путь относительно корня сайта

Множественные значения

Для загрузки нескольких изображений добавьте несколько колонок gallery:

pagetitle;gallery;gallery;gallery
Товар;img/1.jpg;img/2.jpg;img/3.jpg

Решение проблем

Ошибка "Обязательное поле не указано"

Причина: Не сопоставлены поля pagetitle или parent.

Решение: Вернитесь на шаг 2 и укажите соответствие для обязательных полей.

Товары не создаются

Возможные причины:

• Указан несуществующий parent (ID категории)
• Нет прав на создание ресурсов
• Ошибки валидации данных

Решение: Включите режим отладки и проверьте логи MODX.

Неправильная кодировка

Симптом: Кириллица отображается некорректно.

Решение:

• Сохраните файл в UTF-8 без BOM
• Или убедитесь, что определённая кодировка соответствует файлу

Изображения не загружаются

Проверьте:

• Файлы существуют по указанному пути
• Путь указан относительно корня сайта
• Права на чтение файлов

При программной загрузке в галерею используйте процессор MiniShop3\Processors\Gallery\Upload (см. API товара).

Программное использование

Процессоры импорта

Процессор	Назначение
MiniShop3\Processors\Utilities\Import\Fields	Список полей для сопоставления
MiniShop3\Processors\Utilities\Import\Upload	Загрузка CSV
MiniShop3\Processors\Utilities\Import\Preview	Предпросмотр
MiniShop3\Processors\Utilities\Import\Import	Запуск импорта
MiniShop3\Processors\Utilities\Import\Progress	Прогресс

API Endpoint

POST /api/mgr/import/start

Параметры:

{
  "importfile": "assets/import/products.csv",
  "mapping": "{\"0\":\"pagetitle\",\"1\":\"parent\",\"2\":\"price\"}",
  "delimiter": ";",
  "skip_header": true,
  "update": true,
  "key": "article",
  "scheduler": false,
  "debug": false
}

События импорта

Для расширения функциональности используйте события импорта:

• msOnBeforeImport: перед стартом
• msOnImportRow: на каждой строке
• msOnAfterImport: после завершения