Правила заполнения XML-файла

XML-файл (фид) разработан для описания товарных предложений продавца. Он помогает решать две задачи:

  • добавлять товары и обновлять информацию о них;
  • управлять загрузкой ассортимента в личный кабинет, ценами и остатками.

XML-документ с описанием товаров, то есть XML-фид, размещается на веб-сервере продавца, а система Мегамаркета получает из него информацию.

Правила для XML-файла

1. Товарный фид должен быть размещён на отдельной странице http/https сайта продавца или на любом другом стороннем хосте.

Фид не должен находиться в облачных хранилищах (Яндекс. Диск, Google.Диск).

2. Максимальный объём файла составляет 500 МБ.

3. Нельзя менять структуру файла. Требования к его заполнению должны быть соблюдены.

4. Минимальное значение для всех обязательных элементов – 1 символ, не считая пробелы и специальные знаки.

5. Фид должен быть представлен в кодировке UTF-8.

6. Файл XML должен соответствовать общим требованиям стандарта XML.

7. XML-заголовок файла <?xml> должен начинаться с первой строки, с 0-го символа.

8. Все атрибуты элементов файла должны быть указаны в двойных кавычках " ".

9. Нельзя использовать непечатаемые символы с ASCII-кодами от 0 до 31, за исключением знаков с кодами 9, 10, 13 — табуляция, перевод строки, возврат каретки.

10. Символы ", &, >, <, ' нужно заменять на соответствующие коды:

Символ в тексте
Код для XML-файла Мегамаркета
"
&quot;
&
&amp;
>
&gt;
<
&lt;
'
&apos;

Как заполнить XML-файл

Все элементы (теги) не должны повторяться, если не указано иное.

Заголовок

<?xml version="1.0" encoding="UTF-8"?>

Должен быть в любом XML-файле. Заголовок не может дублироваться.

Он занимает первую строку и начинается с нулевого символа.

Кодировка обязательно должна быть UTF-8.

Корневой элемент <yml_catalog>

Должен быть в любом XML-файле. В качестве корневого используется элемент <yml_catalog> с атрибутом date.

В атрибуте укажите дату и время, на которые актуальны данные в файле.

Дату и время нужно отметить, согласно стандарту RFC 3339. Обязательно указывайте часовой пояс. Он отсчитывается от Всемирного координированного времени (UTC).

Например, время по Москве нужно отметить так:

<yml_catalog date="2022-05-12t14:37+03:00">

Элемент <shop>

Должен быть в любом XML-файле. Прописывается в элементе <yml_catalog> один раз. Должен содержать данные о магазине, которому предназначен этот фид.

Список параметров, входящих в <shop>

1. Categories

Элемент с описанием категорий товаров. Каждая категория описывается в отдельном элементе category.

Наличие в файле обязательно.


Элементы, входящие в Categories:


category

Категория товара.

Повторяться может.

category Id

Id категории из системы продавца. Должен быть уникальным в рамках всех категорий.

Тип данных:

  • целое число >0;
  • длина до 50 символов включительно.

Наличие в файле обязательно.

category name

Название категории.

Тип данных: длина до 512 символов включительно.

Наличие в файле необязательно.

category parentId

Id родительской категории продавца. Используется, если категории делятся на подкатегории.

Тип данных:

  • целое число >0;
  • длина до 50 символов включительно;
  • parentId должен быть равен category Id родительской категории;

Наличие в файле необязательно.


Пример
<categories>
    <category id="1"> Детские товары </category>
    <category id="2" parentId="1"> Детские игрушки </category>
    <category id="3" parentId="1"> Конструкторы </category>
</categories>


2. Shipment-options

Элемент с описанием параметров отгрузки офферов продавцом. Эти параметры будут применены ко всему ассортименту товаров.

Наличие в файле необязательно.


Элементы, входящие в Shipment-options:

option days

Количество рабочих дней для доставки заказа.

Тип данных: целое число от 1 до 43 включительно.

Наличие в файле обязательно, если есть shipment-options.

option order-before

Время, до которого в этот день принимаются заказы для доставки.

Тип данных: целое число от 1 до 23.

Наличие в файле обязательно, если есть shipment-options.


Пример
<shipment-options>
    <option days="1" order-before="15"/>
</shipment-options>
3. Offers

Список товаров магазина. Может присутствовать только в единственном экземпляре. Содержит элементы offer с описанием товара

Наличие в файле обязательно.

4. Offer

Описание товара. Каждый товар описывается отдельно.

Повторяться может.

Элементы, входящие в Offer:


offer id

Должен соответствовать артикулу товара в системе учёта заказов продавца. Товары, у которых несколько цветов, размеров и других отличий, должны записываться с разным id.

Тип данных:

  • длина до 80 символов включительно;
  • не должно быть пробелов.

Наличие в файле обязательно.

Пример
<offer id="158" available="true">


offer name

Название товара. Может присутствовать только в единственном экземпляре.

Тип данных: длина до 512 символов включительно.

Наличие в файле необязательно.

Пример
<name> Стиральная машина Indesit SB 185 </name>



available

Показывает доступность конкретного товара:

  • true - доступен для продажи;
  • false - недоступен для продажи.

