Конвертер импорт/экспорт XML

Конвертеры импорт и экспорт XML реализованы для обмена данными системы УКМ 4 c внешними программными продуктами в формате XML. Передача данных осуществляется с помощью файлов в формате XML и возможна только в рамках операционной системы Windows.

Примечание. Несмотря на то, что в интерфейсе УКМ 4 данные XML-конвертеры носят название Супермаг Плюс, их можно использовать не только для интеграции УКМ 4 с продуктом СуперМаг Плюс компании Сервис плюс, но и с любыми внешними системами. Передача данных из внешней системы в УКМ 4 и из УКМ 4 во внешнюю систему осуществляется через раздельные каталоги. Набор каталогов един для всех магазинов, зарегистрированных на одном сервере. В одном файле формата XML передается только один тип данных. Конвертер непрерывно дорабатывается для поддержки передачи новых типов данных по запросам пользователей, однако, уже доступные теги и свойства не удаляются.

Описание передаваемой информации и правила работы с ней

Передача информации из УКМ 4 во внешнюю систему

УКМ 4 выгружает во внешнюю систему информацию двух типов:

          - чеки;

          - кассовая смена (в виде совокупности чеков по смене).

Выгружаются только нормально завершенные чеки (result=0) с операциями продажи, возврата, возврата по чеку и восстановления (type = 0, 1, 4 и 5).

Чеки выгружаются в каталог, указанный в настройках обеих систем, немедленно при появлении их на сервере УКМ 4. Каждый чек помещается в отдельный файл.

TAGNAME = Receipt.

Смены выгружаются по мере появления на сервере информации о закрытии смен. Информация по каждой смене выгружается в отдельный файл.

Смены выгружаются по мере появления на сервере информации о закрытии смен. По смене существует возможность ручной выгрузки (повторные выгрузки). Информация по каждой смене выгружается в отдельный файл.

TAGNAME = SHIFT.

Имена файлов

Файлы с чеками: TAGNAME_[Store]_[Cash]_[Shift]_[Receipt]_[Number].xml.

TAGNAME – название головного тега документа (регистр букв не важен).

Store – идентификатор магазина. Может быть переменной длины.

Cash – номер кассы. Может быть переменной длины.

Shift – номер фискальной смены. Может быть переменной длины.

Receipt – номер чека в смене. Может быть переменной длины.

Number – порядковый номер документа (целое число). Электронной обработки номер не имеет, важен только для регулирования последовательности документов с прочими одинаковыми элементами в имени файла.

Пример:

Receipt _[1112]_[15]_[254]_[32]_[1].xml – чек из магазина 1112, касса 15, смена 254, чек 32, экземпляр файла в каталоге №1.

Файлы со сменами: TAGNAME_[Store]_[Cash]_[Shift]_[Number].xml.

Настройка интерфейса сервера УКМ 4 для передачи данных во внешнюю систему

Перед настройкой сервера УКМ 4 убедитесь, что в настройках внешней системы указаны следующие параметры:

• Каталог для получения данных из УКМ 4.

Настройки в УКМ 4:

• Создать каталог для передачи данных из УКМ 4 во внешнюю систему.

Для подключения конвертера Супермаг Плюс XML экспорт перейдите в раздел веб-интерфейса Настройка сервера и оборудования – Конвертеры. В открывшемся окне нажмите кнопку +Добавить. Далее выберите из списка конвертер и нажмите +Создать. После создания конвертера откроется окно его настройки:

Название – в поле указывается название конвертера (по умолчанию присваивается значение типа добавляемого конвертера).

Запускается – указывается служба, через которую будет осуществляться обмен данными (при условии, что пользователь имеет право доступа к ресурсам). Существуют следующие варианты значений:

      Сервер – обмен будет осуществляться через серверную часть УКМ 4.

      Терминал – обмен будет осуществляться через клиентскую (терминальную) часть УКМ 4.

Магазины – для выбора магазинов, в которых будет действовать конвертер, кликните по ссылке Добавить магазины.

Экспорт средств оплаты – в данном подменю можно установить пользовательскую кодировку средств оплаты. Поля для настройки станут доступны, если в выбранном магазине используется более одного средства оплаты:

Каталог для выгрузки данных – в поле указывается путь до каталога, куда УКМ 4 помещает файлы выгрузки данных.

