Формат Spefix (рекомендовано)

Це наш власний формат, оптимізований для e-commerce платформ. Формат Spefix дозволяє передавати інформацію про ваш каталог товарів у структурованому вигляді для індексування та пошуку.

Коренева структура

Альтернативна застаріла Структура

<yml_catalog>
    <shop>
        <categories>...</categories>
        <offers>...</offers>
    </shop>
</yml_catalog>

попередження

Альтернативна структура все ще підтримується для зворотної сумісності, але не рекомендується для нових інтеграцій. Використовуйте рекомендовану структуру з елементом <catalog>.

Структура категорій

У форматі Spefix ієрархічна структура категорій визначається в елементі <categories>. Кожна категорія може мати батьківську категорію, що дозволяє створювати гнучкі дерева категорій для організації товарів.

Поля категорії

Кожен елемент <category> має наступну структуру:

<category id="123" parent_id="100" url="https://example.com/category" ordering="10">
    Назва категорії
</category>

Атрибут/Поле	Тип	Обов'язкове	Опис
`@id`	String	Так	Унікальний ідентифікатор категорії
`@parent_id`	String	Ні	ID батьківської категорії для створення ієрархії. Якщо не вказано, категорія вважається кореневою.
`@url`	String	Ні	URL сторінки категорії у вашому магазині. Рекомендується вказувати для покращення UX.
`@ordering`	Integer	Ні	Ручний порядок блоків категорій у пошуку. Менше число стоїть вище. Деталі нижче.
`#text`	String	Так	Назва категорії. Текст, що відображатиметься користувачам у пошуку та навігації.

попередження

Унікальність ідентифікаторів дуже важлива. Якщо два елементи матимуть однаковий 'id', це може призвести до помилок при парсингу файлу та некоректної роботи пошуку.

Приклад

Нижче наведено приклад повного розділу <categories> з кількома рівнями вкладеності:

<categories>
    <category id="1" url="https://example.com/electronics">Електроніка</category>
    <category id="2" parent_id="1" url="https://example.com/electronics/phones">Смартфони</category>
    <category id="3" parent_id="1" url="https://example.com/electronics/laptops">Ноутбуки</category>
    <category id="4" parent_id="2" url="https://example.com/electronics/phones/iphone">iPhone</category>
    <category id="5" parent_id="2" url="https://example.com/electronics/phones/android">Android</category>
</categories>

Пояснення прикладу:

Категорія з id="1" є кореневою (немає parent_id)
Категорії з id="2" та id="3" є дочірніми від категорії Електроніка (мають parent_id="1")
Категорії з id="4" та id="5" є дочірніми від категорії Смартфони (мають parent_id="2")

порада

При створенні структури категорій рекомендується дотримуватися логічної ієрархії. Наприклад, якщо у вас є категорія "Смартфони", її дочірніми категоріями можуть бути "iPhone", "Samsung", "Xiaomi" тощо. Це покращує навігацію та пошук для користувачів.

Порядок категорій у пошуку (`ordering`)

Атрибут ordering задає, в якому порядку показувати блоки категорій у згрупованій видачі пошуку. Він не змінює релевантність товарів і не сортує товари всередині категорії.

<categories>
    <category id="10" ordering="1">Молочні продукти</category>
    <category id="11" parent_id="10" ordering="2">Сири</category>
    <category id="12">Ковбаси</category>
</categories>

Правила:

Це ціле число. Менше число стоїть вище. 0 і від'ємні значення допустимі.
Якщо атрибута немає або значення не є числом, ручного порядку немає. Така категорія йде після категорій із числом, але лише серед категорій з однаковим найкращим балом збігу.
Спершу завжди виграє категорія, у якій є точніший збіг із запитом. ordering вирішує порядок лише коли найкращі товари категорій набрали однаковий бал. Далі, за рівного бала і рівного ordering, враховуються ціна і внутрішній id.
Приклад: три категорії з однаковим найкращим балом і ordering 2, 10 і без атрибута стануть саме в цьому порядку. Якщо в категорії без атрибута є товар із вищим балом, вона все одно буде першою.
Не плутати з order на <attribute>: той атрибут задає порядок фільтра в сайдбарі, а не порядок категорій.
Значення з фіду перезаписує попереднє під час наступного імпорту. Якщо прибрати атрибут, збережений порядок теж зникає. У пошуку зміна з'являється після переіндексації, яка йде слідом за імпортом.

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

Розділ <offers> містить інформацію про кожен товар у вашому каталозі. Кожен товар представлений елементом <offer> з набором полів, що описують його характеристики, ціну, доступність та інші параметри.

Обов'язкові поля

Кожна товарна пропозиція повинна містити мінімальний набір обов'язкових полів для коректної індексації та відображення у пошуку.

