Як вивантажити каталог у YML (XML) фід для будь-якого сервісу

30 хв

Elbuz збирає з каталогу фід у форматі YML — XML-файл, який приймають маркетплейси, агрегатори цін, CMS і облікові системи, — і оновлює його за постійним посиланням. Вміст файлу ви задаєте текстом шаблону.

Коли це знадобиться:

Сервіс просить «XML-фід» або «прайс у форматі YML», а готового типу під нього немає — універсальний шаблон підганяється під його вимоги правкою тексту.
Файл потрібен партнеру чи власному сайту — фід перезбирається за розкладом.
Приймач хоче інші імена вузлів — ви міняєте рядок шаблону.
Боїтеся зіпсувати фід правкою — пробне вивантаження покаже XML і помилки на одному товарі.

З чого почати: створіть шаблон «YML (XML)» у вікні «Вивантаження даних».

Що вміє YML-фід

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

Де це і хто має доступ

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

Картка «Шаблон XML» з текстом файлу вивантаження та макросами

Як створити шаблон YML

У вікні «Вивантаження даних» натисніть «Додати», у списку типів відкрийте групу «XML-фід (YML)» і оберіть «YML (XML)». Це універсальний фід; решта пунктів групи налаштовані під конкретні майданчики.

Один шаблон — один файл. Фіди для різних сервісів із різним складом даних робіть окремими шаблонами, а не переналаштовуйте один.

Коли брати готовий тип, а не універсальний

Для відомого майданчика зазвичай уже є свій тип: у ньому враховані обов'язкові вузли, ліміти й особливості ідентифікаторів. Універсальний YML беріть, коли готового типу немає: власний сайт, партнерський обмін, сервіс аналітики, нішевий агрегатор. Пошукайте назву сервісу в списку типів; немає — беріть «YML (XML)».

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

Що потрапляє у файл

Новий шаблон одразу створюється з готовим фідом — переписувати його з нуля не потрібно. У файлі три частини:

Частина файлу	Що в ній
Шапка	Кореневий вузол `yml_catalog` з датою вивантаження, далі `shop`: назва магазину, компанія, адреса сайту, службові відомості про платформу й пошта. Тут же блок `currencies` — валюта фіда та її курс
Категорії	Блок `categories`, у ньому рядок `category` на кожен розділ: власний ідентифікатор, ідентифікатор батьківського розділу й назва. Так у файлі відтворюється ваше дерево
Пропозиції	Блок `offers`, у ньому `offer` на кожен товар: посилання, ціна, валюта, категорія, фото, назва, виробник, артикул, опис і характеристики

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

Категорії, фото, характеристики

Налаштування	Що робить
Категорії (галочка)	Чи включати у файл блок розділів. Деякі сервіси приймають фід без дерева — тоді галочку можна зняти
Символ роздільника категорій	Чим розділяти рівні у повному шляху розділу, коли він іде одним рядком
Фото (галочка)	Чи вивантажувати зображення
Посилання на фото товару	Адреса, з якої приймач качатиме фото: домен і папка. Фото віддаються посиланнями, а не файлами
Максимальна кількість фотографій	Обмеження на товар — у більшості майданчиків свій ліміт, і зайві фото вони або відкидають, або відхиляють увесь фід
Атрибути, Опції (галочки)	Чи вивантажувати характеристики й опції товару

Якщо в довіднику заведений , у файл іде один параметр з іменем головного атрибута, а значення з усіх прив'язаних збираються в нього.

Товар із заповненими «Температура» і «Цветовая температура» віддає один «Цветовая температура» з обома значеннями. Окремої галочки для цього немає: правило діє в усіх YML-шаблонах.

Чий залишок і яка мова

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

Як влаштоване «Вивантажувати лише нові дані»

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

Змін не було — файл не оновиться. У журналі «Вивантаження даних НЕ завершено: файл не сформовано», дата останнього вивантаження не зрушить, за посиланням лишиться попередній файл. Виняток — режим Prom (див. нижче).
Позначка спільна на всі шаблони. Якщо галочку увімкнено у двох шаблонах, зміни забере той, чий прогін пройшов першим; другому дістанеться порожньо.
Приймач має розуміти часткові файли. Сервіс, який вважає фід повним переліком, вирішить, що решти товарів у вас більше немає (що буде з товаром, який зник із фіда).

Як змінити вміст фіда: шаблон XML і макроси

Вміст файлу задаєте ви самі, у полі «Шаблон XML». Це один суцільний документ — такий, яким має вийти фід, — а замість значень у ньому стоять макроси у фігурних дужках: {name}, {price}, {uuid} і так далі. Під час вивантаження кожен макрос замінюється значенням конкретного товару.

Потрібен додатковий вузол — допишіть рядок; інше ім'я — перейменуйте; зайвий — приберіть.

Обчислити значення допоможуть формули у подвійних квадратних дужках: наприклад, рекомендована ціна, якщо вона заповнена, інакше звичайна. Синтаксис і приклади — у розділі ціна у вивантаженні.

Натисніть Ctrl+Space або введіть { — з'явиться підказка. Поруч із полем є довідник макросів, згрупований за змістом. Клік по макросу вставляє його в позицію курсора.

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

Підшаблони: фото й характеристики

У товара не одне фото й не одна характеристика, тому для них є підшаблони — рядки, які повторюються стільки разів, скільки у товара фотографій або атрибутів. У головному шаблоні на їхньому місці стоять макроси {image_list} і {attribute_list}, а самі рядки задаються у картці «Підшаблони». Рядок підшаблону — до 255 символів.

Фото вузлом picture чи image — правка одного рядка підшаблону.

Хто головніший — галочка чи макрос

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

Що	Хто сильніший	Що вийде
Фото й характеристики	Макрос	`{image_list}` у рядку товару везе фото навіть зі знятою галочкою «Фото»; `{attribute_list}` так само ігнорує зняту «Атрибути». Щоб фото не потрапили у фід, приберіть макрос
Категорії	Галочка	Знята «Категорії» — рядків `category` у файлі не буде, лишиться порожня обгортка `<categories></categories>`
Товари	Галочка	Знята «Товари» — у файлі шапка, категорії й жодного `offer`. Прогін завершується штатно, і цей порожній файл ляже на постійне посилання
Порожній підшаблон	Програма	Без «Підшаблону фото» у файл піде `<picture>адреса</picture>`, без «Підшаблону характеристики» — `<param name="Назва" unit="одиниця">Значення</param>`. Свій рядок програма підставляє без власних вузлів

Усередині рядка товару підстановка йде в жорсткому порядку: спочатку формули у подвійних квадратних дужках, потім окремі характеристики {attribute_61}, потім поля товару, потім списки {image_list}, {video_list}, {attribute_list}. Усе, що лишилося у фігурних дужках після цього, вирізається з файлу.

Програма визначає відомий майданчик не лише за типом, а й за текстом: латинські «rozetka» або «prom» у назві шаблону чи в підшаблоні характеристики, а також вузли selling_type, portal_category_id, portal_id у шаблоні. Тоді правила міняються мовчки:

режим Rozetka — фото обрізаються до 15 на товар, значення характеристик — до 255 символів, з текстових полів вирізаються посилання й картинки;
режим Prom — фото обрізаються до 10, а головна картка товару з варіантами у фід не потрапляє, їдуть тільки варіанти. Позначки «Вивантажено» вона не отримує, тож із «лише новими даними» прогін без змін покладе на посилання файл без жодного offer замість «файл не сформовано».

Не називайте універсальний шаблон «як у Rozetka» чи «Prom-подібний»: досить одного латинського слова в назві.

Як не плодити дублі на боці приймача

У пропозиції offer ідентифікатором за замовчуванням іде UUID товару — власний незмінний ключ картки в Elbuz. Доки ідентифікатор стабільний, сервіс оновлює наявні позиції; якщо він змінюється від вивантаження до вивантаження, на тому боці плодяться дублі.

Той самий UUID читає й імпорт: коли фід із Elbuz завантажується назад — у вас чи у партнера, — товари впізнаються за ним і не дублюються. Міняйте ідентифікатор у шаблоні, лише коли приймач прямо вимагає іншого (наприклад, числового коду).

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

Що повторний прогін робить із вашими правками

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

Що станеться з даними, які ви правили в кабінеті сервісу, вирішує сервіс. З боку Elbuz важіль один — склад вузлів у шаблоні: немає у файлі вузла <name> — сервісу нізвідки взяти нову назву, і ваша лишиться. Ведете поле вручну на боці сервісу — приберіть відповідний рядок із шаблону (сценарій).

Як передати наявність і зняти товар із продажу

Наявність у пропозиції — атрибут available, його підставляє макрос {xml_stock_status}. У картці «Пов'язані налаштування» кнопка «Налаштування оновлення за наявністю товару» відкриває таблицю, де кожному вашому статусу задається, що піде у фід (колонка «Назва на сайті (у файлі)») і яку кількість показувати. За замовчуванням «в наявності» дає true, решта — false; потрібні власні слова — впишіть їх там же.

Вікно «Налаштування оновлення за наявністю товару» з таблицею статусів наявності

Рядок таблиці діє, лише доки в ньому стоїть «Активність налаштування». Без галочки програма повертається до вбудованого правила: «в наявності» дає true, решта — false, а кількість береться з активності товару: 1000 для активного, 0 для вимкненого. Якщо «налаштування збереглося, а у файлі старе значення» — перевірте цю галочку першою.

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

Дія або результат
Розвилка: далі шлях залежить від відповіді

Що буде з товаром, який зник із фіда

У YML немає ознаки «товар видалено». Файл — повний перелік того, що ви продаєте зараз, і позиція, якої в ньому більше немає, не отримує жодної команди. Один сервіс знімає її з публікації, інший лишає висіти такою, якою забрав минулого разу; з боку Elbuz це не видно.

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

Як перевірити фід до бойового запуску

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

Перевірка показує:

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

Якщо вказаний товар не проходить умови шаблону, програма так і напише: «Товар #… не потрапив у вивантаження: він не проходить умови цього шаблону».

Розклад і посилання на файл

Готовий файл Elbuz кладе у ваше сховище й дає на нього постійне посилання — його ви віддаєте сервісу. За розкладом файл перезбирається, посилання лишається тим самим. Розклад і FTP задаються кнопками «Налаштування розкладу» і «Налаштування FTP» у картці «Пов'язані налаштування».

Передпольотне зведення, стоп-правила, ручний запуск, розклад, FTP і журнал однакові для всіх форматів: зведення, стоп-правила, запуск руками і за розкладом, куди лягає файл, журнал прогону. Вивантаження у файл не тарифікується: з балансу за прогони нічого не списується.

Що лежить за посиланням, коли прогін не дійшов до кінця

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

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

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

Дія або результат
Розвилка: далі шлях залежить від відповіді

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

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

Дія або результат
Розвилка: далі шлях залежить від відповіді

В імені файлу працюють макроси {DATE}, {DATETIME} і {TIME}. Але новий файл тоді щоразу лягає під новим іменем, а після заливки програма прибирає зі сховища інші файли шаблону: адреса, яку ви віддали сервісу вчора, сьогодні не оновлюється або не працює. Дату в імені ставте, тільки коли файл забирають руками.

«Хвіст» ?uuid=384512 у посиланні щоразу інший; сервісу можна віддати посилання без нього.

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

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

Видалення стирає налаштування: текст шаблону, підшаблони, таблицю статусів наявності, FTP, відбір і розклад. Файл у сховищі не видаляється й тут. Щоб сервіс перестав отримувати ваші дані, приберіть посилання на його боці.

Якщо помилковий фід уже забрали

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

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

Сценарії

Назви й описи на майданчику ведете вручну

Задача: у кабінеті сервісу ви самі переписали назви товарів і не хочете, щоб наступний фід їх затирав.

Що зробити: у полі «Шаблон XML» приберіть із рядка товару вузол <name> (так само — <description>, якщо описи теж ведете там).

Що вийде: у файлі цих вузлів не буде, тож сервісу нізвідки взяти нову назву. Ціна, наявність і решта вузлів ідуть у файл як і раніше. Назви в картках Elbuz не зміняться — вивантаження в картки товарів не пише.

Товар закінчився, але має лишитися на майданчику

Задача: позиція тимчасово відсутня, і на майданчику вона має показуватися як «немає в наявності», а не зникати.

Що зробити: лишіть товар у відборі шаблону. У картці «Пов'язані налаштування» відкрийте «Налаштування оновлення за наявністю товару», у рядку свого статусу поставте «Активність налаштування» і, якщо приймач чекає не false, впишіть його слово в «Назва на сайті (у файлі)».

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

Великий каталог, приймач розуміє часткові файли

Задача: віддавати сервісу за розкладом лише те, що змінилося, а не весь каталог щоразу.

Що зробити: увімкніть «Вивантажувати лише нові дані» в одному шаблоні й задайте частоту кнопкою «Налаштування розкладу».

Що вийде: у файл потрапляють товари без позначки «Вивантажено». Якщо змін не було, новий файл не збереться і за посиланням лишиться попередній (як влаштована галочка).

Не пустити на майданчик обвал наявності

Задача: якщо в базовому каталозі раптом «зникла» наявність, фід не має поїхати на майданчик.

Що зробити: у зведенні перед запуском натисніть «Налаштувати пороги» й для правила обвалу наявності оберіть «Зупинити вивантаження». Поріг за замовчуванням — 30%; для обвалу кількості товарів — 50%.

Що вийде: ні ручний прогін, ні прогін за розкладом не почнуться, у журналі — «Вивантаження зупинено стоп-правилом: …», за посиланням лишається попередній файл. Поки шаблон жодного разу не вивантажився успішно, правила обвалу мовчать — порівнювати немає з чим (стоп-правила).

Сервіс не приймає фото у фіді

Задача: приймач відхиляє файл із вузлами фото або бере зображення з іншого джерела.

Що зробити: приберіть макрос {image_list} з рядка товару в «Шаблон XML».

Що вийде: вузлів фото у файлі не буде. Однієї знятої галочки «Фото» для цього замало (хто головніший — галочка чи макрос).

Що робити, коли фід не такий, як треба

Тут — випадки, властиві YML-шаблону. Порожня вибірка, обраний магазин, стоп-правила, конфлікт розкладу й FTP — у загальній таблиці розбору.

Розбір частих проблем YML-фіда
Що ви бачите	Чому так	Що зробити
«Вивантаження даних НЕ завершено: файл не сформовано», хоча помилок немає	Увімкнено «лише нові дані», а з минулого прогону жоден товар не змінився	Так і має бути: за посиланням попередній файл. Потрібен повний фід — зніміть галочку (як влаштована галочка)
Фід перестав оновлюватися, у журналі за розкладом порожньо	Шаблон вимкнений: за розкладом він пропускається мовчки	Перемкніть стан у шапці картки на «Активний» (вимкнути чи видалити)
«Макроси не розпізнано, і вони будуть вирізані з файлу: …» або сервіс пише, що поле порожнє	Описка в назві макроса: такого поля немає	Вставляйте макроси з підказки (Ctrl+Space) або з довідника поруч із полем, а не руками
«У шаблоні не знайдено повторюваний вузол товару… Зміни НЕ збережено»	Вузол товару перейменували або зіпсували, і програма не знає, який рядок розмножувати	Поверніть тег на місце або впишіть його нове ім'я в «Розширене» → «Тег рядка товару»
Фото чи характеристики у файлі, хоча галочку знято	Макрос у шаблоні сильніший за галочку	Приберіть `{image_list}` або `{attribute_list}` із рядка товару (хто головніший)
У файлі шапка й категорії, але жодного `offer`, у журналі звичайне завершення	Знято галочку «Товари» або в назві шаблону є «prom» і вибірка — лише головні картки з варіантами	Поставте «Товари»; приберіть «rozetka»/«prom» із назви шаблону (режим майданчика)
На боці сервісу після кожного вивантаження з'являються дублі	Ідентифікатор пропозиції змінюється від прогону до прогону	Поверніть в `offer` стабільний `{uuid}` (ідентифікатор товару)

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

Що таке YML і чим він відрізняється від звичайного XML?

YML — XML із наперед відомою структурою для товарних каталогів: корінь yml_catalog, усередині магазин, блоки валют, категорій і пропозицій. Приймачі розуміють такий файл без додаткової розмітки.

Чи треба редагувати шаблон, якщо мене влаштовує стандартний фід?

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

Майданчика немає у списку типів (наприклад, MAUDAU). Як туди вивантажити?

Якщо він приймає XML-фід за посиланням — створіть «YML (XML)» і підженіть теги під його документацію. Якщо Excel або CSV — тип «Прайс-лист (XLSX, CSV)». Прямого з'єднання за API з таким майданчиком немає.

Чи перевіряє Elbuz, що фід відповідає вимогам сервісу?

Ні. Пробне вивантаження перевіряє лише коректність XML і макроси. Обов'язкові вузли, довжину назви, валюти й ліміт фото перевіряє сервіс — про порушення ви дізнаєтеся від нього.

Чи видно в Elbuz, що сервіс забрав файл?

Ні. Журнал закінчується на тому, що файл покладено у сховище. Коли сервіс його прочитав і що з ним зробив, дивіться в кабінеті сервісу.

Прогін обірвався — що зараз лежить за посиланням?

Попередній файл: новий публікується одним останнім кроком. Повторити прогін можна одразу (що лежить за посиланням).

Якщо вимкнути шаблон, фід зникне у сервісу?

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

Скільки фото потрапляє у фід і звідки беруться посилання?

Не більше, ніж задано в «Максимальна кількість фотографій». Адреса складається з поля «Посилання на фото товару»; самі файли приймач качає за посиланнями.

Суміжні теми

Якщо товар є в каталозі, а у фід не потрапив — Вивантаження товарів: чому товар не поїхав у файл.
Якщо фід потрібен для Google Merchant, Facebook чи TikTok — Фід Google Merchant.
Якщо приймач — Rozetka, для неї є готовий тип — Вивантаження на Rozetka.
Якщо треба завантажити чужий YML у свій каталог — Імпорт каталогу з XML / YML.

Чи була стаття корисною?