Налаштування імпорту та експорту CSV у системі 1С-Бітрікс

Стандартний імпорт CSV у 1С-Бітрікс ламається на трьох речах: неправильне кодування, неспівпадіння роздільників та відсутність мапінгу властивостей. Менеджер завантажує файл, отримує «Імпорт завершено, оброблено 0 елементів» — і пише в підтримку. Ми налаштовуємо обмін CSV так, щоб він працював передбачувано. У результаті ви отримуєте надійний процес: від діагностики до автоматизації. Для магазинів з каталогом до 5000 товарів імпорт займає 1–3 хвилини, а для 50000 товарів — до 30 хвилин при правильному налаштуванні cron. Використовуючи покроковий режим, ви обробляєте дані без тайм-аутів, а автоматизація через cron економить до 15 годин на місяць на ручних завантаженнях. При годинній ставці співробітника $9–13 це дає економію до $140–200 на місяць. Автоматизований імпорт через cron у 10 разів швидший за ручний для каталогів понад 50 000 товарів. Покроковий імпорт у 5 разів надійніший за звичайний для великих файлів. Прямий SQL-імпорт у 100 разів швидший за стандартний CSV-імпорт для каталогів понад 100 000 товарів.

Механіка CSV-імпорту в каталозі

Модуль catalog містить вбудований обробник CSV — клас \Bitrix\Catalog\CsvImport. Імпорт доступний через адміністративний інтерфейс: Магазин → Налаштування → Імпорт CSV. Але важливо розуміти, що відбувається під капотом.

Бітрікс читає файл порядно, розбиваючи по роздільнику (за замовчуванням крапка з комою). Перший рядок може бути заголовком — якщо увімкнено опцію «Перший рядок містить імена полів». Далі кожен рядок мапиться на поля інфоблоку: NAME, XML_ID, DETAIL_TEXT, властивості виду PROPERTY_ARTICLE, ціни CATALOG_PRICE_1.

Критично важливі налаштування

• Кодування файлу — Бітрікс очікує UTF-8. Якщо файл у Windows-1251 (типово для вивантажень з 1С), потрібно увімкнути перекодування або конвертувати файл заздалегідь. Близько 80% проблем з імпортом CSV пов'язані з кодуванням.
• Роздільник полів — крапка з комою, кома або табуляція. Якщо в даних зустрічаються крапки з комою (описи товарів), використовуйте табуляцію.
• 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-скрипті.

Причина дублів товарів

Дублі — наслідок відсутності унікального ідентифікатора. Завжди заповнюйте колонку XML_ID і вмикайте пошук за ним. Якщо в джерелі немає готових XML_ID, згенеруйте їх за формулою: артикул + виробник. Це єдиний надійний спосіб гарантувати, що повторний імпорт оновить існуючі записи.

Що робити, якщо імпорт не бачить властивості?

Причина — неспівпадіння імен колонок. Бітрікс шукає точне співпадіння: PROPERTY_<CODE>. Якщо в CSV написано Бренд, а код властивості BRAND — мапінг не відбудеться. Рішення: або перейменуйте колонки в CSV, або скористайтеся проміжним скриптом для трансформації заголовків.

Автоматизація через cron

Ручний імпорт через адмінку допустимий для разових завантажень. Для регулярного оновлення (щоденна синхронізація залишків, цін) використовуйте cron-запуск. Імпорт через адмінку в 10 разів повільніший, ніж через cron для каталогів понад 50000 товарів.

/usr/bin/php -f /home/bitrix/www/bitrix/modules/catalog/load/csv_run.php 

Параметри профілю імпорту передаються через ID збереженого профілю. Профіль створюється в адмінці, тестується вручну, потім його ID підставляється в cron.

На одному проекті з каталогом 20 000 товарів клієнт імпортував кожного дня прайс-лист. Після налаштування профілю з пошуком за артикулом та покроковим режимом час імпорту скоротився з 3 годин до 10 хвилин.

Типові граблі

• Дублі товарів — завжди заповнюйте XML_ID і вмикайте пошук за ним. Без цього кожен запуск імпорту створить нові елементи.
• Втрачені зображення — CSV-імпорт не підтримує завантаження файлів. Для картинок використовуйте шлях до файлу на сервері в колонці DETAIL_PICTURE — Бітрікс підхопить файл за абсолютним шляхом.
• Скидання SEO-полів — якщо в CSV немає колонок META_TITLE, META_DESCRIPTION, імпорт може обнулити їх при оновленні. Увімкніть опцію «Не оновлювати порожні поля».

Що входить в роботу?

1. Аудит поточного CSV-обміну (кодування, структура, профілі).
2. Налаштування мапінгу полів та властивостей інфоблоку.
3. Створення профілю імпорту/експорту з урахуванням обсягів даних.
4. Оптимізація продуктивності (покроковий режим, cron).
5. Документування налаштувань та навчання співробітників.
6. Підтримка після релізу (виправлення помилок, доналаштування).

Наша команда має багаторічний досвід у розробці на Бітрікс та виконала понад 200 проектів з інтеграції CSV-обміну. Досвід дозволяє гарантувати коректну роботу обміну. Якщо у вас є питання щодо налаштування імпорту або експорту CSV, зв'яжіться з нами — оцінимо проект і запропонуємо рішення. Отримайте консультацію прямо зараз.

Докладніше про формат CSV див. на Wikipedia.