Імпорт каталогу з XLSX (Prom.ua / EVO)

Майданчики родини EVO — Prom.ua, satu.kz, deal.by — дозволяють вивантажити весь каталог у файл Excel (XLS, XLSX або CSV) і так само завантажити його назад. Формат файлу імпорту й експорту в них однаковий, тож той самий файл працює в обидва боки. Elbuz читає цей файл напряму: розбирає його аркуші, розкладає значення по картках товарів і, що важливо, зберігає навіть ті поля Prom, яким у стандартній картці немає прямого місця.

Ця стаття — не «натисніть кнопку й усе з'явиться», а докладний розбір: які колонки файлу в які поля потрапляють, за якою логікою зіставляються товари, які обмеження мають поля і як ті самі дані потім вивантажуються назад. Це один зі способів завантаження з огляду завантаження даних: формат Prom має готовий шаблон, тож колонки розмічати вручну не треба — програма впізнає їх за назвами.

1

Шаблон «XLSX - prom.ua, satu.kz, deal.by»

2

Створити новий шаблон

1. Рядок шаблону типу «XLSX - prom.ua, satu.kz, deal.by», за яким завантажують каталог із Prom.ua, Satu.kz, Deal.by.
2. Кнопка «Додати» відкриває форму створення нового шаблону завантаження.

Структура файлу: два аркуші

Excel-файл Prom (XLS/XLSX) містить два аркуші, і Elbuz читає їх за назвами:

• «Export Products Sheet» — товари. Кожен рядок, крім першого, — це один товар; перший рядок — заголовки колонок.
• «Export Groups Sheet» — групи (категорії): їхні номери, назви, ідентифікатори та зв'язок «батько–дитина».

У форматі CSV аркуш лише один (тільки товари), у кодуванні UTF-8 або UTF-16. Перший рядок кожного аркуша — заголовки: Elbuz зіставляє їх із відомими назвами полів і так визначає, у якій колонці що лежить. Назви розпізнаються і російською, і українською (Код_товара = Код_товару, Название_позиции = Назва_позиції тощо), тож обидві мовні версії файлу читаються однаково. Порядок колонок значення не має — важлива саме назва в заголовку; якщо якоїсь колонки немає, відповідне поле лишиться порожнім.

Головне: ідентифікатори і логіка зіставлення

Найважливіше для повторних завантажень — як програма впізнає, що товар із файлу вже є в каталозі. Від цього залежить, оновиться наявна картка чи створиться дубль. За це відповідають кілька колонок, і Elbuz використовує їх у такому порядку:

Логіка така: спочатку Elbuz шукає товар за Ідентифікатором_товару. Якщо цю колонку не заповнено — шукає за Унікальним_ідентифікатором. А якщо не заповнено жодного ідентифікатора — товар вважається новим, і для нього створюється власний внутрішній ключ. Саме тут криється типова пастка: якщо у файлі немає стабільних ідентифікаторів, кожне повторне завантаження створюватиме дублі замість оновлення. Тому файл, вивантажений із самого Prom (де ідентифікатори вже проставлені), — найнадійніше джерело; саморобний файл без ідентифікаторів варто спершу перевірити на невеликій частині.

Куди саме лягають ці ідентифікатори в нас — це варто знати, бо саме вони тримають синхронізацію з Prom:

• Ідентифікатор_товару зберігається у системне поле товару «UUID» — унікальний ключ товару в Elbuz. Це головний ключ зіставлення: при імпорті в UUID лягає Ідентифікатор_товару з файлу.
• Унікальний_ідентифікатор Prom потрапляє в окреме додаткове поле з такою ж назвою (службовий числовий номер товару на Prom).

Пріоритет заповнення UUID при імпорті такий: спершу — Ідентифікатор_товару; якщо його у файлі немає — Унікальний_ідентифікатор; якщо немає й того — Elbuz генерує власний UUID для нового товару. Далі цей UUID стає постійним ключем цієї позиції у вашому каталозі.

Куди потрапляють основні значення картки

Частина колонок лягає прямо в рідні поля картки товару — ті, що є в кожній картці Elbuz:

Артикул (Код_товару) записується одразу у два поля картки — артикул і MPN. Ціна перед збереженням приводиться до вашої базової валюти: якщо у файлі ціни в іншій валюті, Elbuz бере курс за кодом валюти й перераховує. Категорія товару зв'язується з деревом груп із аркуша «Export Groups Sheet», а якщо групи товару там немає — вона створюється автоматично з номера й назви, вказаних у самому рядку товару.

Формати й обмеження значень

У полів Prom є конкретні формати, і файл варто готувати з їх урахуванням — інакше майданчик відхилить рядок або обріже значення:

