Вивантаження каталогу на Prom.ua у форматі XML (YML-фід)

Крім файлу Excel, Elbuz уміє віддавати каталог на Prom.ua у форматі XML — це YML-подібний фід, який майданчик забирає за посиланням і оновлює у себе за розкладом. Формат «prom.ua (XML)» — окремий від «prom.ua (XLS)»: XLSX — це файловий обмін в обидва боки, а XML — фід, що публікується за URL і сам підтримує каталог на Prom свіжим. Ця стаття — про XML-шлях; про файловий див. вивантаження на Prom (XLSX), а про завантаження з Prom — імпорт XLSX (Prom/EVO). Загальний огляд вивантаження — у статті шаблони вивантаження.

Де це у програмі

У вікні вивантаження ви створюєте шаблон і обираєте формат «prom.ua (XML)». Elbuz формує XML-фід із вашого каталогу; ви обираєте, які товари вивантажувати (весь каталог, категорії чи за правилами), і публікуєте фід за посиланням. Prom забирає це посилання й оновлює каталог у себе — вручну або за розкладом.

Що це за формат

Prom XML — це стандартний YML-фід: у корені yml_catalog, усередині — блок категорій і блок пропозицій (offers). Кожен товар — це один offer з набором вкладених елементів. На відміну від Excel-файлу, який ви завантажуєте руками, XML-фід живе за адресою: оновили каталог у Elbuz — фід за тим самим URL віддає свіжі дані, а Prom підхоплює їх за розкладом. Саме тому XML зручний для постійного автоматичного оновлення.

Структура пропозиції (offer)

Кожен товар у фіді виглядає приблизно так (набір полів можна змінювати в шаблоні):

Категорії у фіді йдуть окремим блоком, і в шаблоні за замовчуванням вони несуть ваші ідентифікатори: у категорії стоїть id="{uuid}" з прив'язкою до батьківської, а в товарі — той самий ключ у categoryId. Якщо потрібно віддавати номер категорії самого Prom, у шаблоні для цього є окремі підстановки {category_id_prom} і {category_name_prom} — вони беруть значення з полів категорії, заповнених при зіставленні з довідником майданчика.

Ідентифікатор — той самий UUID, що і в XLSX

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

• Prom упізнає товар за id і оновлює наявну позицію, а не плодить копії — так само, як з ідентифікатором у XLSX.
• Новий товар, створений у Elbuz, іде у фід зі своїм новим UUID — Prom бачить невідомий id і додає його як новий.
• Оскільки ключ один (UUID), формати не «сваряться» між собою: товар лишається тим самим, хоч через XLSX, хоч через XML.

Елемент available береться з поточного статусу наявності товару в каталозі, тож у фіді наявність завжди свіжа. А group_id зв'язує різновиди (варіанти) з основним товаром — тому кольори й розміри одного товару лишаються згрупованими, а не розсипаються окремими картками.

Характеристики й різновиди

Характеристики товару виходять у фід елементами param з атрибутами name (назва) та unit (одиниця) і значенням усередині, з окремим варіантом для української мови. Різновиди товару (варіанти) зв'язуються через group_id: основний товар і його варіанти мають спільну прив'язку, і Prom складає їх в одну картку з вибором варіанта. Фото у фіді обмежені десятьма на товар — це вимога самого Prom.

Публікація та оновлення за розкладом

Головна перевага XML-фіда — автоматизація. Фід публікується за посиланням, і Prom забирає його за заданою періодичністю: ви оновили ціни чи наявність у Elbuz — фід віддав нові дані — Prom оновив каталог у себе, без вашої участі. За словами самого Prom, оновлювати позиції через YML «на порядок легше», ніж файлом: досить один раз налаштувати фід і розклад. У Elbuz розклад вивантаження задають у налаштуваннях шаблону, а віддавати фід можна за прямим посиланням або на FTP.

XML чи XLSX — коли що

Обидва формати Prom спираються на той самий ідентифікатор (UUID), тож обидва оновлюють каталог без дублів. Різниця — у способі роботи:

