Настройка CSV-импорта и экспорта 1С-Битрикс
Стандартный CSV-импорт в 1С-Битрикс ломается на трёх вещах: неправильная кодировка, несовпадение разделителей и отсутствие маппинга свойств. Менеджер загружает файл, получает «Импорт завершён, обработано 0 элементов» — и пишет в поддержку. Разберём, как настроить CSV-обмен так, чтобы он работал предсказуемо.
Механика CSV-импорта в каталоге
Модуль catalog содержит встроенный обработчик CSV — класс \Bitrix\Catalog\CsvImport. Импорт доступен через административный интерфейс: Магазин → Настройки → Импорт CSV. Но важно понимать, что происходит под капотом.
Битрикс читает файл построчно, разбивая по разделителю (по умолчанию точка с запятой). Первая строка может быть заголовком — если включена опция «Первая строка содержит имена полей». Далее каждая строка маппится на поля инфоблока: NAME, XML_ID, DETAIL_TEXT, свойства вида PROPERTY_ARTICLE, цены CATALOG_PRICE_1.
Критически важные настройки:
- Кодировка файла — Битрикс ожидает UTF-8. Если файл в Windows-1251 (типично для выгрузок из 1С), нужно включить перекодировку в настройках импорта или конвертировать файл заранее.
- Разделитель полей — точка с запятой, запятая или табуляция. Если в данных встречаются точки с запятой (описания товаров), используйте табуляцию.
- XML_ID — уникальный идентификатор элемента. Без него импорт создаёт дубли при каждом запуске вместо обновления существующих записей.
Маппинг полей и свойств
Самая частая ошибка — несовпадение заголовков в CSV с кодами свойств инфоблока. Битрикс ищет точное соответствие: если свойство называется BRAND, а в CSV заголовок brand — маппинг не сработает.
Для свойств типа «список» в CSV нужно указывать значение, а не XML_ID варианта. Битрикс попытается найти совпадение по значению и привязать элемент. Если значение не найдено — свойство останется пустым без какой-либо ошибки в логе.
Свойства типа «привязка к элементу» требуют передачи ID связанного элемента или его XML_ID (при включённой опции поиска по XML_ID).
CSV-экспорт
Экспорт настраивается в Магазин → Экспорт данных. Профиль экспорта сохраняется в таблице b_catalog_export и может запускаться по cron через агент \Bitrix\Catalog\CatalogExportAgent::exportCsv.
При экспорте больших каталогов (свыше 50 000 товаров) стандартный механизм работает пошагово — по 500 элементов за итерацию. Размер шага задаётся в настройках профиля. Если экспорт обрывается на середине — увеличьте max_execution_time в PHP или уменьшите размер шага.
Формат выгрузки фиксирован: UTF-8, разделитель из настроек профиля. Для интеграции с внешними системами, ожидающими Windows-1251, добавьте пост-обработку через iconv в cron-скрипте.
Автоматизация через cron
Ручной импорт через админку допустим для разовых загрузок. Для регулярного обновления (ежедневная синхронизация остатков, цен) используйте cron-запуск:
/usr/bin/php -f /home/bitrix/www/bitrix/modules/catalog/load/csv_run.php
Параметры профиля импорта передаются через ID сохранённого профиля. Профиль создаётся в админке, тестируется вручную, затем его ID подставляется в cron.
| Масштаб каталога | Время импорта | Рекомендация |
|---|---|---|
| До 5 000 товаров | 1–3 мин | Стандартный импорт через админку |
| 5 000–50 000 | 5–30 мин | Cron + пошаговый режим |
| Свыше 50 000 | 30+ мин | Cron + прямой SQL-импорт в обход API |
Типичные грабли
-
Дубли товаров — всегда заполняйте
XML_IDи включайте поиск по нему. Без этого каждый запуск импорта создаст новые элементы. -
Потерянные изображения — CSV-импорт не поддерживает загрузку файлов. Для картинок используйте путь к файлу на сервере в колонке
DETAIL_PICTURE— Битрикс подхватит файл по абсолютному пути. -
Сброс SEO-полей — если в CSV нет колонок
META_TITLE,META_DESCRIPTION, импорт может обнулить их при обновлении. Включите опцию «Не обновлять пустые поля».