<offer id="product123" available="true">
    <name>Назва товару</name>
    <url>https://example.com/product</url>
    <picture>https://example.com/image.jpg</picture>
</offer>

Детальний опис обов'язкових полів:

Поле	Тип	Обов'язкове	Опис
`@id` або `id`	String	Так	Унікальний ідентифікатор товару
`name`	String	Так	Назва товару. Має бути зрозумілою та описовою (рекомендується 50-150 символів).
`url`	String	Так	Повна URL-адреса сторінки товару в інтернет-магазині.
`picture` або `image_url`	String	Так	URL основного зображення товару. Може бути масивом для кількох зображень.

попередження

Всі обов'язкові поля повинні бути заповнені. Відсутність будь-якого з цих полів призведе до того, що товар не буде проіндексований і не відображатиметься у пошуку.

Поле	Тип	Опис	За замовчуванням
`price`	Number	Поточна ціна товару. Крапка як десятковий роздільник. Якщо ціни немає або вона `0` — у віджеті показується «уточнюйте ціну». Товар усе одно імпортується.	`0`
`@available`	String	Необов’язкове. Наявність: `"true"`, `"1"`, `"yes"`. Якщо атрибута немає — товар відображається у наявності. Якщо є — береться значення з параметра.	`true` (якщо атрибута немає)
`@price_range`	String	Вмикає режим діапазону цін *	`false`
`sku`	String	Артикул товару (Stock Keeping Unit). Використовується для унікальної ідентифікації товару в системі обліку.	-
`category_id`	String/Array	ID категорії(й), до якої належить товар. Повинен відповідати id з розділу `<categories>`.	-
`currency_code`	String	Код валюти за стандартом ISO 4217 (наприклад, "UAH", "USD", "EUR").	`"UAH"`
`vendor`	String	Назва бренду/виробника	-
`description`	String	Опис товару	-

Режим діапазону цін

Якщо встановлено @price_range="true", система інтерпретує ціни спеціальним чином:

<old_price> → відображається як "від X ₴"
<price> → відображається як "до Y ₴"
Обидва поля → "від X до Y ₴"

Приклад

<offer available="true" price_range="true">
  <old_price>15999</old_price>
</offer>

Результат у інтерфейсі: (від 15 999 ₴)

Увага

Режим діапазону працює лише при наявності атрибута price_range="true". Без нього <old_price> інтерпретується як стара ціна (з закресленням), а <price> — як поточна.

Додаткові поля

Додаткові поля надають більше можливостей для конфігурації товарів, створення варіантів, додавання міток та атрибутів.

Поле	Тип	Опис
`old_price`	Number	Попередня ціна товару (до знижки). Використовується для відображення строї ціни.
`@group_id`	String	Ідентифікатор групи товарів. Використовується для об'єднання варіантів одного товару (розмір, колір тощо).
`@is_main`	String	Позначає основний товар у групі варіантів: `"true"`, `"1"`, `"yes"`. Застосовується разом з `@group_id`.
`label`	String/Array	Мітки або бейджі товару (наприклад, "Новинка", "Хіт продажів", "-20%").
`keywords`	String	Ключові слова для покращення пошуку, розділені комами.
`attribute`	Array	Масив атрибутів/параметрів товару (розмір, колір, матеріал тощо).

примітка

Поле @group_id дозволяє групувати варіанти одного товару (наприклад, різні кольори або розміри). При цьому один з товарів повинен мати атрибут @is_main="true", який визначатиме основний варіант для відображення.

Атрибути товару

Атрибути дозволяють додавати додаткові характеристики товарів, які можуть використовуватися для покращення пошуку, фільтрації та відображення товарів у результатах пошуку.

Структура атрибута

Кожен атрибут додається у вигляді окремого елементу <attribute> усередині тегу <offer>:

<attribute name="Колір" filter="true">Червоний</attribute>
<attribute name="Розмір">XL</attribute>
<attribute name="Матеріал" filter="true">Бавовна</attribute>

Атрибут	Тип	Опис
`@name`	String	Назва атрибута. Використовується для ідентифікації параметра (наприклад, "Колір", "Розмір", "Матеріал"). Повинна бути зрозумілою та короткою.
`@filter`	String	Чи дозволено використовувати атрибут для фільтрації у пошуку. Допустимі значення: `"true"` (включено), `"false"` (виключено). Якщо не вказано — за замовчуванням вважається `"false"`.
`#text`	String	Значення атрибута (конкретна характеристика товару).

порада

Використовуйте атрибут filter="true" для характеристик, за якими користувачі найчастіше фільтрують товари (колір, розмір, бренд, матеріал тощо). Це покращить користувацький досвід при пошуку.

Приклад вживання

