Описание передаваемой информации и правила работы с ней
Тип информации | Имя файла и головного тега | Тип выгрузки |
---|---|---|
Общая информация (одинаковая для всех магазинов) | ||
Справочник свойств товаров | properties | всегда полная |
Справочник налогов | taxes | всегда полная |
Справочник отделов магазинов | stocks | всегда полная |
Товарный классификатор | classif | всегда полная |
Товары (включая штрихкоды и дополнительные характеристики товаров) | updateItems | полная/частичная |
Информация для магазинов | ||
Цены на товары | storePrices | полная/частичная |
Продавцы | storeSellers | всегда полная |
Привязка товаров к отделам магазина | itemStoreStock | всегда полная |
Кассиры | storeCashiers Пример: storeCashiers _[5]_[1]_[F].xml [5] – код магазина во внешней системе; [1] – номер выгрузки п/п; [F] – флаг, что файл содержит полный перечень кассиров | всегда полная |
Имена файлов
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 необходимо использовать кавычки, то заменять их нужно по следующим правилам:
- если для указания значения атрибута используются двойные кавычки, такие же кавычки внутри значения атрибута заменяются на сущность ";
- если для указания значения атрибута используются одинарные кавычки, такие же кавычки внутри значения атрибута заменяются на сущность ';
- можно использовать двойные кавычки внутри значений атрибутов, заключенных в одинарные кавычки, и наоборот.
Наборы – (может быть весь справочник или только изменения):
<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
№ | Рекомендуемое значение ставки до 01.01.2019 | Рекомендуемое значение ставки после 01.01.2019 | Допустимые варианты значений | Описание |
---|---|---|---|---|
1 | 18% | 20% | 18.00%, 20.00% | НДС 18%/ НДС 20% |
2 | 10% | 10% | 10.00% | НДС 10% |
3 | 0% | 0% | 0.00% | НДС 0% |
4 | Не облагается | Не облагается | Без НДС | |
5 | 18/118% | 20/120% | НДС 18/118 / НДС 20/120 | |
6 | 10/110% | 10/110% | НДС 10/110 |
1. В случае, если формулы ставок отличаются от рекомендуемых, то товары могут быть добавлены в чек с некорректной ставкой налога.
Примечание: Для ставок НДС 10%, 18%, 20% допустима форма передачи процента ставки: "XX%" и "XX.00%", например, 10.00% является допустимым значением ставки при передаче через конвертер.
2. Регистр для значения ставки Не облагается при передаче данных конвертеру можно указывать любой.
3. Ставка Не облагается может отсутствовать в справочнике налогов в нескольких случаях (это не вызовет проблем в работе кассовой системы):
- При использовании опции Формировать налоговые ставки автоматически, в соответствии с ФЗ РФ для заказчиков с неосновной системой налогообложения в чек всегда будет добавляться корректная ставка Не облагается – независимо от того, как заданы параметры ставки для списка карточек товаров для импорта.
- Ставка Не облагается будет автоматически использоваться УКМ 4 при пустом справочнике налогов для добавления товаров в чек. Актуально для пользователей с неосновной системой налогообложения, которые не выгружают налоги в УКМ 4 с любыми конвертерами.
- Ставка Не облагается будет использоваться УКМ 4 для объектов пользователя с неосновной системой налогообложения во всех случаях: даже если эта ставка не загружена в справочник налогов УКМ 4, не выбрана для товаров, и справочник налогов не пуст. Актуально для пользователей, которые в одной системе УКМ 4 поддерживают работу как магазинов с основной системой налогообложения, так и магазинов с любой неосновной системой налогообложения (например, ЕНДВ).