Структура XML-файла партнерского интернет-магазина

Каталог товаров интернет магазинов партнерской программы PowerPartners формируется на основе автоматически обновляемого файла shop.xml из каталога products. Для обеспечения уникальности текстов описывающих продукцию в вашем интернет магазине и увеличения его индивидуальности предусмотрена возможность переопределения параметров продукции. О том как это сделать Вы можете прочитать в статье Кастомизация XML-фида. Цель создания этого документа — предоставить всем заинтересованным лицам справочные материалы, описывающие содержание файлов shop.xml.

С технической точки зрения файлы shop.xml должны отвечать стандартам предъявляемым к структуре XML файлов. Поэтому нельзя забывать, что файл обязан начинаться с указания версии XML и кодировки в которой хранятся данные.

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

Второе требование предъявляемое к любому XML документу: должен быть определен единственный корневой узел (нода), в нашем случае речь о ноде shop. Это означает, что все данные которые мы хотим получить или изменить будут являться потомками узла shop

В файле products/shop.xml потомков корневого узла shop можно разделить на три группы

• contacts - определяющие контактные данные
• deliveries - определяющие возможные способы доставки и их параметры
• products - содержащие список товаров интернет магазина

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

<shop>
	<contacts>
	 ...
	</contacts>

	<deliveries>
	 ...
	</deliveries>
	
	<products>
	...
	</products>
</shop>

В дальнейшем для того чтобы сконцентрироваться на главном будем опускать перечисление всех элементов XML документа и будем указывать только родительские узлы относительно которых определены описываемые данные. В конце статьи будет приведена вся структура XML-файла, чтобы ещё раз закрепить все аспекты, описанию которых, посвящен этот документ.

В первую очередь будут описаны параметры, описывающие характеристики конкретного товара, а затем будет освещён раздел со способами доставки и параметрами которые в нём определены. Порядок следования этих узлов не имеет значения, но будет не лишним упомянуть, что в файлах которые интернет магазины получает с сервера партнерской программы первым идёт узел <deliveries> а за ним узел <products>, что ни как не влияет на работоспособность системы.

Каталог продукции

Рассмотрим более внимательно ту часть XML документа products/shop.xml, которая описывает каждый товар интернет магазина и разберёмся какие характеристики в ней определены.

Каждый товар обособлен в отдельный узел product для которого всегда определяется уникальный атрибут code. Критически важно соблюдать точное соответствие кода продукта если вы хотите переопределить его характеристики. Все характеристики, определяющие принадлежность данного товара к той или иной категории являются потомками для узла product. Код продукта не отображается на страницах интернет магазина. Ниже в таблице перечислены базовые характеристики товара и дана расшифровка их возможных значений

Узел	Возможные значения	Описание
category	Стабилизатор напряжения Бензогенератор Инвертор	Значение узла определяет категорию, к которой относится товар
trademark	Sassin Энергия UPower Voltron Etalon	Наименование производителя продукта
series	CHBT PCH ACH APC RDR CLASSIC	Код серии (линейки) к которое принадлежит товар.
model	СНВТ-500/1	Значение этого параметра определяет наименование товара, которое отображается в описании товара в магазине
price	{целое число}	Цена на товар в рублях. В параметрах базового магазина настроено ежедневное обновление информации о цене и наличие товаров. Поставщиком установлены цены в долларах США и ежедневно производится пересчёт и обновление цен в зависимости от колебаний курса ЦБ РФ
description	{текст}	Это короткое описание продукта, которое отображается на титульной странице интернет магазина в каталоге, а так же в результатах поиска. Обратите внимание на то, что объём текста содержащийся в этом узле существенно влияет на отображение товара в каталоге для шаблонов "классик" и "оранж" которые предоставляет партнерская программа.
type	0	Генераторы синхронные
	1	Стабилизатор электромеханического типа
	2	Стабилизатор релейного типа
	3	Стабилизатор тиристорного типа
	4	Генераторы инверторные
	5	Стабилизатор инверторный
	6	Зарядное устройство
	7	Онлайн ИБП
	8	Онлайн ИБП со встроенными АКБ
	9	Другое
case	0	Стандартное (напольное) исполнение
	1	Возможность крепления на стене
	2	Автомобильный инвертор
	3	Универсальное (напольное или настенное)
	4	Другое