• XML (YML-фід) — простіший, автоматичний шлях. Публікуєте посилання, ставите розклад — і каталог на Prom підтримується свіжим сам. Менше ручних дій, добре для постійного оновлення цін, наявності й асортименту.
• XLSX (файл) — повний двобічний файловий обмін з максимальним набором полів Prom. Зручно, коли треба разово вивантажити чи прийняти файл, попрацювати з ним у таблиці, керувати кожним полем.

Практичне правило: для щоденної автоматичної синхронізації зручніший XML-фід; для повного файлового обміну з усіма полями — XLSX. Оскільки ключ товару в них однаковий, можна навіть початково залити каталог файлом XLSX, а далі тримати його свіжим XML-фідом — ідентичність позицій при цьому не втратиться. Головне — не гнати в один і той самий бік два різні формати водночас, щоб не плутати, хто головне джерело.

Як налаштувати фід крок за кроком

Порядок простий і робиться один раз. Створіть шаблон вивантаження й оберіть формат «prom.ua (XML)». Визначте, які товари вивантажувати: весь каталог, окремі категорії чи за правилами відбору — так у фід потрапить саме те, що ви продаєте на Prom. За потреби відкоригуйте набір елементів offer під вимоги майданчика. Скористайтесь перевіркою («тест-прогон»), щоб побачити, як виглядає один товар у фіді, ще до повного вивантаження. Потім опублікуйте фід — отримаєте посилання, яке вставляється в кабінеті Prom, або віддавайте його на FTP.

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

Що відбувається після натискання «Вивантажити»

Кнопка «Вивантажити» є і в картці шаблону, і в рядку списку шаблонів. Перед стартом програма рахує, скільки товарів пройде відбір, і показує це у вікні підтвердження: «У файл піде товарів: N. Готовий файл замінить поточний за постійним посиланням». Зведення перед запуском зі списку шаблонів можна прибрати галочкою «Показувати зведення перед запуском вивантаження» у вікні «Стоп-правила вивантаження» — тоді прогін стартує одразу по кнопці, а зведення й стоп-правила однаково відпрацюють і підуть у журнал. Далі прогін іде так:

1. У журнал операції лягає передпольотне зведення: «Передпольотне зведення: усього товарів …, в наявності …, немає в наявності …, під замовлення …, без статусу наявності …», а поруч — «Минулого прогону: усього …, в наявності …».
2. Спрацьовують стоп-правила. Якщо розбіжність із минулим прогоном виходить за поріг, а правило стоїть у режимі «Попереджати», у журнал іде «Увага, дані виглядають підозріло: …», і прогін триває. Якщо режим «Зупинити вивантаження» — у журналі «Вивантаження зупинено стоп-правилом: …», і файл не чіпається зовсім.
3. Збираються категорії («Вивантаження категорій товарів»), якщо їх увімкнено в шаблоні.
4. Збираються товари («Вивантаження товарів»). Кожні 500 товарів у журнал іде рядок «Вивантаження товарів 500 із 12 340», а зібрана порція дописується у файл на сервері.
5. Зібраний файл їде у сховище: попередній файл цього шаблону стирається, на його місце лягає новий («Завантажуємо файл у хмарне сховище»). Якщо заповнено «Налаштування FTP», файл додатково кладеться на FTP.
6. У шаблон записуються посилання на файл, його розмір і дата вивантаження, а останнім рядком журналу йде «Вивантаження даних завершено» та «Витрачено часу: …».

Дві розвилки, за яких файл за посиланням не оновлюється:

• Під умови шаблону не підійшов жоден товар. Файл не перезаписується, у журналі — «Вивантаження даних НЕ завершено: файл не сформовано», дата останнього вивантаження лишається старою, а за посиланням лежить попередній файл.
• Ви натиснули «Стоп». Прогін обривається на найближчому товарі з рядком «Вивантаження перервано користувачем!» — за посиланням теж лишається попередній файл.