• Код_товару — до 25 символів (цифри, кирилиця, латиниця, знаки - _ . / та пробіл).
• Назва_позиції — до 110 символів (рос.), Назва_позиції_укр — до 130.
• Опис / Опис_укр — до 12160 символів; HTML_заголовок/опис — до 250 (рос.) / 270 (укр.).
• Ціна — число від 0.01; Валюта — код (UAH, USD, EUR, PLN, KZT…) або скорочення (грн, дол, $).
• Тип_товару — літера: r — лише роздріб, w — лише опт, u — і опт, і роздріб, s — послуга.
• Одиниця_виміру — зі списку Prom (шт., упаковка, комплект, пара, м, кг, л, набір…).
• Оптова_ціна та Мінімальне_замовлення_опт — кілька значень через ;; Подарунки/Супутні — номери рядків або ID через ;.
• Знижка — число або відсоток (наприклад, 12.5 або 30%) з датами дії «від/до».

Elbuz зберігає ці значення такими, як вони у файлі (у відповідні поля картки — див. нижче), а перевірку на відповідність вимогам Prom робить уже сам майданчик під час вивантаження. Тому чистий, коректний за форматом файл заощаджує час на обох кінцях.

Наявність: символи Prom і формула зворотного зв'язку

Наявність у файлі Prom кодується символами, і Elbuz переводить їх у свої статуси наявності:

• + (або ! — «готово до відправки») → у наявності;
• - → немає в наявності;
• & → очікується;
• @ → послуга;
• цифра (наприклад, 7) → під замовлення (кількість днів на доставку);
• порожнє поле → «немає в наявності» (так задумано в Prom).

Найцікавіше — що поле наявності працює у два боки. Разом із додатковим полем «Наявність» Elbuz створює для нього формулу, яка рахує символ Prom не зі старого значення файлу, а з поточного статусу наявності товару у вашому каталозі: «у наявності» перетворюється на +, «немає» — на -, «очікування» — на & і так далі. Тому коли ви вивантажуєте каталог назад на Prom, наявність завжди свіжа — така, яка зараз у вашій системі, а не застигла на моменті імпорту.

Додаткові поля, які створюються автоматично

У Prom значно більше полів, ніж у стандартній картці товару. Щоб нічого з файлу не втратити, Elbuz під час імпорту сам створює в базовому каталозі відповідні додаткові поля й записує туди ці значення. Тобто картка не «обрізає» файл Prom до кількох стандартних полів — вона зберігає його вміст повністю. Ось основні групи таких полів, що з'являються в картці після першого імпорту:

• Ціни й замовлення: Оптова_ціна, Мінімальний_обсяг_замовлення, Мінімальне_замовлення_опт, Ціна_від, Знижка, Термін_дії_знижки_від/до.
• Логістика й пакування: Можливість_постачання, Термін_поставки, Спосіб_пакування (+ укр.), Одиниця_виміру, Де_знаходиться_товар, Країна_виробник, Гарантійний_термін.
• Класифікація Prom: Тип_товару, Ярлик, Номер_групи, Назва_групи, Ідентифікатор_підрозділу, Ідентифікатор_групи, ID_групи_різновидів, Номер_пристрою_(MPN).
• Контент і SEO: Ключові_слова, Пошукові_запити, Особисті_нотатки та українські версії назви, опису й meta-полів.
• Зв'язки й службове: Подарунки, Супутні (та їхні ID), Товар_на_видалення й Причина_видалення, Унікальний_ідентифікатор (окреме індексоване поле під внутрішній номер Prom).

Ці поля видно в картці товару поряд зі стандартними, і з ними можна працювати як зі звичайними: фільтрувати, показувати в сітці, використовувати у формулах і — головне — вивантажувати назад.

Повний цикл: імпорт і експорт — одне ціле

Формат Prom влаштований так, що файл імпорту й файл експорту — однакові. Тому поля, у які імпорт записав дані, — це ті самі поля, з яких дані потім вивантажуються назад на Prom. Зокрема, наш UUID товару на вивантаженні лягає назад у колонку Ідентифікатор_товару, а додаткове поле «Унікальний_ідентифікатор» — у однойменну колонку. Так замикається цикл: завантажили каталог Prom → попрацювали з ним у Elbuz → вивантажили назад, і Prom упізнає свої товари.

Сценарій: ви додали новий товар у Elbuz

Розберемо саме той випадок, що найчастіше бентежить. Ви завантажили каталог із файлу Prom — кожен товар отримав UUID, що дорівнює його Ідентифікатору_товару на Prom. Потім у базовому каталозі Elbuz ви створили новий товар — йому програма присвоїла власний новий UUID, а поля «Унікальний_ідентифікатор» у нього немає (він не приходив з Prom). Що станеться на вивантаженні назад:

• у колонку Ідентифікатор_товару потрапить новий UUID цього товару — значення, якого на Prom ще немає;
• колонка Унікальний_ідентифікатор для нього піде порожня — Elbuz навмисно лишає її порожньою, якщо внутрішнього номера Prom у товару немає.

Коли такий файл завантажується на Prom, майданчик зіставляє товари за Ідентифікатором_товару. Наявні (чий Ідентифікатор_товару Prom знає) — оновлюються. А новий, з невідомим для Prom Ідентифікатором і порожнім Унікальним_ідентифікатором, майданчик сприймає як новий товар і додає його, присвоюючи вже свій внутрішній номер. Тобто нічого не ламається: старі позиції оновлюються, нові — заводяться. Ключова умова — не заповнювати «Унікальний_ідентифікатор» вручну для нових товарів: це службовий номер самого Prom, його не можна вигадувати.

XML замість XLSX

Prom дозволяє обмінюватися каталогом не лише через Excel, а й через XML — і на вивантаження, і на завантаження. Логіка ідентифікаторів там та сама: у XML теж є ідентифікатор товару, за яким Prom відрізняє новий товар від наявного. Якщо вам зручніше працювати з XML, каталог можна завантажувати імпортом XML / YML; принцип зіставлення за стабільним ідентифікатором лишається незмінним — тільки формат файлу інший.

Де налаштувати вивантаження назад

Зворотне вивантаження на Prom (у той самий формат XLSX) детально описано в парній статті вивантаження на Prom (XLSX) — там і повний порядок обміну з майданчиком, і чому Elbuz не задвоює товари. За замовчуванням серед колонок вивантаження є і Ідентифікатор_товару (= ваш UUID), і Унікальний_ідентифікатор, тож повний двобічний обмін працює «з коробки». Разом імпорт і експорт складають єдиний цикл: те, що ви завантажили, тими самими полями й вивантажується назад.

Характеристики (атрибути)

Характеристики товару Prom тримає в трійках колонок, які завжди йдуть у строгому порядку: Назва_Характеристики, Одиниця_виміру_Характеристики, Значення_Характеристики. Таких трійок у файлі може бути багато — по одній на кожну характеристику, і колонка одиниці виміру має бути присутня, навіть якщо порожня. Множинні значення однієї характеристики розділяють символом | (наприклад, Алюміній | Пластик).

Elbuz розпізнає ці трійки за заголовком і переносить у атрибути товару: назва стає атрибутом, значення — його значенням, а одиниця виміру (см, кг, Вт…) автоматично додається у довідник одиниць, якщо її там ще немає. Характеристики завантажуються разом з рештою даних файлу автоматично — окремо вмикати їх не треба. Якщо ж у товарі атрибутів немає, значить у файлі не було відповідних трійок колонок або їх не вдалося розпізнати за заголовком.

Різновиди (варіанти) товару

Prom позначає варіанти одного товару (кольори, розміри тощо) через поле ID_групи_різновидів: усі рядки з однаковим значенням цього поля й заповненими характеристиками вважаються різновидами одного товару, а перший рядок у групі — основним. Elbuz зберігає це поле, тож зв'язок різновидів не губиться при зворотному вивантаженні. Якщо ви ведете варіанти на Prom, тримайте ID_групи_різновидів у файлі заповненим — саме воно тримає різновиди разом.

Групи (аркуш «Export Groups Sheet»)

Дерево категорій Elbuz будує з аркуша груп. Кожна група має Номер_групи (номер на сайті Prom), Назву (та її укр. версію), Ідентифікатор_групи (зовнішній ID — наприклад, номер групи у вашій CRM), а вкладеність задається полями Номер_батьківської_групи та Ідентифікатор_батьківської_групи (для кореневих груп вони порожні). Є й SEO-поля групи та описи «до» і «після» списку товарів. Групи зіставляються насамперед за ідентифікатором, а якщо його немає — за номером; нові створюються, наявні оновлюються. Якщо товар посилається на групу, якої немає на аркуші груп, Elbuz створить її з даних самого рядка товару, щоб позиція не лишилась «безхатньою».

Режим «видаляти те, чого немає у файлі»

