Назначение конвертера
Конвертер предназначен для выгрузки информации из базы данных кассовой системы во внешнюю торговую систему (бэк-офис).
Передача происходит с помощью файлов. Формат представления информации – XML. Кодировка – UTF-8, при передаче выполняется автоматическое экранирование спец. символов.
Правила выгрузки информации
Кассовая система выгружает информацию следующих типов:
- чеки (оперативная выгрузка);
- открытие кассовой смены;
- операции внесения/изъятия из денежного ящика;
- закрытие кассовой смены (включает все чеки за смену).
Каждый документ (включая каждый чек) помещается в отдельный файл.
Информация о новом чеке, открытии смены, внесении/изъятии выгружается конвертером сразу после появления соответствующей информации в базе сервера.
Информация о закрытии смены выгружаются только, если в базе сервера есть все чеки по данной смене. Файл со сменой в своей структуре содержит также все её чеки.
При формировании файлов с информацией, УКМ 5 сначала формирует в каталоге выгрузки временный файл с нестандартным именем, а после окончания формирования переименовывает его в стандартное имя.
Порядок выгрузки информации
Если в момент начала работы конвертера на сервере есть документы, относящиеся к нескольким сменам, или производится ручная выгрузка нескольких смен, то для каждой кассы выгружается блок, состоящий из следующих пакетов:
- все операции с денежным ящиком;
- все открытия смен;
- все чеки;
- все закрытия смен.
В каждом пакете информация упорядочена по возрастанию номеров смен.
Блоки с информацией по разным кассам никак не упорядочены.
Если по каким-либо причинам один и тот же документ выгружается повторно, а в выходном каталоге файл с этим же документом уже был создан ранее, то он будет заменён последней версией.
Имена файлов
Файлы с чеками | receipt_[Store]_[PosNum]_[ShiftNum]_[Receipt]_[1].xml |
Файлы со сменами | shift_[Store]_[PosNum]_[ShiftNum]_[1].xml |
Файлы с информацией об открытии смены | shiftOpen_[Store]_[PosNum]_[ShiftNum]_[1].xml |
Файлы с операциями с денежным ящиком (внесения/изъятия) | cashbox_[Store]_[PosNum]_[ShiftNum]_[DocNum]_[1].xml |
Здесь:
Receipt, shift, shiftOpen, cashBox — название головного тега документа.
Store – идентификатор магазина во внешней системе.
PosNum – номер кассы в кассовой системе.
ShiftNum – уникальный идентификатор кассовой смены в кассовой системе.
Receipt – номер чека в смене.
DocNum – номер документа внесения/изъятия.
Последний параметр [1] – номер выгрузки данного элемента..
Пример:
receipt _[1112]_[15]_[254]_[32]_[1].xml – чек из магазина 1112, касса 15, ID смены 254, чек 32.
Внимание!
ShiftNum – это непосредственно идентификатор, присвоенный смене кассовой программой. Идентификатор уникален в течение всей жизни кассы, как программного объекта, и не зависит от смены ККТ, подключенной к кассе, и/или замены в ней фискального накопителя.
Номер смены, присвоенный смене ККТ, выгружается в составе файла Shift в теге <kkm_shift_number>.
Структуры файлов
Оперативные чеки
Примечание | Обяз. | Формат в конверторе | |
<receipt storeId=”” posNum=”” shiftNum=”” receiptNum=””> | |||
storeId | идентификатор магазина во внешней системе | * | String(100) |
posNum | номер кассы в кассовой системе | * | Int(11) |
shiftNum | уникальный идентификатор кассовой смены в кассовой системе | * | Int(11) |
receiptNum | номер чека в смене | * | Int(11) |
<version>=”1.2” | версия формата документа | * | String(20) |
<receiptDateTime> | время закрытия чека | * | yyyy-MM-ddThh:mm:ss |
<receiptOpenDateTime> | время открытия чека | yyyy-MM-ddThh:mm:ss | |
<receiptSubtotalDateTime> | время последнего нажатия на клавишу Расчет | yyyy-MM-ddThh:mm:ss | |
<cashierCode> | код кассира | * | Int(11) |
<cashierName> | имя кассира | * | String(100) |
<type> | Тип чека | * | Int(11) 0-продажа |
<POSsale> | для чеков возврата - номер кассы, на которой была продажа) | Int(11) | |
<shiftNumSale> | для чеков возврата - номер смены, в которой была продажа) | Int(11) | |
<receiptNumSale> | для чеков возврата - номер чека продажи | Int(11) | |
<amount> | сумма чека, уменьшенная на величину скидок | * | Decimal (20.2) |
<item> | 0:∞ | ||
<position> | номер позиции | * | Int(11) Нумерация начинается с 1 |
<positionSale> | для чеков возврата - номер позиции в чеке продажи | * | Int(11) |
<article> | артикул товара | * | String(40) |
<barcode> | штрихкод товара (если он был введён по штрихкоду) | String(40) | |
<egaisBarcode> | штриховые коды алкогольных марок PDF417 | String(200) | |
<KIZ> | КИЗ - полное содержание кода маркированной продукции без дополнительной обработки. Кодировка BASE64. | String(255) | |
<serialNumber> - серийный номер, выделенный из кода DataMatrix (может отсутствовать) | Серийный номер, выделенный их КИЗ | String(20) | |
<maxPrice> | Максимальная розничная цена, выделенная из КИЗ (табак) | Decimal (20.2) | |
<quantity> | количество товара в позиции | * | Decimal (20.3) |
<price> | цена товара по прайс-листу | * | Decimal (20.2) |
<total> | стоимость позиции, уменьшенная на величину скидок | * | Decimal (20.2) |
<enterType> | способ ввода товара в чек | * | Int(11) 0 – сканер, заказ, распознавание 10 – прочие способы |
<sellerId> | код продавца | String(50) | |
<sellerName> | фамилия продавца | String(50) | |
<stockId> | Номер отдела | Int(11) | |
<Property> | Код доп.свойства (размер) | String(20) | |
<PropertyValue> | Значение доп.свойства (размер) | String(20) | |
<Tax> | 0:∞ | ||
<TaxGroupId> | Код налоговой группы | * | Int(11) |
<TaxId> | Код налога | * | Int(11) |
<TaxName> | Название налога | * | String(40) |
<percent> | Ставка налога | * | Decimal (20.2) |
<amount> | Сумма налога, рассчитанная кассой | * | Decimal (20.2) |
</Tax> | |||
<discount> | скидки, которые привели к изменению суммы продажи | 0:∞ | |
<programId> | код скидки в УКМ | * | Int(11) |
<programName> | название скидки в УКМ | * | String(40) |
<programType> | тип системы лояльности | * | Int(11) |
<amount> | значение скидки - положительное число | * | Decimal (20.2) |
<discCardNumber> | номер диск.карты, но не клубной карты! | String(40) | |
</discount> | |||
<addition> | наценки, которые привели к изменению суммы продажи | 0:∞ | |
<programId> | код скидки в УКМ | * | Int(11) |
<programName> | название скидки в УКМ | * | String(40) |
<programType> | тип системы лояльности | * | Int(11) |
<amount> | значение наценки - положительное число | * | Decimal (20.2) |
<discCardNumber> | номер диск.карты – номер карты, возвращенный loya | String(40) | |
</addition> | |||
</item> | |||
<TaxTotal> | Суммы налогов по чеку | 0:∞ | |
<TaxGroupId> | Код налоговой группы | * | Int(11) |
<TaxId> | Код налога | * | Int(11) |
<TaxName> | Название налога | * | String(40) |
<percent> | Ставка налога | * | Decimal (20.2) |
<amount> | Сумма налога | * | Decimal (20.2) |
</TaxTotal> | |||
<removedItems> | Отменёнными позициями | 0:∞ | |
<item> | структура такая же, как у нормально завершённых чеков, но добавлен тег <supervisor> | ||
<position> | * | Int(11) | |
<article> | * | String(40) | |
<barcode> | * | String(40) | |
<quantity> | * | Decimal (20.3) | |
<price> | * | Decimal (20.2) | |
<total> | * | Decimal (20.2) | |
<stockId> | Int(11) | ||
<enterType> | * | Int(11) | |
<supervisor> | кассир, разрешивший операцию отмены позиции | 1:1 | |
<id> | * | Int(11) | |
<name> | * | String(100) | |
</supervisor> | |||
</item> | |||
</removedItems> | |||
<gift> | 0:∞ | ||
<loyalty_type> | тип системы лояльности, выдавшей подарок | * | Int(11) |
<article> | артикул товара, выданного как подарок | * | String(40) |
<quantity> | количество товара-подарка | * | Decimal (20.3) |
<programId> | id скидки в УКМ, которая инициировала выдачу данного подарка | Int(11) | |
<programName> | Название скидки, которая инициировала выдачу данного подарка | String(40) | |
</gift> | |||
<loyality_used_gifts> | |||
<loyalty_type> | тип системы лояльности, выдавшей подарок | ||
<item> | артикул товара, выданного как подарок | ||
<quantity> | количество товара-подарка | ||
</loyality_used_gifts> | |||
<loyality_cardNum> | номер карты клиента | 0:∞ | |
<loyalty_type> | тип внешней системы лояльности | * | Int(11) |
<card_num> | номер карты покупателя в системе лояльности | * | String(128) |
</loyality_cardNum> | |||
<loyality_used_coupons> | применённые в чеке купоны | 0:∞ | |
<loyalty_type> | тип внешней системы лояльности | * | Int(11) |
<coupon_num> | номер полученного купона | * | String(40) |
<coupon_amount> | использованная сумма купона(если она определена) | Decimal (20.2) | |
</loyality_used_coupons> | |||
<loyality_award_coupons> | выданные купоны | 0:∞ | |
<loyalty_type> | тип внешней системы лояльности | * | Int(11) |
<coupon_num> | номер выданного купона | * | String(40) |
<coupon_amount> | сумма купона(если она определена) | Decimal (20.2) | |
</loyality_award_coupons> | |||
<payment> | оплаты по чеку | 1:∞ | |
<paymentId> | «тип» средства оплаты | * | Int(11) «тип» средства оплаты: если не включено мапирование средств оплаты в настройках конвертора Экспорта или не указан код, в который надо мапировать, то коды присваиваются по следующим правилам: 0 - Наличные" 101 – оплаты банк.авторизациями, включая «голосовые/ пустые» авторизации) 102 - Подарочный сертификат 103 – Оплата баллами с внутреннего счета или баллами внешних систем лояльности (кроме подар.сертификатов) 104 – Ранее полученные авансы/предоплаты 105 – Оплата в кредит |
<paymentName> | название средства оплаты в УКМ | * | String(40) <paymentId>=0 – «Наличные»; <paymentId>=101 – «Банковская карта»; <paymentId>=102 – «Подарочный сертификат»; <paymentId>=103 – «Оплата баллами» <paymentId>=104 – «Предоплата» <paymentId>=105 – «Кредит» |
<paymentAmount> | * | Decimal (20.2) | |
<maskedCardNumber> | Маскированный номер банковской карты при наличии данных | String(100) | |
<cardType> | Тип банковской карты, при наличии данных | String(100) | |
<authCode> | Код банковской авторизации, при наличии данных | String(100) | |
<rrn> | Код ссылки банковской авторизации, при наличии данных | String(100) | |
</payment> | |||
</receipt> |
Внесение/изъятие в/из денежного ящика
Примечание | Обяз. | Формат конвертора | |
<cashBox storeId=”” posNum=”” shiftNum=”” docNum=””> | Аналогично чеку (docNum - Int(11)) | ||
<version>=”1.0” | * | String(20) | |
<dateOper> | * | String(“yyyy-MM-ddTHH:mm:ss”) | |
<operCode> | код операции | * | Int(11) 100 – внесение 101 – изъятие |
<cashierCode> | код кассира | * | Int(11) |
<cashierName> | имя кассира | * | String(100) |
<saleAmount> | сумма операции | * | Decimal (20.2) |
<saleAmount_before> | сумма в денежном ящике до выполнения операции | * | Decimal (20.2) |
</cashbox> |
СМ+ файл не загружает
Отрытие смены
Примечание | Обяз. | Формат конвертора | |
<shiftOpen storeId=”” posNum=”” shiftNum=”” | * | Аналогично чеку | |
<version>=”1.0” | * | String(20) | |
<dateOpen> | * | String(“yyyy-MM-ddTHH:mm:ss”) | |
<cashierCode> | кассир открывший смену | * | Int(11) |
<cashierName> | * | String(100) | |
</shiftOpen> | |||
СМ+ файл не загружает.
Закрытие смены
Примечание | Обяз. | Формат в конверторе | |
<shift storeId=”” posNum=”” shiftNum=””> | * | Аналогично чеку | |
<version>=”1.2” | * | String(20) | |
<dateClose> | * | String(“yyyy-MM-ddTHH:mm:ss”) | |
<kkm_shift_number> | номер смены по ККТ | * | Int(11) |
<kkm_serial_number> | заводской номер ККТ (при закрытии смены без ККТ тег будет отсутствовать) | String(40) | |
<kkm_registration_number> | регистрационный номер ККТ (при закрытии смены без ККТ тег будет отсутствовать) | String(40) | |
<kkm_model_name> | название модели ККТ (при закрытии смены без ККТ тег будет отсутствовать) | String(40) | |
<cashierCode> | кассир закрывший смену | * | Int(11) |
<cashierName> | * | String(100) | |
<saleAmount> | сумма всех чеков продажи за смену по данным УКМ (сумма чека за минусом скидок) | * | Decimal (20.2) |
<returnAmount> | сумма всех чеков возвратов за смену по данным УКМ | * | Decimal (20.2) |
<kkm_saleAmount> | сумма всех чеков продажи за смену по данным ККТ | * | Decimal (20.2) |
<kkm_returnAmount> | сумма всех чеков возвратов за смену по данным ККТ | * | Decimal (20.2) |
<saleCount> | количество чеков продаж за смену по данным УКМ | * | Int(11) |
<returnCount> | количество чеков возвратов за смену по данным УКМ | * | Int(11) |
<kkm_saleCount> | кол-во чеков чеков продажи за смену по данным ККТ | Int(11) | |
<kkm_returnCount> | кол-во чеков возвратов за смену по данным ККТ | Int(11) | |
<kkm_withdrawal> | кол-во изъятий по данным ККТ | Int(11) | |
<kkm_insertion> | кол-во внесений по данным ККТ | Int(11) | |
<payment> | оплаты по смене | 0:∞ | |
<paymentId> | * | Int(11) Правила формирования как для чека | |
<paymentName> | название средства оплаты в УКМ | * | String(40) Правила формирования как для чека |
<paymentAmountSale> | сумма оплат данным средством за смену по данным УКМ | * | Decimal (20.2) |
<paymentAmountReturn> | сумма возвратов данным средством за смену по данным УКМ | * | Decimal (20.2) |
<kkm_paymentAmountSale> | сумма оплат данным средством за смену по данным ККТ | Decimal (20.2) | |
<kkm_paymentAmountReturn> | сумма возвратов данным средством за смену по данным ККТ | Decimal (20.2) | |
</payment> | |||
<receipt storeId=”” posNum=”” shiftNum=”” receiptNum=””> | Перечень нормально завершённых чеков | 0:∞ | |
Структура такая же, как у Оперативных чеков | |||
</receipt> | |||
<receipt storeId="" posNum="" shiftNum="" receiptNum="" cancelled="true"> | Перечень отменённых (аннулированных) чеков | 0:∞ | |
<receiptDateTime> | |||
<receiptOpenDateTime> | * | ||
<cashierCode> | * | Int(11) | |
<cashierName> | * | String(100) | |
<type> | * | Int(11) (аналогично оперативному чеку) | |
<amount> | |||
<supervisor> | кассир, разрешивший отмену | * | |
<id> | * | Int(11) | |
<name> | * | String(100) | |
</supervisor> | |||
<item> | 0:∞ | ||
<position> | * | Int(11) | |
<article> | * | String(40) | |
<barcode> | String(40) | ||
<quantity> | * | Decimal (20.3) | |
<price> | * | Decimal (20.2) | |
<total> | * | Decimal (20.2) | |
<stockId> | Int(11) | ||
<enterType> | * | Int(11) Возможные значения как для чека | |
</item> | |||
</receipt> | |||
</shift> | |||
Проблемы
- Выгрузка доп.свойств
В структуре чека есть поля <property> и <propertyValue>. В УКМ4 и СМ+ это механизм работы с «размерами» (кассир продает ботинки и выбирает размер из списка). Похоже, что на настоящий момент, функционал не востребован.
В УКМ5, к сожалению, эти же поля используются для других целей и, что хуже, в другом формате:
<property>
<id>ид</id>
<name>название</name>
<value>
<id>ид значения</id>
<name>название значения</name>
</value>
</property>.
Фактически это означает, что если в чеке УКМ5 будет зафиксировано доп.свойство (в том числе и выгруженное из внешней системы – например, «код индивидуального средства защиты»), то … СМ+ такой чек не примет.
- Информация о подарках
В чеках 2 тега с выданными подарками - <loyality_used_gifts> и <gift>.
УКМ4 заполняет оба тега, УКМ5 - тег <gift>, СМ+ загружает подарки из <gift>.