Если доступность не указана, система по умолчанию пропишет true.

Наличие в файле необязательно.

Пример
<offer id="158" available="true">


url

Ссылка на страницу товара в магазине продавца.

Тип данных: длина до 512 символов включительно.

Наличие в файле необязательно.

Пример
<url> http://www.test.ru/158.html </url>



price

Цена товара.

Тип данных:

  • целое число от 1 до 99 999 999 включительно;
  • по умолчанию округляется до целых значений.

Наличие в файле обязательно.

Пример
<price> 18500 </price>


oldprice

Стоимость до скидки. Зачеркнута на витрине как старая цена.

Тип данных:

  • целое число >=0;
  • по умолчанию округляется до целых значений;
  • максимальное допустимое значение 99 999 999.

Наличие в файле необязательно.

Пример
<oldprice> 25500 </oldprice>



categoryId

Id категории продавца, в которую входит данный товар. Может присутствовать только в единственном экземпляре.

Тип данных:

  • целое число >0;
  • длина до 50 символов включительно.

Наличие в файле обязательно.

Пример
<categoryId> 1293 </categoryId>


picture

Ссылка на изображение товара. Ссылку на основное изображение необходимо указывать первой. А после неё - дополнительные изображения.

Тип данных: длина до 512 символов включительно.

Наличие в файле необязательно.

Пример
<picture> http://www.test.ru/1580.jpg </picture>



vat

Содержит значение ставки НДС для товара.

Тип данных:

Возможные значения

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

1
VAT_20
3
VAT_20_120

20%

2
VAT_10
4
VAT_10_110

10%
VAT_77%
VAT_55%
6
VAT_0		0%

5
NO_VAT

Без НДС
Пример
<vat> VAT_10 </vat>


model

Модель товара.

Тип данных: длина до 512 символов включительно.

Наличие в файле необязательно.

Пример
<model> Indesit SB 185 </model>



vendor

Бренд товара.

Тип данных: длина до 512 символов включительно.

Наличие в файле необязательно.

Пример
<vendor> Indesit </vendor>


vendorCode

Артикул товара.

Тип данных: длина до 512 символов включительно.

Наличие в файле необязательно.

Пример
<vendorCode> 12345678 </vendorCode>



description

Описание товара.

Тип данных: длина до 3000 символов включительно.

Наличие в файле необязательно.

Пример
<description> Очень хорошая стиральная машина </description>


barcode

Штрих-код в формате EAN.

Тип данных:

  • целое число 8, 12 или 13 символов;
  • должен находиться за пределами диапазона 20xxxxxxxxxxxx;
  • первые 2 цифры не должны быть равны 20 в 13-цифровом баркоде.

Наличие в файле необязательно.

Пример
<barcode> 1234567890 </barcode>



shipment-options

Элемент с описанием параметров отгрузки данного товара.

Наличие в файле необязательно.


Элементы, входящие в shipment-options:

shipment-options option days

Количество дней, за которое произойдёт отгрузка заказа конкретного товара.

Тип данных: целое число от 1 до 43 включительно.

Наличие в файле обязательно при наличии shipment-options.

shipment-options option order-before

Время, до которого принимаются заказы для отгрузки.

Тип данных: целое число от 1 до 23.

Наличие в файле обязательно при наличии shipment-options.


Пример
<shipment-options>
	<option days="1" order-before="15"/>
</shipment-options>



outlet

Данные по остатку товара и склада.

Наличие в файле обязательно, если планируете передавать остатки.


Элементы, входящие в outlet:

outlet id

Идентификатор склада, который указан в разделе Логистика → Склад и доставка → поле «ID склада».

Тип данных: длина до 200 символов включительно.

Наличие в файле обязательно при наличии outlet.

outlet instock

Количество товара на складе в шт.

Тип данных:

  • целое число >= 0;
  • максимальное допустимое значение - 100 000.

Наличие в файле необязательно при наличии outlet.


Пример
<outlets >
	<outlet id="1" instock="50" price="15458" oldprice="500000"/>
</outlets >

Пример заполненного XML-файла

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2022-01-02 10:00+03:00">
	<shop>
		<categories>
			<category id="1"> Детские товары </category>
			<category id="2" parentId="1"> Детские игрушки </category>
			<category id="3" parentId="1"> Конструкторы </category>
		</categories>
		<shipment-options>
			<option days="1" order-before="15"/>
		</shipment-options>
		<offers>
			<offer id="158" available="true">
				<url> http://www.test.ru/158.html </url>
				<name> Indesit SB 185</name>
				<price> 18500 </price>
				<oldprice> 25500 </oldprice>
				<categoryId> 1293 </categoryId>
				<picture> http://www.test.ru/1580.jpg </picture>
				<vat> 2 </vat>
				<shipment-options>
					<option days="1" order-before="15"/>
				</shipment-options>
				<vendor> Indesit </vendor>
				<vendorCode> 12345678 </vendorCode>
				<barcode> 7564756475648 </barcode>
				<model> Indesit SB 185 </model>
				<description> Indesit SB 185 </description>
				<outlets>
					<outlet id="1" instock="50"/>
				</outlets >
			</offer>
		</offers>
	</shop>
</yml_catalog>