У шаблоні є окремий режим повного дзеркала: видаляти з каталогу товари й категорії, яких немає в завантажуваному файлі. Увімкнений, він робить каталог точною копією файлу — усе зайве прибирається (разом із їхніми характеристиками, фото та зв'язками). Це потужно, але й небезпечно: якщо ви випадково завантажите неповний файл, зайве буде видалено. Тому вмикайте цей режим свідомо й лише коли впевнені, що файл містить увесь асортимент. Щоб дзеркало не зачіпало товари з інших джерел, є окреме обмеження унікальності за шаблоном-джерелом — тоді видаляються лише позиції, що прийшли саме цим шаблоном.

Чому товар іноді не оновлюється

Якщо після повторного імпорту якийсь товар лишився без змін, причина зазвичай не у файлі, а в ознаках самого товару. Позиції з ознакою «лише читання» імпорт навмисно не чіпає — так захищають вручну вивірені картки. А якщо в товарі стоїть «зафіксована ціна», оновляться всі поля, крім ціни: файл не перезапише те, що ви зафіксували свідомо. Це не помилка, а захист від затирання ручної роботи автоматичним завантаженням.

Що обрати в шаблоні

Форма шаблона проста: ви вказуєте джерело — файл з комп'ютера або посилання, за яким Elbuz забиратиме файл сам, — і за потреби вмикаєте кілька перемикачів. Основний набір даних (категорії, товари, виробники, характеристики) завантажується з файлу автоматично, окремо вмикати їх не треба. Керовані ж опції стосуються поведінки завантаження: режим повного дзеркала («видаляти те, чого немає у файлі»), перевірка унікальності в межах цього шаблону-джерела та інші тонкі налаштування. Радимо перший запуск зробити на невеликому або тестовому файлі й перевірити кілька карток очима — назви, ціни, категорії, наявність, додаткові поля, — і лише переконавшись, що все стало правильно, вантажити повний файл і ставити шаблон на розклад.

1

Джерело даних — локальний файл або зовнішнє посилання

2

Блок «Що завантажувати»

1. Оберіть, звідки брати файл: завантажити з комп'ютера чи вказати зовнішнє посилання.
2. Опція визначає, чи видаляти в базовому каталозі записи, яких немає у завантаженому файлі.

Часті питання

Куди потрапляють поля Prom, яких немає в стандартній картці (оптова ціна, знижки тощо)?

Elbuz створює під них додаткові поля прямо в базовому каталозі під час першого імпорту й записує туди значення. Тому картка зберігає вміст файлу Prom повністю, а не лише кілька стандартних полів. Ці ж поля потім використовуються для вивантаження назад.

Що буде, якщо у файлі не заповнено ідентифікатор товару?

Elbuz спробує зіставити товар за внутрішнім номером Prom (Унікальний_ідентифікатор). Якщо і його немає — товар вважається новим. Тому файл без жодних ідентифікаторів при повторному завантаженні наробить дублів; надійніше брати файл, вивантажений із самого Prom, де ідентифікатори вже проставлені. У самому Prom «Ідентифікатор_товару» — обов'язкове поле саме з цієї причини.

Код_товару — це і є ідентифікатор для оновлення?

Ні. Код_товару — це ваш артикул (SKU, до 25 символів), він записується в поля «артикул» і «MPN» картки. Для впізнавання товару при повторному імпорті Elbuz використовує внутрішній ідентифікатор Prom, а не артикул, бо артикул продавці іноді змінюють.

Я створив новий товар у Elbuz — Prom підхопить його при вивантаженні?

Так. Новий товар отримує власний UUID, який на вивантаженні йде в колонку Ідентифікатор_товару, а «Унікальний_ідентифікатор» лишається порожнім. Prom бачить Ідентифікатор_товару, якого в нього немає, і додає товар як новий, присвоївши свій внутрішній номер. Наявні товари при цьому оновлюються за їхнім Ідентифікатором_товару. Головне — не заповнювати «Унікальний_ідентифікатор» руками для нових товарів.

Чому не оновилась українська назва чи опис товару?

У Prom українська версія оновлюється, лише якщо у файлі заповнені обидва українські поля — і назва (Назва_позиції_укр), і опис (Опис_укр). Заповнене одне з них Prom проігнорує. Тримайте це правило, коли готуєте файл.

Чому наявність на вивантаженні не збігається з тим, що було у файлі?

Бо поле наявності рахується формулою з поточного статусу товару у вашому каталозі, а не береться з файлу «як є». Це навмисно: при вивантаженні назад на Prom іде актуальна наявність, а не застигла на моменті імпорту.

Товар не оновився при повторному імпорті — чому?

Найчастіше на ньому стоїть ознака «лише читання» (тоді імпорт його не чіпає) або «зафіксована ціна» (тоді оновиться все, крім ціни). Це захист вручну вивіреної картки від затирання автоматичним завантаженням.

Чому не завантажились характеристики?

Характеристики завантажуються з файлу автоматично, окремо вмикати їх не треба. Якщо в товарі їх немає, значить у файлі не було трійок колонок «Назва / Одиниця_виміру / Значення характеристики» або їх не розпізнано за заголовком — колонки мають іти саме в цьому порядку.