Импорт из Excel

Массовая загрузка продуктов из файла .xlsx вместо ручного создания карточек.

Импорт всегда выполняется в рамках одной категории: её атрибуты задают, какие колонки файла можно сопоставить. Пользователи, группы и эксперты этим механизмом не загружаются — для них используются методы users и groups.

Порядок обмена

Импорт устроен как сессия: файл загружается, схема сопоставления уточняется, результат проверяется и только затем записывается в каталог.

Шаг	Метод	Что происходит
1	POST /api/v1/categories/{id}/imports/xlsx/schema	Загрузка файла и получение схемы импорта
2	PATCH /api/v1/imports/{import_session_id}	Уточнение сопоставления колонок с атрибутами
3	GET /api/v1/imports/{import_session_id}/preview	Предпросмотр результата до записи
4	POST /api/v1/imports/{import_session_id}	Запуск импорта

Состояние сессии доступно методом GET /api/v1/imports/{import_session_id}, список сессий — GET /api/v1/imports.

Без этого импорт не запустится

В загружаемом файле Excel обязательно должна быть колонка с названием продукта, и на шаге сопоставления её нужно явно пометить как название.

Пока такая колонка не помечена, запуск импорта (шаг 4) вернёт ошибку.

Сопоставление колонок

Схема, полученная на первом шаге, содержит колонки файла и предложенные соответствия атрибутам категории. Часть соответствий определяется автоматически по названию колонки, остальные уточняются на шаге 2.

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

Предпросмотр

Предпросмотр возвращает результат разбора до записи: какие строки будут созданы, какие отклонены и почему.

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

Обработка повторов

Ситуация	Поведение
Совпадают название и все остальные данные	Строка считается полным дубликатом и не импортируется
Совпадает название, данные различаются	Строка обрабатывается как отдельная запись

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

Частые ошибки

• Не выбрана категория — импорт выполняется только в конкретную категорию.
• Не помечена колонка с названием — запуск недоступен.
• Смена категории после загрузки — файл и результаты сопоставления сбрасываются, шаги 1–3 выполняются заново.
• Неверный формат файла — принимается .xlsx.

Права

Для импорта нужны разрешения «Импорт из файла» и «Создание» в группе прав «Продукты» — см. Роли.

Каждый импорт фиксируется в журнале действий в сущности «Импорт».