Повторний прогін: що перезапишеться

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

Звідси спосіб лишити поле за собою: приберіть цей елемент із шаблону в розділі «Шаблон XML». Чого немає в шаблоні, того немає й у файлі — віддавати майданчику буде нічого. Окремої галочки «не чіпати це поле» немає, керує саме склад шаблону. А як Prom чинить із полями, яких у фіді немає, і з правками, зробленими в кабінеті, задає сам майданчик — звіряйтеся з його довідкою.

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

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

Коли товар зникає з фіда

Товар не потрапляє у файл, якщо справджується хоча б одне:

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

Нуль на складі товар із фіда не прибирає. Наявність передається окремим атрибутом: за замовчуванням available="true" отримує тільки статус «В наявності», решта статусів дають available="false", а сам товар лишається у файлі. Що саме віддавати за кожним статусом — своє слово чи кількість — задають у вікні «Налаштування оновлення за наявністю товару», яке відкривається з картки шаблону.

Масове зникнення ловлять стоп-правила. За замовчуванням вони попереджають, якщо кількість товарів у наявності впала більш ніж на 30% щодо минулого прогону, якщо загальна кількість товарів у вивантаженні впала більш ніж на 50% або якщо вивантажувати нічого. Пороги й режим змінюють у вікні «Стоп-правила вивантаження»: у режимі «Зупинити вивантаження» файл не перезапишеться взагалі, і за посиланням лишиться минулий фід. Пороги працюють і під час запуску за розкладом.

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

Якщо прогін обірвався

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

Ознаки того, що прогін не дійшов до кінця: дата в колонці «Останнє вивантаження» не зрушила, а останній рядок журналу — «Вивантаження даних НЕ завершено: файл не сформовано» або «Вивантаження перервано користувачем!».

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

Розклад після обриву не заклинить назавжди: якщо процес помер, замок знімається сторожем, коли від старту минула година, а ознак життя немає понад пів години. Живий довгий прогін сторож не чіпає — доки він пише в журнал, він вважається робочим.

Якщо розклад спрацював, поки вивантажується інший шаблон, прогін скасовується рядком «Скасовано вивантаження за розкладом, причина - вивантажується інший шаблон (конфлікт обробки даних)». Файл лишається минулим, а наступного разу за розкладом шаблон піде звично.

Як побачити, що відпрацювало

Перше місце — журнал прогону в «Операціях»: він відкривається разом із запуском і пише кроки в реальному часі. Дивитися варто на три речі: передпольотне зведення на початку (скільки товарів і скільки з них у наявності), рядки «Вивантаження товарів N із M» і останній рядок — «Вивантаження даних завершено» з витраченим часом або «Вивантаження даних НЕ завершено: файл не сформовано».

Друге місце — список шаблонів: результат прогону видно там, без відкриття картки.

• «Останнє вивантаження» — коли шаблон відпрацював востаннє і скільки це тривало. «Ще не вивантажувався» означає, що прогону не було жодного.
• «В наявності» — скільки товарів останнього прогону були в наявності, а поруч різниця з попереднім прогоном і загальна кількість товарів у файлі. Падіння видно відразу, не відкриваючи сам файл.
• «Файл» — ім'я файла з посиланням (поруч кнопка «Копіювати посилання») і його розмір. Майже порожній фід помітний уже за розміром.

Третє — кнопка «Історія запусків» у шапці картки шаблону: скільки було запусків за період, середня тривалість, найдовший, скільки з помилками, початок і підсумок кожного.

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

Якщо id пропозиції все-таки змінили

Наслідки виправляють у зворотному порядку:

1. Поверніть у шаблоні атрибут у вигляд id="{uuid}" — саме так він стоїть у шаблоні за замовчуванням.
2. Натисніть «Перевірити» і подивіться на отриманий offer: у id має стояти той самий довгий ідентифікатор, що й у колонці «Ідентифікатор_товару» вивантаження XLSX.
3. Запустіть вивантаження. Наступний фід знову посилатиметься на ті самі картки, що й до помилки.

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