Игнорировать поврежденные чеки – при включенном флаге информация по чекам, данные которых повреждены, передаваться не будет.

Выгружать оперативные чеки – при включенном параметре передача данных по чеку будет производиться сразу после его печати.

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

При первом подключении выгружать – возможные варианты:

От начала открытой смены на момент подключения конвертера – после сохранения настроек конвертера будет произведена выгрузка данных по последней (открытой) смене и далее по мере появления на сервере информации о закрытии смен.

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

Структура данных, передаваемых из УКМ 4 во внешнюю систему

Внимание! В данном описании перечислены только новейшие изменения. Полную версию файлов экспорта можно найти здесь.

Чек:

<receipt storeId=”” posNum=”” shiftNum=””  receiptNum=””>
<version=””>
<receiptDateTime></receiptDateTime>        (время закрытия чека)
<cashierCode></cashierCode>                      (код кассира)
<cashierName></cashierName>                    (имя кассира)
<type></type>
<amount>/< amount>                                    (сумма чека, уменьшенная на величину скидок)
<item> // minOccurs=”1” maxOccurs="unbounded"
<article></article>
<barcode></barcode>
<egaisBarcode>5453453,352342,5645564,34523542</egaisBarcode>       (штриховые коды алкогольных марок PDF417, если товар является
                                                                                                                      алкогольной продукцией и кассиром была считана с бутылки акцизная марка
                                                                                                                      (или несколько марок для товаров-наборов))
<NOPDF></NOPDF>              (содержание QR кода, если товар является алкогольной продукцией
                                                 и кассиром был считан внутренний QR-код, наклеенный на бутылку)
<quantity></quantity>
<price></price>                                (цена товара по прайс-листу)
<total></total>                                 (стоимость позиции, уменьшенная на величину скидок)
<stockId></stockId>                         (отдел)
<Property></Property>                     (идентификатор свойства товара из нормализированного хранилища.
                                                            В случае нескольких значений выбирается случайным образом)
<PropertyValue></PropertyValue>    (значение свойства товара)
<discount> // minOccurs=”0” maxOccurs="unbounded"  (выгружаются скидки, которые привели к изменению суммы продажи)
<programId></programId>                       (код скидки в УКМ 4)
<programName></programName>          (название скидки в УКМ 4)
<programType></programType>              (тип скидки в УКМ 4 (значение поля trm_out_receipt_discounts.efts) integer)
<amount></amount>                                (значение скидки – положительное число)
<discCardNumber></discCardNumber>   (номер диск.карты, но не клубной карты!)
</discount>
<addition> // minOccurs=”0” maxOccurs="unbounded" (наценки, которые привели к изменению суммы продажи)
<programId></programId>                      (код скидки в УКМ 4)
<programName></programName>         (название скидки в УКМ 4)
<programType></programType>             (тип скидки в УКМ 4 (значение поля trm_out_receipt_discounts.efts) integer)
<amount></amount>                               (значение скидки – положительное число)
<discCardNumber></discCardNumber>  (номер диск.карты, но не клубной карты!)
</addition>
<enterType></enterType>                        (способ ввода товара: 0 – сканером, 1 – с клавиатуры, 2 – по «горячей» клавише)
<sellerId></sellerId>
<sellerName></sellerName>                    (фамилия продавца)
</item>
<gift> // minOccurs=”1” maxOccurs="unbounded"
<article></article>                                    (артикул товара, выданного как подарок)
<programId></programId>                     (ID скидки в УКМ 4, которая инициировала выдачу данного подарка)
<programName></programName>
<quantity></quantity>                             (количество товара-подарка)
</gift>
<payment> // minOccurs=”1” maxOccurs="unbounded" (оплаты по чеку)
<paymentId></paymentId>                     («тип» средства оплаты: если не включено мапирование средств оплаты
                                                                   в настройках конвертора экспорта или не указан код,
                                                                   в который надо мапировать, то коды присваиваются по следующим правилам:
0 – наличные;
101 – все средства оплаты, связанные с банковскими авторизациями
          и голосовыми/пустыми серверами авторизаций в УКМ 4;
102 – ПС и ПК;
103 - внутренние счета)           
<paymentName></paymentName>  (название средства оплаты в УКМ 4:
Для кода 0 – Наличные;
Для кода 101 – Банковская карта;
Для кода 102 – Подарочный сертификат;
Для кода 103 – Оплата баллами)
<paymentAmount></paymentAmount>
</payment>
</receipt>

