История страницы

Назначение конвертера

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

Передача информации в кассовую систему

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

Формат представления информации – XML. Кодировка – UTF-8. Десятичный разделитель – точка (УКМ 4 допускает разделитель запятую).

Поля, связанные с передачей ИНН (кассира, поставщика и т.д.) УКМ 5 проверяет на соответствие правилам формирования в РФ, УКМ 4 – не проверяет.

Если текстовые поля (например, названия товаров, магазинов и т.д.) содержат служебные символы языка XML, то они заменяются на следующие последовательности:

Пример:

Название товара – Конфеты “M&Ms” – должно быть передано в следующем виде:

<updateItems fullness=”I”>

       <version=”1.0”>

       <item>

              <article>002565</article>          

              <name>Конфеты &quot;M&amp;Ms&quot;</name>

…

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

Торговая система выгружает файлы с информацией в каталог, доступный для конвертера. Конвертер должен иметь доступ к данному каталогу с правами на чтение, запись и удаление файлов.

Торговая система должна сначала сформировать файл, а затем сделать его доступным для кассовой системы путем переименования файла (создание и переименование должны происходить в рамках одного дискового пространства, без копирования файла с одного диска на другой).

После обработки файла кассовая система удаляет его из каталога (переносит в каталог с архивом загруженных файлов).

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

Типы передаваемой информации

Якорь
filenames filenames

Имена файлов

Имена файлов имеют формат TAGNAME_[Store]_[Number]_[P]_[Error].xml, где:

TAGNAME – название выгружаемой информации; должно совпадать с названием головного тега в XML-файле.

Store – код (идентификатор) магазина в торговой системе; может быть переменной длины.

Параметр Store может содержать любые печатные английские символы, кроме символа пробела.

Для файлов regions, stores, storeTypes, taxes, updateItems, classif и picklists параметр Store не указывается (т.к. информация предназначена для всех магазинов).

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

P – признак полноты информации в файле:

• F – файл содержит полный перечень элементов ("полная" выгрузка)
• I – файл содержит неполный перечень элементов ("инкрементальная" выгрузка)

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

Примеры:

1) storePrices_[$112]_[1]_[I].xml – файл с ценами, где:

 [$112] – код магазина во внешней системе;

[1] – пакет номер 1;

[I] – файл содержит только изменения цен (новые и изменившиеся значения).

2) classif_[2]_[F].xml – классификатор товаров (товарные группы), где:

[2] – пакет номер 2;

[F] – файл содержит полный товарный классификатор.

Порядок формирования номеров файлов

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

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

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

Для упрощения процедуры формирования имён файлов, торговая система может вести сквозную нумерацию своих выгрузок и каждому файлу присваивать очередной порядковый номер или только младшие разряды номера выгрузки (например, 4 младшие разряда).

Правила обработки файлов конвертером 

1. Конвертер обрабатывает файлы с параметром I (increment) следующим образом:

    - если элемент отсутствует в кассовой системе, то он добавляется в систему;

    - если элемент есть в кассовой системе, то существующее значение полностью замещается на новое.

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

2. При загрузке файлов с признаком F, соответствующая информация в кассовой системе полностью заменяется на информацию из загружаемых файлов, с учетом типа информации: для всех магазинов или только для конкретного. Если изменений в каких-либо уже загруженных в кассовую систему файлах во внешней системе не было, то в кассовой системе новые файлы соответствующих типов не создаются.

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

Флаг полной выгрузки для товаров учитывается только для формирования последовательности их обработки во входном каталоге (см. пункт 5). 

3. Если выгруженный файл любого типа не содержит тегов с информацией, то он не будет воспринят как ошибочный, никаких изменений после его обработки не произойдёт.

4. Кассовая система обрабатывает каждый файл как транзакцию, т.е. он или обрабатывается целиком или не обрабатывается вообще. Каждый файл обрабатывается независимо от другого.

5. При обработке файлов во входном каталоге для каждого типа информации кассовая система ищет файл полной выгрузки с наибольшим номером, загружает его, а затем – и все последующие файлы с инкрементной выгрузкой (этого же типа). Другими словами, если во входном каталоге накопилось много файлов одного типа, то загрузка начнётся с файла с флагом полной выгрузки с максимальным номером.

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

7. Кассовая система переносит все файлы из входного каталога в подкаталог Archive, добавляя к концу имени дату и время его обработки (в формате YYYYMMDDHHMMSS). При этом, если файл был загружен, то в конец имени дописывается Load, если файл был пропущен – Ignor.

8. Если при обработке файла возникли ошибки любого типа (как связанные с доступом к файлу, так и с его содержанием), то он не обрабатывается целиком, в конец имени добавляется Error и он переносится в подкаталог Archive. Работа конвертера продолжается далее в штатном режиме.

Версионность

Каждый файл с данными в своем начале должен содержать тег version="MJ.MN", описывающий версию формата данных соответствующего типа информации. Номера представляются в виде целого положительного числа (например, version="1.0").

Здесь MJ означает номер «мажорной» версии, MN означает номер «минорной» версии.

Логика изменения номеров версий заключается в следующем:

- если в новой версии формата данных произошли изменения, в результате которых новый формат данных стал несовместим с прежним форматом, то номер «мажорной» версии увеличивается на 1;

- если изменения совместимы с прежним форматом, то увеличивается номер «минорной» версии.

На практике это означает, что при изменении MJ-номера формата, версия конвертера, работающая с прежним форматом, не будет обрабатывать файлы с новым форматом и, наоборот, версия конвертера с новым форматом не будет обрабатывать файлы со старым форматом.

Если изменился MN-номер (но не изменилась MJ-номер), то файлы будут обрабатываться, но «незнакомые» для конвертера теги будут пропущены.

Структуры файлов импорта

Условные обозначения в столбце "Обязательность":

            * – значение должно указываться;

            1:∞ – секция должна быть указана хотя бы один раз;

            0:∞ – секция может быть не указана;

            1:1 – секция должна быть, и только одна.

Якорь
regions regions

REGIONS – Регионы

Особенности

Якорь
storetypes storetypes

STORETYPES – Типы магазинов

Особенности

Якорь
stores stores

STORES – Магазины

Особенности

Якорь
taxes taxes

TAXES – Налоговые группы

Ограничения

Якорь
classif classif

CLASSIF – Классификатор товаров

Якорь
updateitems updateitems

UPDATEITEMS – Товары

Несмотря на то, что файл может быть выгружен с признаком полной выгрузки fullness=”F”, товарный справочник не перезаписывается (как вывод из этого – невозможно удалить товары из справочника, но можно удалять цены). Признак полной выгрузки анализируется только для определения порядка загрузки файлов.

Правила обработки некоторых полей

barcode.id – штрихкод товара. Штрихкод уникален среди всего товарного справочника (т.е. в один и тот же момент времени в товарном справочнике один штрихкод не может быть привязан более, чем к одному товару). Т.к. штрихкоды входят в состав описания товара, то штрихкод будет привязан к тому товару, который был выгружен из торговой системы последним.

barcode.quantity – количество товара, с которым он добавляется в чек при вводе данного штрихкода. Торговая система должна устанавливать это значение следующим образом:

   - для штучного товара (товар с measprec = 0):

      - если штрихкод соответствует упаковке, то в данном поле должно быть установлено значение, равное количеству товара в упаковке;

      - в противном случае, значение должно быть равным 1;

   - для товаров с другими значениями measprec (весовых/мерных) должно быть установлено значение 0.

Комментарии к реализации в УКМ 4 и УКМ 5

productAlcCodes – c СуперМаг+ и УКМ 4 реализован контроль за соответствием штрихкода, считанного с бутылки, введенной алкомарке. Функционал работает только для марок старого образца (68 символов); в новых марках код алкогольной продукции отсутствует. В УКМ 5 данный функционал не поддержан.

TNVDcode – первоначально, маркировка товаров предполагала, что для тега 1162 префикс кода будет формироваться на основании принадлежности товаров к группам ТН ВЭД, но в нынешнем стандарте префикс тега формируется на основании типа считанного штрихкода кода. В УКМ 5 данный функционал не поддержан.

