Импорт XML

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

Имена файлов

TAGNAME_ [Object]_ [Number]_[P]_[Error].xml

TAGNAME – название головного тега файла.

Object – идентификатор объекта. Может быть переменной длины и принимать значение [код магазина] для файлов, указанных в таблице выше в разделе Информация для магазинов.

Если документ содержит только общую информацию, то параметр Object не указывается.

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

P – признак полноты информации в файле: F – файл содержит полный перечень элементов, I – файл содержит не полный перечень элементов.

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

Для всех частей имени файла регистр букв не важен.

Примеры:

storePrices_[1112]_[1]_[I].xml – изменения розничных цен в магазине 1112;

classif_[2]_[F].xml – классификатор товаров.

Принципы обмена данными между УКМ 4 и внешней системой

• Процесс передачи данных между УКМ 4 и внешней системой исключает дублирующие потоки информации. Сервер УКМ 4 получает всю информацию о товарах из сервера внешней системы. Другими словами, в случае наличия центрального сервера внешней системы и сервера главного офиса УКМ 4, информация о товарах будет загружаться и на сервер главного офиса (СГО) и на сервера магазинов. Соответственно, в УКМ 4 репликация товарных справочников с СГО на сервера магазинов будет заблокирована.
• При настройке передачи данных из внешней системы в УКМ 4 необходимо учитывать, что все магазины в УКМ 4 работают с одной номенклатурой. Если настройка сделана неверно, то в УКМ 4 будет использована одна из номенклатур (выбор номенклатуры произойдет случайным образом). Ограничение отслеживается административными методами.
• В России налоги обычно не загружаются на кассы. На Украине и в Белоруссии налог один, и ставка его одинакова на всей территории страны. Таким образом, функционал налоговых регионов во внешних системах фактически не используется. Поэтому выгружать из внешней системы информацию о связке <налоговая группа – товар> предлагается только для региона Россия.

Правила выгрузки информации из внешней системы в УКМ 4

• Все справочники, кроме товаров (артикулов) и цен, выгружаются из внешней системы полностью (если в них произошли изменения во внешней системе с момента предыдущей выгрузки). Если изменений во внешней не было, то файлы соответствующих типов не создаются.
• Удаления записей о товарах (артикулах) и ценах в рамках протокола обмена информацией не предусмотрено. Удаление товара (запись в прайс-листе) производится через интерфейс УКМ 4.
• Удаления записей о товарах (артикулах) в рамках протокола не предусмотрено. При большой необходимости удалить товар можно через интерфейс УКМ 4.
• Если файл с ценами имеет флаг полной выгрузки, то УКМ 4 предварительно удаляет текущее содержимое прайс-листа для магазина и затем загружает его содержание из файла. Удаляются только цены на артикулы, цены на штрихкоды не изменяются.
• Если в выгруженной записи о цене пропущено её значение (есть только теги <price></price>), то УКМ 4 удаляет запись о цене для данного товара из текущего прайс-листа.

Правила обработки информации сервером УКМ 4