Смена:

<shift storeId=”” posNum=”” shiftNum=””>
<dateClose>/<dateClose>
<cashierCode></cashierCode>            (кассир, закрывший смену)
<cashierName></cashierName>
<saleAmount></saleAmount>             (сумма всех чеков продажи за смену (сумма чека за минусом скидок))
<returnAmount></returnAmount>      (сумма всех чеков возвратов за смену (суммы чеков с учётом восстановления скидок))
<saleCount></saleCount>
<returnCount></returnCount>
<receipt storeId=”” posNum=”” shiftNum=”” receiptNum=””>//minOccurs=”0” maxOccurs = "unbounded"
<receiptNum></receiptNum >
<receiptDateTime></receiptDateTime>
<cashierCode></cashierCode>            (код кассира)
<cashierName></cashierName>          (имя кассира)
<type></type>
<amount>/< amount>                          (сумма чека, уменьшенная на величину скидок)
<item> // minOccurs=”1” maxOccurs="unbounded"<article></article>
<barcode></barcode>  
<egaisBarcode>5453453,352342,5645564,34523542</egaisBarcode>    (штриховые коды алкогольных марок PDF417, если товар
                                                                                                                   является алкогольной продукцией и кассиром была считана
                                                                                                                   с бутылки акцизная марка (или несколько марок
                                                                                                                   для товаров-наборов))
<NOPDF></NOPDF>              (содержание QR кода, если товар является алкогольной продукцией
                                                 и кассиром был считан внутренний QR-код, наклеенный на бутылку)
<quantity></quantity>
<price></price>                      (цена товара по прайс-листу)
<total></total>                       (стоимость позиции, уменьшенная на величину скидок)
<stockId></stockId>
<Property></Property>          (идентификатор свойства товара из нормализированного хранилища;
                                                 в случае нескольких значений выбирается случайным образом)
<PropertyValue></PropertyValue>
<discount> // minOccurs=”0” maxOccurs="unbounded"   (выгружаются скидки, которые привели к изменению суммы продажи)
<programId></programId>                        (код скидки в УКМ 4)
<programName></programName>           (название скидки в УКМ 4)
<programType></programType>               (тип скидки в УКМ 4 (значение поля trm_out_receipt_discounts.efts) integer)
<amount></amount>                                 (значение скидки – положительное число)
<discCardNumber></discCardNumber>    (номер диск.карты, но не клубной карты!)
</discount>
<addition> // minOccurs=”0” maxOccurs="unbounded"    (наценки, которые привели к изменению суммы продажи)
<programId></programId>                        (код скидки в УКМ 4)
<programName></programName>           (название скидки в УКМ 4)
<programType></programType>               (тип скидки в УКМ 4 (значение поля trm_out_receipt_discounts.efts) integer)
<amount></amount>                                 (значение скидки – положительное число)
<discCardNumber></discCardNumber>    (номер диск.карты, но не клубной карты!)
</addition>
<enterType></enterType>
<sellerId></sellerId>
<sellerName></sellerName>
</item>
<gift> // minOccurs=”1” maxOccurs="unbounded"
<article></article>                                      (артикул товара, выданного как подарок)
<programId></programId>                       (ID скидки в УКМ 4, которая инициировала выдачу данного подарка)
<programName></programName>
<quantity></quantity>                               (количество товара-подарка)
</gift>
<payment> // minOccurs=”1” maxOccurs="unbounded"    (оплаты по чеку)
<paymentId></paymentId>                («тип» средства оплаты: если не включено мапирование средств оплаты
                                                              в настройках конвертора экспорта или не указан код,
                                                              в который надо мапировать, то коды присваиваются по следующим правилам:
0 – наличные;
101 – все средства оплаты, связанные с банковскими авторизациями
          и голосовыми/пустыми серверами авторизаций в УКМ 4;
102 – ПС и ПК;
103 - внутренние счета) 
<paymentName></paymentName> (название средства оплаты в УКМ 4:
Для кода 0 – Наличные;
Для кода 101 – Банковская карта;
Для кода 102 – Подарочный сертификат;
Для кода 103 – Оплата баллами)
<paymentAmount></paymentAmount>
</payment>
</receipt>
</shift>