Особенности продажи товаров по договорам комиссии или агентским договорам

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

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

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

В УКМ 5 загрузка информации о поставщиках товара через XML-конвертер не происходит. При реализации загрузки возможна правильная загрузка (в привязке к магазинам) – внутренняя структура УКМ 5 позволяет это сделать, однако для этого потребуется изменение XML-протокола. Способы реализации товаров по агентским или комиссионным договорам в УКМ 5 подробно описаны здесь и осуществляются через web-сервисы. Особенности работы с налоговыми ставками изложены тут.

Кодирование весовых товаров

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

Касса выделяет в ведённом штрихкоде вес товара, а оставшуюся часть кода использует для поиска товара в товарном справочнике (поиск происходит сначала среди штрихкодов, и если подходящий штрихкод не находится, то поиск продолжается среди артикулов). Таким образом, код товара (или штрихкод) в товарном справочнике не должен иметь «весовой» части.

Например, если на весовой этикетке имеется следующий код – ХХХХХХХККГГГС, то касса будет искать в базе данных товар с кодом (штрихкодом) ХХХХХХХ (а не ХХХХХХХ00000С) и если не найдет его, то будет выведено сообщение об ошибке.

Якорь
barcodeprop barcodeprop

BARCODEPROPERTY – Дополнительные свойства штрихкодов

Особенности

Якорь
properties properties

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

Особенности

Якорь
kit kit

KIT – Наборы

Особенности

Комментарии к реализации

Устаревший функционал, предназначавшийся для реализации работы с алкогольными товарами, входящими в наборы: если в набор входил один или несколько акцизных товаров, то касса запрашивала ввод акцизных марок по количеству акцизных товаров в чеке, регистрировала их все в УТМ со штрихкодом товара-набора, а в чеке акцизные марки сохраняла в привязке к товару-набору.

Согласно актуальным не сегодняшний день правилам, алкоголь отнесен к маркированным товарам, соответственно, нельзя к одной позиции привязать несколько акцизных марок,  т.е. набор не может содержать более одного алкогольного товара – но тогда становится ненужной сама структура набора, т.к. достаточно товар-набор объявить маркированным товаром (его состав для кассы не важен).

Якорь
pickl pickl

PICKLISTS – Пик-листы

Особенности

Якорь
stocks stocks

STOCKS – Отделы магазина

Особенности

Якорь
tnvdcode tnvdcode

TNVDCODE – Справочник кодов ТН ВЭД

Особенности

Якорь
suppliers suppliers

SUPPLIERS – Справочник поставщиков

Особенности

Якорь
storeprices storeprices

STOREPRICES – Розничные цены магазина

Для товара может быть указана только одна цена.

Поле minprice является обязательным для УКМ 4.

Выгрузка файла с fullness=”F” приводит к замене цен для магазина.

Если секция price для товара указана, но секция пуста (<price> </price>), то для этого товара цена будет удалена. Если значение price.value отсутствует, то возникнет ошибка загрузки и файл не загрузится.

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

Если для MRC не указано значение MRCMinPrice (т.е. тег пропущен или отсутствует), то в момент загрузки конвертер установит его значение в MRCValue (т.е. скидки на альтернативные цены будут запрещены).

Если не указано значение MRCComment (т.е. тег пропущен или отсутствует), то в момент загрузки конвертер установит его значение в Дополнительная цена (УКМ 4 данное поле не загружает).

Особенности

Якорь
spa spa

STOREPRICESADD – Дополнительные прайс-листы

Особенности

Якорь
storesellers storesellers

STORESELLERS – Продавцы магазина

Якорь
storecashiers storecashiers

STORECASHIERS – Кассиры магазина

Особенности 

Якорь
iss iss

ITEMSTORESTOCK – Назначение товаров на отделы магазина

Особенности

Якорь
rests rests

STORERESTOFGOODS – Остатки товаров в конкретном магазине

Особенности