<offer id="12345">
    <name>Ноутбук ASUS ROG Strix G15</name>
    <!-- інші обов'язкові поля -->
    <attribute name="Процесор" filter="true">Intel Core i7-12700H</attribute>
    <attribute name="Оперативна пам'ять" filter="true">16 GB</attribute>
    <attribute name="SSD" filter="true">512 GB</attribute>
    <attribute name="Відеокарта" filter="true">NVIDIA RTX 3060</attribute>
    <attribute name="Діагональ екрана">15.6"</attribute>
    <attribute name="Роздільна здатність">1920×1080 (Full HD)</attribute>
    <attribute name="Операційна система">Windows 11</attribute>
</offer>

попередження

Непідтримувані типи атрибутів: Формат Spefix не підтримує типи даних, які передбачають числа, булеві значення або вибір за допомогою true/false у значеннях атрибутів. Всі значення мають бути текстом. Наприклад, замість:

<attribute name="У наявності">true</attribute>

використовуйте:

<attribute name="Доступність">В наявності</attribute>

Оптимізація

Не використовуйте атрибути для дублювання інформації, яка вже міститься в назві або описі.

<!-- Неправильно -->
<name>Червона футболка</name>
<attribute name="Колір">Червоний</attribute>

<!-- Правильно -->
<name>Футболка з принтом</name>
<attribute name="Колір">Червоний</attribute>

Атрибути повинні додавати додаткову цінність, а не дублюватися.

Мітки товару

Мітки - це візуальні бейджі/теги, які додають до товару додаткову інформацію та відображаються на товарних картках.

Проста мітка (лише текст)

Ви можете додати просту мітку, використовуючи тег <label> з текстом мітки:

<label>Новинка</label>
<label>Розпродаж</label>

Мітка з кольором:

Для міток, які потребують відображення кольору, використовуйте атрибут color з шестнадцятковим кодом кольору:

<label color="#FF0000">Гаряча пропозиція</label>
<label color="#00FF00">Еко-товар</label>

Атрибут	Тип	Обов'язкове	Опис
`color`	String	Ні	Шестнадцятковий код кольору мітки. Якщо не вказано, мітка відображається без кольору.

порада

Мітки з кольором можуть підкреслити важливі акції або характеристики товару. Використовуйте їх для підвищення атрактивності товару на сторінці.

Повний приклад

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

<?xml version="1.0" encoding="UTF-8"?>
<catalog>
    <categories>
        <category id="1" url="https://shop.com/electronics">Електроніка</category>
        <category id="10" parent_id="1" url="https://shop.com/electronics/phones">Смартфони</category>
        <category id="11" parent_id="1" url="https://shop.com/electronics/laptops">Ноутбуки</category>
    </categories>

    <offers>
        <offer id="12345" available="true" group_id="phone-x" is_main="true" price_range="true">
            <name>Смартфон X Pro</name>
            <sku>PHN-X-PRO-BLK</sku>
            <vendor>TechBrand</vendor>
            <category_id>10</category_id>
            <price>17999</price>
            <old_price>15999</old_price> // old_price тут менший, оскільки позначає ціну "від", а не ціну без знижки
            <currency_code>UAH</currency_code>
            <url>https://shop.com/products/smartphone-x-pro</url>
            <picture>https://shop.com/images/phone-x-1.jpg</picture>
            <picture>https://shop.com/images/phone-x-2.jpg</picture>
            <description>Найновіший флагманський смартфон з передовими функціями</description>
            <label color="#FF0000">Новинка</label>
            <label color="#00AA00">Бестселер</label>
            <keywords>смартфон,мобільний,5g,флагман</keywords>

            <attribute name="Колір" filter="true">Чорний</attribute>
            <attribute name="Розмір екрану" filter="true">6.7 дюймів</attribute>
            <attribute name="Оперативна пам'ять" filter="true">12 ГБ</attribute>
            <attribute name="Накопичувач" filter="true">256 ГБ</attribute>
            <attribute name="Батарея">5000 мАг</attribute>
        </offer>

        <offer id="12346" available="true" group_id="phone-x" is_main="false">
            <name>Смартфон X Pro</name>
            <sku>PHN-X-PRO-WHT</sku>
            <vendor>TechBrand</vendor>
            <category_id>10</category_id>
            <price>15999</price>
            <currency_code>UAH</currency_code>
            <url>https://shop.com/products/smartphone-x-pro-white</url>
            <picture>https://shop.com/images/phone-x-white.jpg</picture>

            <attribute name="Колір" filter="true">Білий</attribute>
            <attribute name="Розмір екрану" filter="true">6.7 дюймів</attribute>
            <attribute name="Оперативна пам'ять" filter="true">12 ГБ</attribute>
            <attribute name="Накопичувач" filter="true">256 ГБ</attribute>
        </offer>
    </offers>