phases	1 3	Число фаз
power	{целое число}	Полная мощность оборудования указанная в вольт-амперах (ВА) или значение основной характеристики для иных товаров
weight	{вещественное число}	Вес товара (дробная часть отделяется точкой)
volume	{вещественное число}	Объём товара в м3 (дробная часть отделяется точкой, 4 знака после запятой)
image	voltron-rsn-10000h.jpg	Название файла изображения товара отображаемого в описании товара
image_big	voltron-rsn-10000h_big.jpg	Название файла увеличенного изображения товара отображаемого в подробном описании товара при нажатии на исходное маленькое изображение
image_big_2 ... image_big_6	voltron-rsn-10000h_big_2.jpg	Дополнительные файлы изображений товара увеличенного формата. Мелкоразмерных изображений для дополнительных фотографий не предусмотрено Необязательные. Могут отсутствовать
html	svc-30000-3.htm	Название файла содержащего полное описание товара, включающее расширенные технические данные и ссылки на сертификаты и другие доступные документы
available		Наличие товара на складе
	0	товар отсутствует
	1	товар в наличие
bestseller		Признак приоритетности товара. Определяет нужно ли выводить товар на титульной странице магазина
	0	не отображать на титульной странице магазина
	1	отображать на титульной странице
characteristics	<chracteristic>	Дополнительные характеристики отображаемые в виде таблицы в кратком описании товара
chracteristic	Дополнительные характеристики отображаемые в виде таблицы в кратком описании товара <chracteristic name="{text}" value="{text}">
	name={текст}	расшифровка значения характеристики
	value={текст}	значение характеристики
barcode	{13 цифр}	Штрих-код товара (EAN-13)
article	Е0101-0041	Артикул
certificate	pages/img/energy-2015-cert.jpg	Имя файла с сертификатом (РосТест). Полный путь относительно корня магазина.
manual	pages/img/energy_hybrid_passport.pdf	Имя файла с техническим паспортом изделия. Полный путь относительно корня магазина.

В результате каждый товар в XML-файле представлен в следующем виде:

...
 <products>

  <product code="svc-500">
    <category>Стабилизатор напряжения</category>
    <trademark>Sassin</trademark>
    <model>SVC-500</model>
    <price>1780</price>
    <description>Бытовой стабилизатор переменного напряжения. Предназначен для питания различной бытовой техники и защиты от перепадов напряжения и сетевых помех.</description>
    <characteristics>
      <chracteristic name="Напряжение входа, В" value="150 - 260" />
      <chracteristic name="Напряжение выхода, В" value="220 ± 3%" />
      <chracteristic name="Мощность, кВА" value="0.5" />
    </characteristics>
    <type>1</type>
    <case>0</case>
    <phases>1</phases>
    <power>500</power>
    <weight>4</weight>
    <image>svc-500.jpg</image>
    <image_big>svc-500_big.jpg</image_big>
    <html>svc-500.htm</html>
    <available>1</available>
    <bestseller>1</bestseller>
    <barcode>4607110188022</barcode>
    <certificate>pages/img/energy-2015-cert.jpg</certificate>
    <manual>pages/img/energy_hybrid_passport.pdf</manual>
  </product>
	
  <product code="svc-1000">
  ...
	
 </products>
...

Помните, что вы можете переопределить и дополнить эти характеристики (кроме характеристики price) и таким образом прибавить индивидуальности вашей торговой площадке.

Доставка

В файле products/shop.xml нода deliveries содержит данные о способах доставки. Наша партнерская программа постоянно развивается и старается обеспечить клиентам интернет магазинов большое число способов оплаты и доставки. В связи с этим структура построена таким образом, чтобы по мере добавления новых способов оплаты и доставки партнеры автоматически получали в своих магазинах не только оперативную информацию о продукции и ценах на неё, но и позволяли обслужить максимальное количество клиентов. Так например появление оплаты по безналичному рассчёту и доставка в регионы транспортной компанией привело к тому, что география успешно выполненных заказов существенно расширилась.

Информация в данном разделе описывает два возможных на текущий момент способа доставки: курьером <delivery code="0"> и самовывоз <delivery code="1">. В реальности существует возможность заказать товар в другой город средствами транспортной компании. В этом случае клиент выбирает доставку курьером. Обрабатывая заказ менеджер связывается с клиентом и сообщает варианты доставки заказанного оборудования и способ оплаты заказа. Для оплаты заказа с отправкой его транспортной компанией возможна отгрузка товара только при условии его оплаты по безналичному расчету или при помощи WebMoney платежа.

Узлы delivery содержат потомков наименований:

Узел	Возможные значения	Описание
name	Курьер	Название способа доставки (используется в форме оформления заказа)
	Самовывоз
price	400	Стоимость доставки выбранным способом по Москве в пределах МКАД
	0
free_limit	10000	Сумма заказа (в рублях), превысив которую доставка в пределах МКАД осуществляется бесплатно
extra_pay	20	рублей за километр. Параметр определяет стоимость доставки в Подмосковье в зависимости от удалённости от МКАД

В результате блок описывающий возможные способы доставки имеет вид:

...
  <deliveries>
    <delivery code="0">
      <name>Курьер</name>
      <price>400</price>
      <free_limit>10000</free_limit>
      <extra_pay>20</extra_pay>
    </delivery>
    <delivery code="1">
      <name>Самовывоз</name>
      <price>0</price>
    </delivery>
</deliveries>
...

Собрав воедино информацию о доставке и о продукции, получаем вот такой документ:

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

<shop>
  <deliveries>
  
    <delivery code="0">
      <name>Курьер</name>
      <price>400</price>
      <free_limit>10000</free_limit>
      <extra_pay>20</extra_pay>
    </delivery>
	
    <delivery code="1">
      <name>Самовывоз</name>
      <price>0</price>
    </delivery>
	
  </deliveries>
	
  <products>

    <product code="svc-500">
      <category>Стабилизатор напряжения</category>
      <trademark>Sassin</trademark>
      <model>SVC-500</model>
      <price>1780</price>
      <description>Бытовой стабилизатор переменного напряжения. Предназначен для питания различной бытовой техники и защиты от перепадов напряжения и сетевых помех.</description>
      <characteristics>
        <chracteristic name="Напряжение входа, В" value="150 - 260" />
        <chracteristic name="Напряжение выхода, В" value="220 ± 3%" />
        <chracteristic name="Мощность, кВА" value="0.5" />
      </characteristics>
      <type>1</type>
      <case>0</case>
      <phases>1</phases>
      <power>500</power>
      <weight>4</weight>
      <image>svc-500.jpg</image>
      <image_big>svc-500_big.jpg</image_big>
      <html>svc-500.htm</html>
      <available>1</available>
      <bestseller>1</bestseller>
      <barcode>4607110188022</barcode>
    </product>
	
    <product code="svc-1000">
    ...
	
  </products>
  
</shop>

Контактные данные

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

Например, если в XML содержатся такие данные:

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

<shop>
  ...
  <contacts>
    <phone>+7(495)255-19-70</phone>
    <email>example@mail.com</email>
    <skype>skypeaccname</skype>
    <address>ул.Стромынка, д.12</address>
    <telegram>https://t.me/+7XXXXXXXXXX</telegram>
    </contacts>
  ...
</shop>

То, в каждый шаблон скина будут передаваться переменные PHONE, EMAIL, SKYPE, ADDRESS и TELEGRAM с соответсвующими значениями. И эти переменные можно использовать в шаблонах при помощи конструкции TMPL_VAR.

Особым образом обрабатывается нода //contacts/phone, её одержимое будет разобрано, и в дополнении к переменной PHONE, в шаблон будут переданы следующие переменные:

Эти дополнительные переменные могут быть использованы для удобства вёрстки или для функций автоматизации при помощи JavaScript, например, для виджета обратного звонка.

При кастомизации шаблонов магазина, следует избегать жёсткого прописывания контактных данных, и использовать для этого переменные. Т.е. вместо

  <h2>Наши контакты</h2>
  тел. +7(495)123-45-67<br>
  email sales@myshop.ru<br>

Следует использовать конструкцию

  <h2>Наши контакты</h2>
  тел. <TMPL_VAR NAME="PHONE"><br>
  email <TMPL_VAR NAME="EMAIL"><br>

По умолчанию, все шаблоны способны отображать следующие контактные данные:

И, если кастомизировать XML, определив все контактные данные в файле /custom/shop.xml, например, так:

<?xml version="1.0" encoding="utf-8"?>
<shop>
  <contacts>
    <phone>+7(495)111-11-11</phone>
    <email>sales@my_shop.ru</email>
    <city>Москва</city>
    <address>ул.Стромынка, д.12</address>
    <telegram>https://t.me/+7XXXXXXXXXX</telegram>
    <whatsup>https://api.whatsapp.com/send/?phone=74952222222</whatsup>
    <vk>https://vk.com/my_shop</vk>
    <instagram>https://www.instagram.com/my_shop/</instagram>
    <youtube>https://www.youtube.com/@my_shop</youtube>
    <dzen>https://dzen.ru/my_shop</dzen>
    <twitter>https://dzen.ru/my_shop</twitter>
    <legal_name>ООО «Рога и Копыты»</legal_name>
    <legal_address>123298, Москва, ул.Хромовская, д.11</legal_address>
    <legal_inn>300700578317</legal_inn>
    <legal_ogrn>623400217000032</legal_ogrn>
    <legal_kpp>654321</legal_kpp>
    <legal_rs>987654321</legal_rs>
    <legal_ks>1234567890</legal_ks>
    <legal_bank>ПАО "Сбербанк", г.Москва</legal_bank>
    <legal_bik>1234567</legal_bik>
  </contacts>
</shop>

То, страница "Контакты" приобретёт следующий вид: