birmaga.ru
добавить свой файл

1

Описание формата XML файла для экспорта данных

в систему shop.bigmir.net



Версия 1.5




Содержание:


  1. Общая информация, контакты, ссылки

  2. Описание формата, типичные ошибки

  3. Пример файла экспорта

  4. Пример php класса для генерации файла экспорта

  5. ЧаВо


информация,_контакты,"> Общая информация, контакты, ссылки



Система shop.bigmir.net является платным агрегатором товарных предложений магазинов-партнёров с оплатой за переход пользователя на сайт магазина-партнёра.

Консультации по техническим вопросам, связанным с работой системы



e-mail: shopadmin@bigmir.net

Заездный Олег

Вопросы связанные с оплатами, размещением рекламы



e
-mail: zaruba@kpmedia.ua тел: 8 (044) 496-45-63, внутренний 7043

Заруба Оксана

Статистика


Статистика работы магазина доступна по адресу http://shop.bigmir.net/shopadmin , для доступа к статистике необходимо авторизоваться на Бигмире под логином на который зарегистрирован магазин-партнёр.

Тестирование файла экспорта


Сервис для тестирования файла экспорта доступен по адресу http://shop.bigmir.net/test/. Для доступа к сервису необходимо авторизоваться на Бигмире под логином, на который зарегистрирован магазин-партнёр. Для регистрации магазина пришлите заявку на shopadmin@bigmir.net.

Актуальный вариант этого документа

Актуальный вариант документа доступен по адресу http://i.bigmir.net/adv/shop_export_format.doc



Описание формата, типичные ошибки

XML


Обязательное начало XML файла экспорта. Пробелы или переводы строки недопустимы в начале файла, обязательно указание кодировки “windows-1251”:

Не допускаются с ASCII-кодами 0-31, кроме табуляции и перевода строки. А так же обязательно необходимо кодировать следующие символы во всех тестовых полях файла экспорта в соответствующие им сущности:
" - "


& - &


< - <


> - >


' - '

Структура файла экспорта




------------------------------------------------------------------------------------









------------------------------------------------------------------------------------









------------------------------------------------------------------------------------











































------------------------------------------------------------------------------------



Часть 1


Пример:


Атрибут date должен содержать дату и время генерации файла экспорта в формате YYYY-MM-DD HH-MM . Если система уже обрабатывала файл с такой датой, повторная обработка не производится.



Часть 2


Пример:

ELEKROVENIK

http://electrovenic.com.ua



Киев

Одесса
Тэг name содержит название магазина-партнёра. Запрещается размещать в названии магазина любую рекламную информацию, как то лозунги, телефоны и прочее. Тэг должен содержать только название магазина (без слов «интернет-магазин», «www»).
Тэг url содержит ссылку на главную страницу магазина-партнёра.
Атрибут code тэга currency указывает на то, в какой валюте указаны цены в файле экспорта. Допустимые значения ”USD”, ”EUR”, ”UAH”.
Атрибут rate тэга currency указывает на курс валюты, по которому будут рассчитываться цены в гривне для отображения в системе shop.bigmir.net, если атрибут rate отсутствует – будет использоваться курс НБУ для указанной валюты. Разделитель целой и дробной части – точка. Примеры:

- валюта прайса долар США, курс 8.0

- валюта прайса Евро, курс НБУ

- валюта прайса украинская гривна
Тэг region содержит название региона в котором магазин-партнёр осуществляет доставку. Допустимые значения: "Украина", "Винница", "Днепропетровск", "Донецк", "Житомир", "Закарпатье", "Запорожье", "Ивано-Франковск", "Киев", "Кировоград", "Крым", "Луганск", "Луцк", "Львов", "Николаев", "Одесса", "Полтава", "Ровно", "Сумы", "Тернополь", "Харьков", "Херсон", "Хмельницкий", "Черкассы", "Чернигов", "Черновцы", "Россия".

Внимание! Не указывайте несколько регионов в одном тэге! Используйте отдельный тэг для каждого региона. Пример:


Киев

Одесса - регионы доставки Киев, Одесса

Часть 3


Пример:



Мобильная связь

Мобильные телефоны


Тэг catalog содержит описание дерева категорий используемого в файле экспорта.
Тэг category содержит название описываемой категории дерева категорий.
Атрибут id тэга category содержит уникальный id категории, целое число от 1 до 2147483647. Внимание! Необходимо, что бы id категории был постоянным, и не изменялся от экспорта к экспорту.




Атрибут parentID тэга category содержит id родительской категории, целое число от 1 до 2147483647. Если атрибут parentID не указан, либо равен нулю – родительской категорией для описываемой считается корневая.
Максимальная допустимая вложенность категорий – шесть уроней. Желательная - менее четырёх.

Товары должны заключаться в определенную категорию/подкатегорию (особенно если указывается только фирма-производитель), сродную нашему каталогу
товаров. Иначе товар на сайте отображаться не будет. Если нужной категории/подкатегории нет - сообщите об этом Вашему менеджеру. В случае необходимости категория/подкатегория будет создана.

Часть 4


Пример:





Гравицапа с оптическим прицелом

http://electrovenic.com.ua/goods/?id=1


100.5


1

Kin-dza-dza

http://electrovenic.com.ua/goodsimage/?id=1



Гравицапа с оптическим прицелом – прекрасный подарок для

настаящего пацака :)



CD12345




Гравицапа без оптического прицела

http://electrovenic.com.ua/goods/?id=2


90.5


1

Kin-dza-dza

http://electrovenic.com.ua/goodsimage/?id=2



Гравицапа без оптического прицела – прекрасный подарок для

настаящего пацака :)



CD12345




Тэг items содержит все описания товаров в файле экспорта.
Тэг item содержит описание отдельного товара.
Атрибут id тэга item содержит уникальный id товара, целое число от 1 до 2147483647. Внимание! Необходимо, что бы id товара был постоянным, и не изменялся от экспорта к экспорту.
Тэг name содержит название товара, строку до 150 символов, если название больше, оно обрезается, и в его конце ставится троеточие. Внимание! Название товара должно быть указано по формату {Бренд} {Модель}, например, Nokia E96. Также не допускаются названия товаров, полностью написанные заглавными буквами. Не указывайте в этом теге принадлежность товара к группе (например «Ноутбук», «Мобильный телефон»). Название товара должно бать уникальным, с указаним артикула или маркировки (например, платье Амели 02154 – правильно; платье - неправильно). Цвет товара добавляйте в конце названия и на английском языке с маленькой буквы (например, Sony
2210 red).
Тэг url содержит ссылку на страницу товара на сайте магазина-партнёра.
Тэг price содержит цену описываемого товара, число, разделитель целой и дробной части – точка. Внимание! Не допускаются товары с нулевой ценой, а так же не приветствуются цены не соответствующие действительности. Ваш магазин может быть отключен без уведомления при нарушении данного правила.

Тэг categoryId содержит id категории из дерева категорий файла экспорта к которой относится данный товар.

Тэг vendor содержит название производителя описываемого товара, строку до 100 символов. Не обязательное поле. Пример:

Nokia

Внимание! Не допускаются названия производителей, полностью написанные заглавными буквами или с ошибками.