• Каждый файл, передаваемый из внешней системы в УКМ 4, содержит один тип информации и обрабатывается сервером УКМ 4 как отдельная транзакция, т.е. он или обрабатывается целиком или не обрабатывается вообще. Каждый файл обрабатывается независимо от другого.
• Файлы обрабатываются сервером УКМ 4 в порядке, в котором они перечислены в таблице (см. выше). При этом, для каждого типа информации (тега) УКМ 4 ищет файл полной выгрузки с наибольшим номером, загружает его и все последующие файлы этого же типа с инкрементной выгрузкой (этого же типа) и не загружает все файлы до загруженного файла.
• Все файлы из входного каталога УКМ 4 переносит подкаталог Archive, добавляя к концу имени дату-время его обработки (в формате YYYYMMDDHHMMSS). При этом, если файл был загружен, то в конец имени дописывается load, если файл был пропущен – ignor.
• Если при обработке файла возникли ошибки любого типа (как связанные с доступом к файлу, так и с его содержанием), то работа конвертера останавливается, он переходит в режим периодического рестарта. При каждом старте конвертер начинает обработку каталога заново. В этом случае предполагается, что проблема будет исправлена с помощью ручной полной выгрузки из внешней системы. Файлы, при обработке которых возникли ошибки, остаются в каталоге обмена, и УКМ 4 дописывает к их имени [error]. Например: Classif_[1]_[F]_[error]. При рестарте конвертера файлы по-прежнему участвует в обработке информации по общим правилам, но отметка [error] остается у файла навсегда, в том числе и при переносе в подкаталог Archive. При этом, файл может быть успешно обработан (load) или может быть пропущен (ignor).
• УКМ 4 должен обеспечить правильную обработку привязки штрихкодов к артикулам, т.е. в базе УКМ 4 штрихкод должен быть привязан к артикулу в соответствии с последней информацией, полученной из внешней системы.

Требования к внешней системе:

• Если сервер внешней системы обслуживает несколько магазинов, то изменение общей информации должно выгружаться только один раз (а не столько раз, сколько магазинов обслуживает сервер).
• Внешняя система должна сначала сформировать файл, а затем сделать его доступным для УКМ 4 путем переименования файла (создание и переименование происходят в одном и том же каталоге).
• В рамках каждой отдельной выгрузки внешняя система делает доступными для УКМ 4 файлы в порядке перечисления типов информации в приведенной выше таблице.

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

Например, в каталоге есть файлы Classif_[1]_[F], Classif_[2]_[F], Classif_[3]_[F]. Если в этот момент внешняя система еще раз выгружает товарный классификатор, то она должна выгрузить его в файл с именем Classif_[4]_[F].  Флаг полного/неполного наполнения файла не влияет на нумерацию файлов (т.е. нумерация сквозная для файлов с одним типом документов без учета полного/неполного их содержимого).

• Полные выгрузки внешняя система делает либо по расписанию, либо при ручной выгрузке. «Загруженность» предыдущих порций информации внешняя система не проверяет.

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

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

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

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

После создания конвертера откроется окно его настройки:

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

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

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

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

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

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

Роль, которая назначается кассирам – указывается одна из ролей кассового персонала. Загружаемые записи о кассирах будут привязаны к этой роли. Пароли при загрузке зашифрованы.

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

Рекламная акция – устаревший функционал; в поле необходимо указать значение Не загружать скидки.

Формировать налоговые ставки по ФЗ РФ – загрузка налоговых ставок.

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

ВНИМАНИЕ! В данном описании перечислены только новейшие изменения. 

Загрузка дополнительных цен

<storePricesAdd fullness="F" storeId="4">
<version=”1.0”>
<PriceType> //  minOccurs=”0” maxOccurs="unbounded"
<priceTypeCode></priceTypeCode>                      (код вида цены в СМ)
<priceTypeName></priceTypeName>                    (название вида цены в СМ)
<item article=””> //minOccurs=”0” maxOccurs="unbounded"
<price>// minOccurs=”0” maxOccurs="1"
<value></value>
<minprice></minprice>
<MRC>// minOccurs=”0” maxOccurs="unbounded"
<MRCValue> </MRCValue>
</MRC>
</price>
</item>
</PriceType>
</storePricesAdd>

Ссылка на чек продажи в чеке возврата

<cashierName> </cashierName>
<cashierCode> </cashierCode>
<type> </type>
<POSsale> </POSsale>
<shiftNumSale> </shiftNumSale>
<receiptNumSale> </receiptNumSale>     (для всего чека)
<amount> </amount>
<item>
<position> </position>
<positionSale> </positionSale>                 (для отдельной позиции)
<article> </article>
<quantity> </quantity>
<price> </price>
<total> </total>
<stockId> </stockId>
<enterType> </enterType>
<discount>
<programId> </programId>
<programName> </programName>
<programType> </programType>
<amount> </amount>
</discount>
</item>