Вимкнути шаблон чи видалити

У шапці картки шаблону є перемикач «Активний / Вимкнений», у списку це колонка «Стан».

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

Якщо шаблон видалити: разом із ним зникають усі його налаштування — текст XML-шаблону, відбір товарів і категорій, налаштування статусів наявності, FTP і розклад. Повернути це можна тільки заведенням шаблону наново, з новим шаблоном XML і новим посиланням. Тому для паузи беріть вимкнення, а видалення лишайте для шаблонів, які точно більше не знадобляться.

Межі та числа

• Стелі за кількістю товарів немає. У файл іде все, що пройшло відбір; прогрес журнал відмічає кожні 500 товарів. Виняток — демонстраційний режим: там вивантаження обмежене 100 товарами, і в журналі про це є окремий рядок.
• Фото — до десяти на товар для Prom. Якщо потрібно менше, поставте своє число в полі «Максимальна кількість фотографій» у картці шаблону.
• Розклад — від години. У конструкторі розкладу найчастіший період для вивантаження — година; варіанта «щохвилини» там немає.
• Масовий прогін іде по черзі. «Вивантажити всі шаблони» запускається окремим фоновим процесом і бере активні шаблони один за одним: наступний стартує тільки після завершення попереднього. Кнопка «Стоп» зупиняє чергу на найближчій межі між шаблонами.
• У кожного шаблону власний файл і власне посилання, тож два шаблони не перезаписують файли один одного, навіть якщо ім'я файла в них однакове.

Чого фід не робить

• Не забирає нічого з Prom. XML-фід — рух в один бік: Elbuz кладе файл за посиланням. Дані з майданчика приходять іншим шляхом — див. імпорт XLSX (Prom/EVO).
• Не видаляє позицій на майданчику. У файлі є тільки те, що треба показати; команди «прибрати позицію» формат не передає.
• Не перевіряє вимог майданчика до вмісту. Elbuz стежить за тим, щоб XML був валідним (це й показує кнопка «Перевірити»), а чи влаштують Prom назви, категорії й характеристики — вирішує сам Prom при імпорті.
• Не попереджає про помилку в назві підстановки. Нерозпізнана підстановка вирізається з файлу мовчки, і вузол виходить порожнім.

Розбір частих проблем

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

Чим XML відрізняється від XLSX для Prom?

XLSX — це файл, який ви завантажуєте й приймаєте вручну або за розкладом, з максимальним набором полів. XML — це фід за посиланням, який Prom забирає сам за розкладом і оновлює каталог. XML простіший для постійної автоматизації, XLSX — повніший для файлового обміну.

Який ідентифікатор товару у XML-фіді?

Атрибут id пропозиції — це UUID товару в Elbuz, той самий ключ, що й «Ідентифікатор_товару» у XLSX. Тому ідентичність товару однакова в обох форматах, і Prom оновлює позиції без дублів.

Як Prom підхопить нові товари з фіда?

Новий товар іде у фід зі своїм новим UUID у id. Prom бачить невідомий ідентифікатор і додає товар як новий. Наявні позиції (чий id Prom уже знає) оновлюються.

Чому у фіді не всі фото товару?

Для Prom кількість зображень у фіді обмежена десятьма на товар — це вимога майданчика. Перше фото вважається головним.

Чи треба щоразу вивантажувати фід вручну?

Ні. Фід публікується за посиланням, а Prom забирає його за розкладом. Достатньо один раз налаштувати шаблон і періодичність — далі каталог на Prom оновлюється автоматично.

Як передаються різновиди (варіанти) товару?

Через атрибут group_id: основний товар і його варіанти мають спільну прив'язку, і Prom складає їх в одну картку з вибором варіанта, а не показує окремими позиціями. У фід для Prom при цьому їдуть самі різновиди, а головний товар пропускається.

Що буде, якщо вивантаження обірветься посередині?

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

Що дає вимкнення шаблону?

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