Тэг image содержит ссылку на изображение товара в формате gif, jpg или png. Внимание! Запрещено присылать товар без картинки. Крайне не приветствуется указание вместо изображения товара каких либо заглушек, это приравнивается к отсутствию картинки и такой товар добавлен не будет.
Тэг description содержит описание товара, строку до 64 Кб. Внимание! Товары без описания добавлены не будут. Допускаются следующие HTML теги:
,
,

  • , , ,
    ,
      ,
        , .

        Типичные ошибки XML


        1. Используются символы не допустимые в xml (",&,<,>,') без перекодировки в соответствующие сущности.



        Типичные ошибки в части 1


        1. Атрибут date не содержит актуальной информации, к примеру статичен, в следствии чего система не обрабатывает файл экспорта, считая, что файл экспорта не обновлялся.

        Типичные ошибки в части 2


        1. Тэг name содержит не разрешённую правилами информацию. Как правило, магазин отключается администратором раздела до момента исправления файла экспорта.

        2. Неверно указана валюта прайса либо её курс, в результате чего отображаемые цены не соответствуют действительности.

        Типичные ошибки в части 3


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

        2. Id категорий не уникальны.

        3. Id категорий изменяются от экспорта к экспорту.

        Типичные ошибки в части 4


        1. Id товаров в экспорте не уникальны.

        2. Id товаров изменяются от экспорта к экспорту.
        3. Нулевая либо не соответствующая действительности цена товара.


        4. Не указан id категории, к которой относится товар.



        Пример файла экспорта




        shopik

        http://www.shopik.com.ua/





        Товары

        Цветы

        Букеты

        Подарки







        Букет из роз

        http://www.shopik.com.ua/id=1

        210

        4





        Букет ко дню рождения 0421

        http://www.shopik.com.ua/id=2

        200

        5






        Пример php класса для генерации файла экспорта



        setlocale(LC_CTYPE, array('ru_RU.CP1251', 'rus_RUS.1251'));

        set_time_limit(600);
        /**

        * price_generator($shopname, $shopurl);

        * string $shopname - название магазина

        * string $shopurl - урл магазина

        */

        class price_generator{

        var $shopname = '';

        var $shopurl = '';

        var $shopcurrency = 'UAH';

        var $currencyrate = 1;

        var $region = array();

        var $category = array();

        var $item = array();

        var $err = array();

        var $adminmail = '';

        var $allcurrency = array('UAH', 'USD', 'EUR');

        var $allregion = array( 'Украина',

        'Винница',


        'Днепропетровск',

        'Донецк',

        'Житомир',

        'Закарпатье',

        'Запорожье',

        'Ивано-Франковск',

        'Киев',

        'Кировоград',

        'Крым',

        'Луганск',

        'Луцк',

        'Львов',

        'Николаев',

        'Одесса',

        'Полтава',

        'Ровно',

        'Сумы',

        'Тернополь',

        'Харьков',

        'Херсон',

        'Хмельницкий',

        'Черкассы',

        'Чернигов',

        'Черновцы',

        'Россия');

        /**

        * инициализация класса

        *

        * @param string $shopname - название магазина

        * @param string $shopurl - урл магазина

        * @param string $mail - е-мейл админа для отсылки отчёта об ошибках

        * @return price_generator

        */

        function price_generator($shopname, $shopurl, $mail = ''){

        if (!$shopname) {

        $this->error('Не указано название магазина.');

        die('Не указано название магазина.');

        } else {

        $this->shopname = $this->txt($shopname);

        }

        if (!$shopurl) {

        $this->error('Не указан url магазина.');

        die('Не указано название магазина.');

        } else {

        $this->shopurl = $shopurl;

        }

        if ($mail) {

        $this->adminmail = $mail;

        }

        }

        function txt($s, $level = 0){

        if ($level == 0) {

        $s = strip_tags($s);

        }

        $s = html_entity_decode($s);

        $s = htmlspecialchars($s, ENT_QUOTES);

        return $s;

        }

        /**

        * Обработка ошибок

        *

        * @param string $errmesage

        */

        function error($errmesage){

        $this->err[] = $errmesage;

        }

        /**

        * Добавляет категорию в дерево каталога

        * @param string $name - название категории


        * @param int $id - уникальный числовой идентификатор категории

        * @param int $parentID - числовой идентификатор родительской категории, если 0, или отсутствует - категория корневая

        * @return bool - возвращает true если категория добавлена, иначе false

        */

        function add_category($name, $id, $parentID = 0){

        if (empty($name)){

        $this->error("Нет названия категории. ({$id})");

        return false;

        }

        if ($id == 0){

        $this->error("id категории не может быть равно нулю. ({$name})");

        return false;

        }

        if (isset($this->category[$id])){

        $this->error("Категория с id={$id} уже есть.");

        return false;

        }

        if ($id == $parentID){

        $this->error("parentID категории с id={$id} указывает на саму категорию.");

        return false;

        }

        if (!is_int($parentID) || !is_int($id)){

        $this->error("id и parentID категории должно иметь тип integer. ({$name})");

        return false;

        }

        $this->category[$id]['name'] = $this->txt($name);

        $this->category[$id]['parentID'] = $parentID;

        return true;

        }

        /**

        * Добавляет товар в экспорт

        *

        * @param int $id - уникальный числовой идентификатор товара

        * @param string $name - название товара

        * @param string $description - описание товара

        * @param real $price - цена

        * @param int $categoryID - числовой идентификатор категории к которой принадлежит товар

        * @param string $url - урл товара на сайте магазина

        * @param string $image - урл изображения товара

        * @param string $vendor - производитель товара

        * @return bool - возвращает true если товар добавлен, иначе false

        */

        function add_item($id, $name, $description = '', $price, $categoryID, $url, $image = '', $vendor = ''){


        if ($id == 0 || !is_integer($id)){

        $this->error("id товара должно иметь тип integer. Название товара '{$name}'");

        return false;

        }

        if (empty($name)) {

        $this->error("Не указано название товара. id товара {$id}");

        return false;

        }

        if ($price <= 0 || !is_numeric($price)){

        $this->error("Цена товара должна быть числом больше нуля. Название товара '{$name}' id товара {$id}");

        return false;

        }

        if ($categoryID == 0 || !is_int($categoryID)){

        $this->error("id категории должно иметь тип integer. Название товара '{$name}' id товара {$id}");

        return false;

        }

        if ((strtolower(substr(trim($url), 0, 7)) != "http://")&&(strtolower(substr(trim($url), 0, 8)) != "https://")){

        $this->error("Урл товара должен начинаться с 'http://'. Название товара '{$name}' id товара {$id}");

        return false;

        }

        if (isset($this->item[$id])){

        $this->error("Товар с id = {$id} уже есть в экспорте. Название товара '{$name}'");

        return false;

        }

        $this->item[$id]['name'] = $this->txt($name);

        $this->item[$id]['description'] = $this->txt($description, 1);

        $this->item[$id]['price'] = $price;

        $this->item[$id]['categoryID'] = $categoryID;

        $this->item[$id]['url'] = $this->txt($url);

        $this->item[$id]['image'] = $this->txt($image);

        $this->item[$id]['vendor'] = $this->txt($vendor);

        return true;

        }

        /**

        * Устанавливает валюту прайса

        *

        * @param string $currency - валюта прайса, допустимые значения 'UAH', 'USD', 'EUR'

        * @param real $rate - курс, если не указан, будет использоватmся курс НБУ

        * @return bool - возвращает true если валюта прайса установлена, иначе false

        */

        function set_currency($currency, $rate = 0){


        if (!in_array(strtoupper($currency) , $this->allcurrency)){

        $this->error("Неизвестная валюта '{$currency}'");

        return false;

        }

        if (!is_numeric($rate)){

        $this->error("Недопустимый курс валюты '{$rate}'");

        return false;

        }

        $this->shopcurrency = $currency;

        $this->currencyrate = $rate;

        return true;

        }


        /**

        * Устанавливает регион доставки . Пример add_region('Украина', 'Россия');

        * @param допустимые регионы 'Украина', 'Винница',

        * 'Днепропетровск', 'Донецк', 'Житомир', 'Закарпатье', 'Запорожье',

        * 'Ивано-Франковск', 'Киев', 'Кировоград', 'Крым', 'Луганск', 'Луцк',

        * 'Львов', 'Николаев', 'Одесса', 'Полтава', 'Ровно', 'Сумы', 'Тернополь',

        * 'Харьков', 'Херсон', 'Хмельницкий', 'Черкассы', 'Чернигов', 'Черновцы', 'Россия'

        * @return bool - возвращает true если все регионы установлены, иначе false

        */

        function add_region(){

        $flag = true;

        $tmp = func_get_args();

        foreach ($tmp as $region){

        $region = trim($region);

        $region = ucfirst(strtolower($region));

        if (!in_array($region, $this->allregion)){

        $this->error("Не известный регион доставки '{$region}'.");

        $flag = false;

        }

        $this->region[$region] = $region;

        }

        return $flag;

        }
        /**

        * метод для внутреннего использования, выполняет

        * проверку целостности каталога и списка товаров

        *

        */

        function validate(){

        foreach ($this->category as $id => $cat){

        if (!isset($this->category[$cat['parentID']]) && $cat['parentID'] != 0){

        $this->error("Не верный parentID у категории с id={$id}. В экспорте нет категории с id {$cat['parentID']}");

        unset($this->category[$id]);


        }

        }

        foreach ($this->item as $id => $item){

        if (!isset($this->category[$item['categoryID']])){

        $this->error("Не верная категория товара с id={$id}. В экспорте нет категории с id {$item['categoryID']}");

        unset($this->item[$id]);

        }

        }

        }

        /**

        * Отсылает отчёт на email

        *

        */

        function send($mail = ''){

        if ($mail){

        $this->adminmail = $mail;

        }

        if ($this->adminmail) {

        if (count($this->err) != 0){

        mail($this->adminmail, $this->shopname . ' export error ' . date('Y-m-d H:i'), implode("\n", $this->err));

        } else {

        mail($this->adminmail, $this->shopname . ' export error ' . date('Y-m-d H:i'), "Без ошибок.\n");

        }

        }

        }

        /**

        * Выводит список ошибок

        *

        */

        function debug (){

        $this->validate();

        echo '
        ';

        if (count($this->err) != 0){

        foreach ($this->err as $err){

        echo $err . '
        ';

        }

        } else {

        echo "Ошибок нет.
        ";

        }

        echo "


        Название магазина '{$this->shopname}'
        ";

        echo "Урл магазина '{$this->shopurl}'
        ";

        echo "Валюта прайса '{$this->shopcurrency}'
        ";

        echo "Курс " . ($this->currencyrate ? $this->currencyrate : " НБУ") . "
        ";

        echo "Регион(ы) доставки: " . implode(',', $this->region) . "
        ";

        echo "
        Категорий " . count($this->category) . "
        ";

        echo "Товаров " . count($this->item) . "

        ";

        echo '
        ';

        }

        /**

        * генерирует и выводит xml

        *

        * @param string $file - имя файла для записи xml экспорта

        */

        function generate($file = ''){

        // проверка целостности каталога и списка товаров


        //$this->validate();

        // заголовок xml

        $out = "\n";

        $out .= "
        \n";

        //название магазина

        $out .= "{$this->shopname}\n";

        //регион доставки

        foreach ($this->region as $region){

        $out .= "{$region}\n";

        }

        //урл магазина

        $out .= "{$this->shopurl}\n";

        //валюта прайса

        $out .= "shopcurrency}\"" . ($this->currencyrate ? " rate = \"" . $this->currencyrate . "\"" : "") . " main = \"1\"/>\n";

        // генерируем дерево каталога

        $out .= "\n";

        foreach ($this->category as $id=>$cat){

        $out .= "{$cat['name']}\n";

        }

        $out .= "
        \n";

        // выводим товары

        $out .= "\n";

        foreach ($this->item as $id=>$item){

        $out .= "\n";

        $out .= "{$item['name']}\n";

        $out .= "{$item['url']}\n";

        $out .= "
        {$item['price']}
        \n";

        $out .= "{$item['categoryID']}\n";

        $out .= $item['vendor'] ? "{$item['vendor']}\n" : "";

        $out .= $item['image'] ? "{$item['image']}\n" : "";

        $out .= $item['description'] ? "{$item['description']}\n" : "";

        $out .= "
        \n";

        }

        $out .= "
        \n";

        $out .= "
        \n";

        // пишем в файл или выводим

        if (!$file){

        if (!headers_sent()){

        Header('Content-Type: text/xml; charset = windows-1251');

        Header('Cache-Control: no-store, no-cache, must-revalidate');

        Header('Cache-Control: post-check = 0, pre-check = 0', false);


        $this->send();

        echo $out;

        } else {

        $this->error('Header уже отправлен!');

        $this->send();

        die('
        Header уже отправлен!');

        }

        } else {

        $handle = fopen($file, 'wb');

        if ($handle){

        if (fwrite($handle, $out) === false){

        $this->error("Не удалось записать ({$file}).");

        $this->send();

        fclose($handle);

        die("Не удалось записать ({$file}).");

        } else {

        $this->send();

        fclose($handle);

        }

        } else {

        $this->error("Не удалось открыть ({$file}) для записи.");

        $this->send();

        die("Не удалось открыть ({$file}) для записи.");

        }

        }

        }

        }

        // Пример использования
        // создаём экземпляр класса

        $z = new price_generator('Название', 'http://www.gdeto.com', '');
        // создаём категорию 'Мобильная связь' с id = 1

        $z->add_category('Мобильная связь',1);
        // создаём подкатегорию 'Телефоны' с id = 2 в категории 'Мобильная связь' (id = 1)

        $z->add_category('Телефоны', 2, 1);
        // устанавливаем валюту прайса и её курс к гривне

        $z->set_currency('USD',5.5);
        // устанавливаем регион доставки

        $z->add_region('луцк', 'львов');
        // добавляем товар 'Гравицапа' с id = 1 в категорию 'Телефоны' (id = 2)

        $z->add_item(1, 'Гравицапа', '', 121.75, 2, 'http://www.gdeto.com/item?id=1', '', 'nokia');
        // добавляем товар 'Гравицапа специальная' с id = 2 в категорию 'Телефоны' (id = 2)

        $z->add_item(2, 'Гравицапа специальная ', 'То что нужно настоящему пацаку!', 252.5, 2, 'http://www.gdeto.com/item?id=2', '', 'nokia');
        //вывод ошибок

        $z->debug();
        //выводим экспорт

        //$z->generate();
        //сохраняем экспорт в файл

        //$z->generate('shop1.xml');

        ?>