Контроль алкокодов для акцизных марок

<egaisType></egaisType>              ((int), признак акцизного товара; 0 – неакцизный товар, 1 – маркированный товар,
                                                         2 – немаркированный, 3 - специальный маркируемый)
<ProductAlcCodes>                         (присутствует, если egaisType = 1)
<AlcCode></AlcCode>                   (код алкогольной продукции, может быть от 0 до множества)
</ProductAlcCodes>

Открытие смен

<?xml version="1.0" encoding="UTF-8"?>
<shiftOpen storeId="1" posNum="7" shiftNum="32">
<version> </version>
<dateOpen> </dateOpen>                   (дата открытия смены)
<cashierCode> </cashierCode>            (код кассира)
<cashierName> </cashierName>          (имя кассира)
</shiftOpen>

Сведения о ККТ

<kkm_shift_number> </kkm_shift_number>                           (номер смены по ККТ)
<kkm_serial_number> </kkm_serial_number>                        (заводской номер ККТ)
<kkm_registration_number> </kkm_registration_number>    (регистрационный номер ККТ)
<kkm_model_name> </kkm_model_name>                            (название модели ККТ)

Суммы за смену, полученные от ККТ

<kkm_saleAmount> </kkm_saleAmount>                              (сумма продаж)
<kkm_returnAmount> </kkm_returnAmount>                       (сумма возвратов) 
<kkm_saleCount> </kkm_saleCount>                                     (количество чеков продажи)
<kkm_returnCount> </kkm_returnCount>                              (количество чеков возврата)
<kkm_withdrawal> </kkm_withdrawal>                                  (сумма изъятия из денежного ящика)
<kkm_insertion> </kkm_insertion>                                         (сумма внесения в денежный ящик)

Дата и время

<receipt storeId="1" posNum="7" shiftNum="32" receiptNum="4">
<receiptDateTime> </receiptDateTime>                                                  (дата и время закрытия чека)
<receiptOpenDateTime> </receiptOpenDateTime>                                (дата и время открытия чека)
<receiptSubtotalDateTime> </receiptSubtotalDateTime>                       (дата и время подытога)
<cashierName>Петров</cashierName>

Сведения об операциях внесения/изъятия, производимых на кассе

<cashBox storeId="1" posNum="7" shiftNum="34" docNum="2">
<version> </version>
<dateOper> </dateOper>
<dateOper> </dateOper>                                 (дата операции)
<operCode> </operCode>                                (код операции)
<cashierCode> </cashierCode>            
<cashierName> </cashierName>
<saleAmount> </saleAmount>                          (сумма внесения)
<saleAmount_before> </saleAmount_before>  (сумма в денежном ящике до внесения)
</cashBox>

<?xml version="1.0" encoding="UTF-8"?>                       
<shiftOpen storeId="1" posNum="7" shiftNum="32">   
<version> </version>
<dateOper> </dateOper>                                   (дата операции)
<operCode> </operCode>                                  (код операции)
<cashierCode> </cashierCode>
<cashierName> </cashierName>               
<saleAmount> </saleAmount>                           (сумма изъятия)
<saleAmount_before> </saleAmount_before>   (сумма в денежном ящике до изъятия)
</cashBox>

Свойства товаров (весь справочник, в СуперМаг+ – справочник «Размеры»):

<Properties fullness=”F”>
<version=””>
<Property> // minOccurs=”0” maxOccurs="unbounded"
<id></id>
<name></name>                    (название дополнительной характеристики в СуперМаг+)
<PropertyValue>
<value></value>
</PropertyValue>
</Property>
</Properties>

Налоговые группы (весь справочник):

<taxes fullness=”F”>
<version=””>
<group>// minOccurs=”0” maxOccurs="unbounded"
<id></id>
<code></code>                       (в СуперМаг+ – «Тип группы» – украинские группы А,B,C…)
<tax> // minOccurs=”0” maxOccurs="unbounded"
<id></id>
<name></name>
<sequence></sequence>         (в СуперМаг+ – «Приоритет начисления налога)
<percent></percent>
</tax>
</group>
<taxes/>

Структура магазинов (отделы) (весь справочник):

<stocks fullness=”F”>
<version=””>
<store storeId=””> // minOccurs=”0” maxOccurs="unbounded"
<stock> // minOccurs=”0” maxOccurs="unbounded"
<id></id>                                («Код магазина» в СуперМаг+)
<name></name>
</stock>
</store>
</stocks>

Классификатор товаров (весь справочник):

<classif fullness=”F”>
<version=””>
<group> // minOccurs=”0” maxOccurs="unbounded"
<id></id>
<owner></owner>
<name></name>
</group>
</classif>

Товары (может быть весь справочник или только изменения):

<updateItems fullness=”F/I”>
<version=””>
<item>// minOccurs=”0” maxOccurs="unbounded"
<article></article>
<name></name>
<measure></measure>           (Сокращение)
<measprec></measprec>        (Точность – 1, 0.001, 0.01, 0.1)
<groupId></groupId>             (ссылка на узел классификатора)
<egaisType></egaisType>       ((int), признак акцизного товара; 0 – неакцизный товар, 1 – маркированный товар,
                                                  2 – немаркированный, 3 - специальный маркируемый)
<propertyId></PropertyId>     (в СуперМаг+ – «Свойство», в СуперМаг+ к товару может быть
                                                  привязано только одно свойство)
<taxgroupId></taxgroupId>
<addProperty> // minOccurs=”0” maxOccurs="unbounded"
<id></id>                                 («Код доп. характеристики» в СуперМаг+)
<value></value>
</addProperty>
<barcode> // minOccurs=”0” maxOccurs="unbounded"
<id></id>                                 (сам штрихкод)
<PropertyValue></PropertyValue>
<quantity></quantity>            (в СуперМаг+ – «Количество для штрихкода»)
</barcode>
</item>
</updateItems>

PropertyId  привязывается к товару в УКМ 4, как тип свойства (используется для выбора значения на кассе при продаже по артикулу).

<PropertyValue> из <barcode> привязывается к штрих-коду товара как значение.

<addProperty> хранится как денормализованный справочник.

Значение параметра <NOPDF> должно быть в следующем виде:

<nopdf  article="ХХХХХ" code="ХХХ" bname="ХХХ ХХХ" alc="ХХХ" volume="ХХХ"/>.

В целом, запись о маркировке товара должна выглядеть таким образом:

<NOPDF> <nopdf  article="ХХХХХ" code="ХХХ" bname="ХХХ ХХХ" alc="ХХХ" volume="ХХХ"/> </NOPDF>.

Если внутри значения атрибута bname необходимо использовать кавычки, то заменять их нужно по следующим правилам:

• если для указания значения атрибута используются двойные кавычки, такие же кавычки внутри значения атрибута заменяются на сущность &quot;;
• если для указания значения атрибута используются одинарные кавычки, такие же кавычки внутри значения атрибута заменяются на сущность &apos;;
• можно использовать двойные кавычки внутри значений атрибутов, заключенных в одинарные кавычки, и наоборот.

Наборы – (может быть весь справочник или только изменения):

<kit fullness=”F/I”>
<version=”1.0”>
<item article =””> // minOccurs=”0” maxOccurs="unbounded"
<subItem> // minOccurs=”0” maxOccurs="unbounded"
<article></article>        (артикул товара, входящего в набор)
<quantity></quantity> (количество товара, десятичное число)
</subItem >
</item>
</kit>

Розничные цены магазина (может быть весь справочник или только изменения):

<storePrices fullness=”F/I” storeId=””> 
<version=”1.1”>
<item article=””>// minOccurs=”0” maxOccurs="unbounded"
<price> // minOccurs=”0” maxOccurs="1"
<value></value>
<minprice></minprice>        (минимальная цена продажи в денежных единицах)
<MRC> // minOccurs=”0” maxOccurs="unbounded"
<MRCValue> </MRCValue>  (значение цен из истории)
</MRC>
</price>
</item>
</storePrices>

Если в теге значения цены и мин. цены пропущены (то есть только теги <price> </price>), то соответствующая запись в прайс-листе в УКМ 4 будет удалена.

Флаг полной выгрузки приводит к тому, что УКМ 4 удаляет текущее содержание прайс-листа и загружает его новое содержимое.

Продавцы магазина (весь справочник):

<storeSellers fullness=”F” storeId=””>
<version=””>
<seller> // minOccurs=”0” maxOccurs="unbounded"
<id></id>
<name></name>
</seller>
</storeSellers>

Назначение товаров на отделы магазина (весь справочник):

<itemStoreStock fullness=”F” storeId=””>
<version=””>
<item article=””>
<stockId></stockId> // minOccurs=”0” maxOccurs="1"
</item>
</itemStoreStock>

Кассиры магазина (весь справочник):

<storeCashiers fullness=”F” storeId=””>
<version=””>
<cashier> // minOccurs=”0” maxOccurs="unbounded"
<id></id>                              (целое число больше 0)
<name></name>                  (символьная строка – 40 символов)
<INN>                                    (строка 12 символов, может быть пустой (для совместимости: может отсутствовать))
<password></password>      (символьная строка – 15 символов. Выгружается без шифрования)
</cashier>
</storeCashiers>

Значение параметра <NOPDF> передается в виде:

<nopdf article="ХХХХХ" code="ХХХ" bname="ХХХ ХХХ" alc="ХХХ" volume="ХХХ"/>.

Требования к загрузке налоговых ставок

В связи с добавлением в УКМ 4 функционала автоматического мапирования ставок НДС, со стороны УКМ 4 имеются новые требования к загрузке налоговых ставок через конвертеры. Для работы алгоритма автоматического выбора индекса ставки для ККТ при передаче данных о налогах через конвертеры УКМ 4 требуется указанием формулы налоговой ставки НДС в заданном виде.

Список ставок НДС, ожидаемых конвертерами УКМ 4

1. В случае, если формулы ставок отличаются от рекомендуемых, то товары могут быть добавлены в чек с некорректной ставкой налога.

Примечание: Для ставок НДС 10%, 18%, 20% допустима форма передачи процента ставки: "XX%" и "XX.00%", например, 10.00% является допустимым значением ставки при передаче через конвертер.

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

3. Ставка Не облагается может отсутствовать в справочнике налогов в нескольких случаях (это не вызовет проблем в работе кассовой системы):

• При использовании опции Формировать налоговые ставки автоматически, в соответствии с ФЗ РФ для заказчиков с неосновной системой налогообложения в чек всегда будет добавляться корректная ставка Не облагается – независимо от того, как заданы параметры ставки для списка карточек товаров для импорта.

• Ставка Не облагается будет автоматически использоваться УКМ 4 при пустом справочнике налогов для добавления товаров в чек. Актуально для пользователей с неосновной системой налогообложения, которые не выгружают налоги в УКМ 4 с любыми конвертерами.
• Ставка Не облагается будет использоваться УКМ 4 для объектов пользователя с неосновной системой налогообложения во всех случаях: даже если эта ставка не загружена в справочник налогов УКМ 4, не выбрана для товаров, и справочник налогов не пуст. Актуально для пользователей, которые в одной системе УКМ 4 поддерживают работу как магазинов с основной системой налогообложения, так и магазинов с любой неосновной системой налогообложения (например, ЕНДВ).