</catalog>

Конвенції найменування полів

Для забезпечення сумісності та зручності ми підтримуємо два стилі написання назв полів: snake_case (рекомендований) та camelCase (застарілий, але підтримується для зворотної сумісності).

Рекомендовано (snake_case)	Застаріле (camelCase)
`category_id`	`categoryId`
`currency_code`	`currencyId`
`old_price`	`oldprice`
`image_url`	`picture`
`sku`	`vendorCode`

порада

Ми наполегливо рекомендуємо використовувати стиль snake_case у нових інтеграціях, оскільки він є більш читабельним і відповідає сучасним стандартам. Застарілий стиль camelCase може бути видалений у майбутніх версіях.

Валюти

Якщо ваш фід містить ціни в різних валютах, необхідно оголосити підтримувані валюти та їхні курси відносно гривні в елементі <currencies> у корені <catalog>. Код валюти в елементі <offer> (currency_code) повинен відповідати одному з оголошених id.

Структура

<currencies>
  <currency id="UAH" rate="1"/>
  <currency id="USD" rate="41.5"/>
  <currency id="EUR" rate="44.2"/>
</currencies>

Атрибут	Тип	Обов'язкове	Опис
`@id`	String	Так	Код валюти за стандартом ISO 4217 (`UAH`, `USD`, `EUR` тощо).
`@rate`	Number	Так	Курс валюти відносно гривні (UAH). Для UAH завжди `1`.

попередження

Якщо в <offer> вказано <currency_code>USD</currency_code>, але валюта USD не оголошена в <currencies>, ціна товару може бути оброблена некоректно.

Приклад у контексті каталогу

<?xml version="1.0" encoding="UTF-8"?>
<catalog>
    <currencies>
        <currency id="UAH" rate="1"/>
        <currency id="USD" rate="41.5"/>
        <currency id="EUR" rate="44.2"/>
    </currencies>
    <categories>
        ...
    </categories>
    <offers>
        <offer id="1" available="true">
            <name>Товар в USD</name>
            <price>99.99</price>
            <currency_code>USD</currency_code>
            ...
        </offer>
    </offers>
</catalog>

Статус наявності

Атрибут @available не обов’язковий.

Якщо його немає — товар відображається у наявності.
Якщо він є — береться значення з параметра. Товар вважається доступним, якщо значення дорівнює "true", "1" або "yes".

<!-- Без атрибута — товар у наявності -->
<offer id="123">...</offer>

<!-- Явно в наявності -->
<offer id="123" available="true">...</offer>

<!-- Не в наявності -->
<offer id="123" available="false">...</offer>

обережно

Підтримка тега <presence> вважається застарілою і може бути видалена в майбутніх версіях. Рекомендується використовувати атрибут @available. Тег <presence> приймав такі текстові значення для позначення наявності:

"в наличии" (російською)
"в наявності" (українською)
"available" (англійською)
"є в наявності" (українською)
"есть в наличии" (російською)

Приклад застарілого формату:

<offer id="123">
    <presence>в наявності</presence>
    ...
</offer>

Формат Spefix (рекомендовано)

Коренева структура

Рекомендована структура

Альтернативна застаріла Структура

Структура категорій

Поля категорії

Приклад

Порядок категорій у пошуку (`ordering`)

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

Обов'язкові поля

Рекомендовані поля

Режим діапазону цін

Приклад

Додаткові поля

Атрибути товару

Структура атрибута

Оптимізація

Мітки товару

Проста мітка (лише текст)

Мітка з кольором:

Повний приклад

Конвенції найменування полів

Валюти

Структура

Приклад у контексті каталогу

Статус наявності

Коренева структура​

Рекомендована структура​

Альтернативна застаріла Структура​

Структура категорій​

Поля категорії​

Приклад​

Порядок категорій у пошуку (ordering)​

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

Обов'язкові поля​

Рекомендовані поля​

Режим діапазону цін​

Приклад​

Додаткові поля​

Атрибути товару​

Структура атрибута​

Оптимізація​

Мітки товару​

Проста мітка (лише текст)​

Мітка з кольором:​

Повний приклад​

Конвенції найменування полів​

Валюти​

Структура​

Приклад у контексті каталогу​

Статус наявності​

Коренева структура

Рекомендована структура

Альтернативна застаріла Структура

Структура категорій

Поля категорії

Приклад

Порядок категорій у пошуку (`ordering`)

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

Обов'язкові поля

Рекомендовані поля

Режим діапазону цін

Приклад

Додаткові поля

Атрибути товару

Структура атрибута

Оптимізація

Мітки товару

Проста мітка (лише текст)

Мітка з кольором:

Повний приклад

Конвенції найменування полів

Валюти

Структура

Приклад у контексті каталогу

Статус наявності