Вимоги до XML(YML)

Загальні вимоги

Файл повинен мати кодування UTF-8.
Під час формування XML-файлу зверніть увагу на максимальну довжину окремих полів та вимоги до їхнього формату.
Всі теги повинні бути закритими. Наприклад:

<currencies>
    ...
</currencies>

або

<currency id="USD" rate="35"/>

Список обов’язкових елементів

Кожен із цих елементів має бути присутній у XML-файлі.

yml_catalog — кореневий тег XML-файлу. Містить всю інформацію про каталог товарів.
shop — містить інформацію про магазин та його товари.
currencies — містить перелік валют, які використовуються для зазначення цін у файлі.
offers — містить список товарних пропозицій продавця.
categories — містить список категорій продавця. Атрибут sy_code — код відповідної категорії Synthetic.

Опис можливих тегів, атрибутів та значень у `<offer>...</offer>`

offer — обов’язковий елемент, який описує окрему товарну пропозицію.
Повинен містити атрибути:
- id — ідентифікатор товарної пропозиції. Має бути унікальним у межах файлу, до 100 символів.
- available — наявність пропозиції:
  - true — товар є в наявності;
  - false — товару немає в наявності.
name / name_ua / name_ru — обов’язковий елемент. Містить назву товару, до 500 символів для кожного поля. Іноземна мова необовʼязкова.
vendor — обов’язковий елемент. Містить назву бренду товару, до 100 символів.
vendorCode — код виробника товару.
url — посилання на сторінку товару.
price — обов’язковий елемент. Містить поточну ціну товару.
state — стан товару. Можливі значення:
- new — новий;
- refurbished — відновлений;
- discount — уцінка;
- used_perfect — Б/В, ідеальний;
- used_well — Б/В, хороший;
- used_satisfy — Б/В, задовільний.
stock_quantity або quantity — доступна кількість товару.
picture — обов’язковий елемент. Містить посилання на зображення товару. Підтримуються формати: PNG, JPEG, WebP. Для товарів зі станом «Уцінка», «Б/В» або «Відновлений» зображення з цього тегу додаються до фотографій пропозиції під час її створення. Максимальний формат — до 512 символів для одного посилання; до 15 зображень.
description — опис товару. Вміст тегу повинен бути огорнутий у <![CDATA[опис товару]]> для коректного сприйняття та відображення спеціальних символів.
param — значення характеристики товару. Тег повинен містити відповідні атрибути для передачі характеристики.

Вимоги до тегу `SKU` (`offer/@id`)

Значення offer/@id використовується як SKU пропозиції.

Синхронізація та оновлення даних пропозиції відбуваються саме за значенням SKU.
Максимальна довжина / формат до 100 символів.
Значення SKU повинно бути унікальним у межах одного продавця.
Використання однакових SKU у кількох товарах або різних файлах синхронізації може призвести до некоректного оновлення даних та перезапису інформації між пропозиціями.
Після першої синхронізації не рекомендується змінювати значення SKU, оскільки це може призвести до створення нової пропозиції або втрати зв’язку з існуючою.

Важливо: якщо товар уже синхронізований із Synthetic, не змінюйте його SKU (offer/@id) без необхідності.

Опис товару

Для передачі опису товару можна використовувати такі теги:

description — загальний опис товару. Якщо в XML-файлі вказано лише цей тег, його вміст буде використовуватися як україномовний опис (description_ua).
description_ua — опис товару українською мовою.
description_ru — опис товару іноземною мовою.

Правила використання

Якщо вказано тільки description, його вміст буде використано як description_ua.
Якщо вказано description_ua, саме цей тег використовується для передачі україномовного опису товару.
Якщо вказано description_ru, його вміст використовується для передачі опису іноземною мовою.
Для передачі опису двома мовами можна одночасно використовувати description_ua та description_ru.
Вміст тегів опису повинен бути огорнутий у <![CDATA[...]]> для коректного сприйняття та відображення спеціальних символів і HTML-розмітки.

Дозволені HTML-теги всередині description, description_ua та description_ru

Тег	Для чого використовується	Приклад
`br`	Перенесення тексту на новий рядок	`<br>`
`b`	Виділення тексту жирним	`<b>Важливо</b>`
`strong`	Виділення важливого тексту жирним	`<strong>Увага!</strong>`
`p`	Створення окремого абзацу	`<p>Опис товару</p>`
`i`	Виділення тексту курсивом	`<i>Примітка</i>`
`em`	Виділення тексту курсивом з акцентом	`<em>Важлива інформація</em>`
`ul`	Створення маркованого списку	`<ul>...</ul>`
`ol`	Створення нумерованого списку	`<ol>...</ol>`
`li`	Створення окремого пункту списку	`<li>Характеристика</li>`
`h1`	Заголовок 1-го рівня	`<h1>Назва</h1>`
`h2`	Заголовок 2-го рівня	`<h2>Особливості</h2>`
`h3`	Заголовок 3-го рівня	`<h3>Характеристики</h3>`
`h4`	Заголовок 4-го рівня	`<h4>Комплектація</h4>`
`h5`	Заголовок 5-го рівня	`<h5>Додаткова інформація</h5>`
`h6`	Заголовок 6-го рівня	`<h6>Примітка</h6>`

Приклад опису з використанням HTML-тегів:

<description_ua>
<![CDATA[
<p><strong>Основні характеристики:</strong></p>
<ul>
    <li>Діагональ — 14"</li>
    <li>Оперативна пам'ять — 8 ГБ</li>
    <li>SSD — 512 ГБ</li>
</ul>
]]>
</description_ua>

Внутрішні теги Synthetic (`sy_`)

Внутрішні теги Synthetic призначені тільки для передачі даних на маркетплейс Synthetic.

При їх використанні до кореневого тегу yml_catalog потрібно додати атрибут.

Доступні внутрішні теги:

sy_spc — код товару, до якого автоматично буде прив’язана товарна пропозиція. Максимальна довжина — до 8 символів.
sy_warranty — термін гарантійного обслуговування. Вказується кількість місяців.
sy_price_old — ціна без знижки (стара ціна). На маркетплейсі відображається як перекреслена ціна під поточною.
sy_delivery_policy — політика доставки. Потрібно вказати ідентифікатор політики. Максимальна довжина — UUID: 36 символів із дефісами або 32 символи без дефісів.
sy_offer_description_ua та sy_offer_description_ru — опис пропозиції українською та іноземною мовою. Дані теги використовуються виключно для товарів, які мають стан "Уцінка", "Відновлений", "Б/В". А також, у випадку, якщо Вам необхідно додати якусь особливу інформацію щодо умов оплати (передоплати). Максимальна довжина — до 2 200 символів для кожної мови.

Параметри та атрибути товару (`param`)

Тег param використовується для передачі характеристик товару, наприклад: колір, об’єм пам’яті, вага, діагональ тощо.

Щоб характеристика була правильно співставлена з відповідним атрибутом на Synthetic, у тегу потрібно вказати відповідні коди.

Властивості тегу param

name — назва атрибуту. Це Ваша внутрішня назва характеристики. Для синхронізації не використовується.
sy_attr_code — код атрибуту. За цим кодом параметр співставляється з відповідним атрибутом вказаного типу товару на Synthetic.
sy_value_code — код значення. Використовується для атрибутів, які мають заздалегідь визначений список можливих значень. За цим кодом значення співставляється з відповідним значенням на Synthetic.
sy_unit_code — код одиниці виміру. Використовується для атрибутів, для яких передбачені одиниці виміру.

Як вказати декілька значень одного атрибуту?

Якщо атрибут підтримує декілька значень, його можна вказати в XML-файлі декілька разів — окремим тегом param для кожного значення.

Наприклад, якщо товар доступний у трьох кольорах — чорному, білому та синьому:

<param name="Колір" sy_attr_code="AND-123456" sy_value_code="VLD-111111">Чорний</param>
<param name="Колір" sy_attr_code="AND-123456" sy_value_code="VLD-222222">Білий</param>
<param name="Колір" sy_attr_code="AND-123456" sy_value_code="VLD-333333">Синій</param>

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

Важливо

Якщо sy_attr_code не вказано, атрибут не буде завантажено.
Для спискових атрибутів рекомендується обов’язково вказувати sy_value_code. Якщо код значення не вказано, товар не потрапить у відповідний фільтр категорії.
Для безспискових атрибутів, наприклад ваги або довжини, sy_value_code не передбачений.
Якщо атрибут має одиницю виміру, її можна передати через sy_unit_code.

Зразок правильно складеного XML

Нижче наведено приклад XML-файлу з правильним форматуванням та відступами.

<yml_catalog xmlns:sy="http://base.synthetic.ua/ns/1.0" date="2025-12-21 09:32">
    <shop>
        <name>Інтернет магазин "Your-Shop"</name>
        <company>Інтернет магазин "Your-Shop"</company>
        <url>https://yourshop.ua/</url>

        <currencies>
            <currency id="UAH" rate="1"/>
            <currency id="USD" rate="42.70"/>
            <currency id="EUR" rate="CB"/>
        </currencies>

        <categories>
            <category id="1" sy_code="C320580">Ноутбуки</category>
            <category id="2" sy_code="C337965">Смартфони</category>
            <category id="3" sy_code="C441077">Планшети</category>
        </categories>

        <offers>
            <offer id="648053662" available="true">
                <categoryId>1</categoryId>
                <sy_spc>P06705ZH</sy_spc>
                <price>9995.00</price>
                <sy_price_old>12995.00</sy_price_old>
                <stock_quantity>10</stock_quantity>
                <sy_warranty>12</sy_warranty>
                <sy_delivery_policy>f302334549b84230a052bcbb483542a3</sy_delivery_policy>
                <state>new</state>
                <currencyId>UAH</currencyId>
                <name>Ноутбук 14" Lenovo V14-IGL Intel Celeron N4020 RAM 4GB SSD 128GB Windows 11</name>
                <vendor>Lenovo</vendor>
                <sy_type>PTD-00103</sy_type>

                <picture>https://cdn.synthetic.com.ua/media/assets/images/9/a/4/d/7/6/9/8/9/b/4/6/4/2/4/e/full/9a4d76989b46424eb94fdae8d2b89a24.png</picture>
                <picture>https://cdn.synthetic.com.ua/media/assets/images/2/f/a/4/7/d/8/3/d/3/5/d/4/6/6/5/full/2fa47d83d35d4665a671c2c7837a839e.png</picture>

                <description_ru>
                    <![CDATA[
                    Опис товару іншою мовою
                    ]]>
                </description_ru>

                <description_ua>
                    <![CDATA[
                    <p>Екран 14" TN (1920 x 1080) Full HD / Intel Celeron N4020 1.1 - 2.8 ГГц (2/2 ядра) / RAM 4 ГБ DDR4 / SSD 128 ГБ / Intel UHD Graphics 600 / Wi-Fi 5 / Bluetooth 4.2 / TPM модуль / Windows 11 / 1.6 кг</p>

                    <p><strong>Практичний мобільний ноутбук</strong></p>

                    <p>Lenovo V14-IGL важить всього 1,6 кг, тому його зручно носити на аудиторні заняття або приймати в ділові поїздки. З цим ноутбуком можна до шостої години не замислюватися про пошуки розетки.</p>
                    ]]>
                </description_ua>

                <param name="Вид" sy_attr_code="AND-533594" sy_value_code="VLD-64251"></param>
                <param name="Об'єм SSD" sy_attr_code="AND-534870" sy_value_code="VLD-5031075">128 гб</param>
                <param name="Процесор" sy_attr_code="AND-497020" sy_value_code="VLD-75698">Intel Celeron N4020</param>
                <param name="Вага" sy_attr_code="AND-00001" sy_value_code="VLD-80399">1,6 кг</param>
            </offer>
        </offers>
    </shop>
</yml_catalog>

Продавцям

Вимоги до XML(YML)

Загальні вимоги

Список обов’язкових елементів

Опис можливих тегів, атрибутів та значень у <offer>...</offer>

Вимоги до тегу SKU (offer/@id)