Настройка 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, імпорт може обнулити їх при оновленні. Включіть опцію «Не оновлювати порожні поля».