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

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

Назначение

Импорт позволяет массово создавать и обновлять товары на основе данных из CSV-файла. Поддерживается:

• Автоматическое определение кодировки (UTF-8, Windows-1251, KOI8-R)
• Визуальное сопоставление колонок с полями товара
• Обновление существующих товаров по ключевому полю
• Импорт TV-полей и опций товаров
• Загрузка изображений в галерею

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

Шаг 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 — ID ресурса

Шаг 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	Размер
remains	Остаток
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
• Или убедитесь, что определённая кодировка соответствует файлу

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

Проверьте:

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

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

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 — после завершения импорта