Page tree
Skip to end of metadata
Go to start of metadata

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

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

Передача происходит с помощью файлов. Формат представления информации – XML. Кодировка – UTF-8, при передаче выполняется автоматическое экранирование спец. символов.

Правила выгрузки информации

Кассовая система выгружает информацию следующих типов:

- чеки (оперативная выгрузка);

- открытие кассовой смены;

- операции внесения/изъятия из денежного ящика;

- закрытие кассовой смены (включает все чеки за смену).

Каждый документ (включая каждый чек) помещается в отдельный файл.

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

Информация о новом чеке, открытии смены, внесении/изъятии выгружается конвертером сразу после появления соответствующей информации в базе сервера.

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

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

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

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

Порядок выгрузки информации

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

- все операции с денежным ящиком;

- все открытия смен;

- все чеки;

- все закрытия смен.

В каждом пакете информация упорядочена по возрастанию номеров смен.

Блоки с информацией по разным кассам никак не упорядочены.

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

Имена файлов

Файлы с чеками

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, shiftOpencashBox — название головного тега документа.

Store – идентификатор магазина во внешней системе.

PosNum – номер кассы в кассовой системе.

ShiftNum – уникальный идентификатор кассовой смены в кассовой системе.

Receipt – номер чека в смене.

DocNum – номер документа внесения/изъятия.

Последний параметр [1]номер выгрузки данного элемента..


Пример:

receipt _[1112]_[15]_[254]_[32]_[1].xml – чек из магазина 1112, касса 15, ID смены 254, чек 32.


Внимание!

ShiftNum – это непосредственно идентификатор, присвоенный смене кассовой программой. Идентификатор уникален в течение всей жизни кассы, как программного объекта, и не зависит от смены ККТ, подключенной к кассе, и/или замены в ней фискального накопителя.

Номер смены, присвоенный смене ККТ, выгружается в составе файла shift в теге <kkm_shift_number>.

Структуры файлов экспорта

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

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

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

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

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

Внесение в/изъятие из денежного ящика


Примечание

Обяз.

Формат в конвертере

<cashBox

storeId=””

posNum=””

shiftNum=””

docNum=””>


Идентификатор магазина во внешней системе

Номер кассы в кассовой системе

Уникальный идентификатор кассовой смены в кассовой системе

Номер документа о внесении/изъятии в кассовой системе



String(100)

Int(11)

Int(11)

Int(11)

<version=””>

Значение указывается в кавычках


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=””


Идентификатор магазина во внешней системе

Номер кассы в кассовой системе

Уникальный идентификатор кассовой смены в кассовой системе

*


String(100)

Int(11)

Int(11)

<version=””>

Значение указывается в кавычках

*

String(20)

<dateOpen>


*

String(yyyy-mm-ddThh:mm:ss)

<cashierCode>

Кассир, открывший смену

*

Int(11)

<cashierName>


*

String(100)

</shiftOpen>




Особенности

СуперМаг+ – не загружает файл.

Оперативные чеки


Примечание

Обяз.

Формат в конвертере

<receipt

storeId=””

posNum=””

shiftNum=””

receiptNum=””>


Идентификатор магазина во внешней системе

Номер кассы в кассовой системе

Уникальный идентификатор кассовой смены в кассовой системе

Номер чека в смене



String(100)

Int(11)

Int(11)

Int(11)

<version=””>   

Версия формата документа. Значение указывается в кавычках

*

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 – продажа

1 – возврат

4 – возврат по исходному чеку

5 – продажа по восстановленному чеку

6 – расход

<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)

  <NOPDF>

Содержание QR-кода, если товар является алкогольной продукцией и кассиром был считан внутренний QR-код, наклеенный на бутылку

  <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 – сканер, заказ, распознавание

1 – клавиатура

2 – горячая клавиша/ пик-листы

10 – прочие способы

  <sellerId>

Код продавца


String(50)

  <sellerName>

Фамилия продавца


String(50)

  <stockId>

Номер отдела


Int(11)

  <addProperty>

Дополнительные свойства

     <id>Код свойства
String(40)
     <name>Название свойства
String(80)
     <value>


        <id>Значение свойства
String(100)
        <name>Название значения свойства
String(100)
     </value>


  </addProperty>


  <Property>Код дополнительного свойства (размер)
String(20)
  <PropertyValue>Значение дополнительного свойства (размер)
String(20)

  <Tax>


0:∞
      <TaxGroupId>Код налоговой группы*Int(11)
      <TaxId>Код налога*Int(11)
      <TaxName>Название налога*String(40)
      <percent>Ставка налога*String(40)
      <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>Номер дисконтной карты – не клубной карты!
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)

   <number>

Номер примененного в чеке сертификата (только для средства оплаты "Подарочный сертификат")*String(100)

   <balance>

Остаток на счете подарочного сертификата после оплаты им чека (только для средства оплаты "Подарочный сертификат")*Decimal(20.2)

   <maskedCardNumber>

Маскированный номер банковской карты, при наличии данных


String(100)

   <cardType>

Тип банковской карты, при наличии данных, или подарочный сертификат


String(100)

   <authCode>

Код банковской авторизации, при наличии данных


String(100)

   <rrn>

Код ссылки банковской авторизации, при наличии данных


String(100)

   <qrRequisites>

Сохраненные данные платежа для обмена со внешней системой
String(256)

   <cashOutSum>

Cумма выданных наличных при операции выдачи наличных
Decimal(20.2)

<banknotes>




   <banknote>
1:∞
      <nominal>Номинал купюры    *Int(11)
      <number>Номер купюры    *String(100)
   </banknote>


</banknotes>


</payment>


  <saleReceiptNum>

Номер (ID в смене) чека продажи, связанного с чеком расхода
Int(11)
</receipt>


Особенности

Группа <banknotes></banknotes> содержит информацию о номерах купюр и используется только в рамках соответствующего функционала УКМ 5.

В таблице присутствуют два тега с информацией о выданных подарках: loyality_used_gifts и giftУКМ 4 заполняет оба тега. УКМ 5 заполняет только тег gift

Поля number и balance поддерживаются только для УКМ 5.

СуперМаг+ загружает подарки из тега gift.

УКМ 5 передает значения дополнительных свойств товарной позиции в теге <addProperty> только в версии 1.2 конвертера XML. В прочих версиях конвертера для этой цели используются теги <property> и <propertyValue>, что может привести к некорректной передаче чеков в СуперМаг+.

УКМ 4 не выгружает перечень отменённых (аннулированных) чеков (<removedItems>): в частности, поля <cashOutSum> и <saleReceiptNum> для УКМ 4 выгружаться не будут.

УКМ 4 также не выгружает тэги <NOPDF><Tax> (и его содержимое), <TaxTotal> (и его содержимое), <addProperty> (и его содержимое); <loyalty_type=""> и <programName> в составе тэга <gift><coupon_amount=””> в составе тэга <loyality_used_coupons=””>, а также полное содержимое тэга <payment>.

Для ставки, соответствующей «НДС не облагается», в поле amount выгружается не сумма налога (0.00), а сумма товаров с налоговой ставкой «НДС не облагается». Размер ставок НДС выгружаются в том же формате, как они были загружены из торговой системы.

Расчет налогов кассой носит справочный характер и может не совпадать с расчетом налогов, сделанным ККТ (и переданным в ОФД), а также не совпадать с расчетом, сделанным в соответствии с правилами бухгалтерского учета.

УКМ 5 не выгружает тэги, а СМ+ не принимает тэги <Tax> и <TaxTotal>.

Закрытие смены


Примечание

Обяз.

Формат в конвертере

<shift

storeId=””

posNum=””

shiftNum=””>


Идентификатор магазина во внешней системе

Номер кассы в кассовой системе

Уникальный идентификатор кассовой смены в кассовой системе

*


String(100)

Int(11)

Int(11)

<version=””>

Значение указывается в кавычках

*

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)

«Тип» средства оплаты: если не включено мапирование средств оплаты в настройках конвертера экспорта или не указан код, в который надо мапировать, то коды присваиваются по следующим правилам:

0 – наличные

101 – оплаты банковскими авторизациями, включая голосовые/"пустые" авторизации

102 – подарочный сертификат

103 – оплата баллами с внутреннего счета или баллами внешних систем лояльности (кроме подарочных сертификатов)

104 – оплата в счет ранее полученных авансов/предоплат

105 – оплата в кредит

    <paymentName>Название средства оплаты в кассовой системе*

String(40)

<paymentId>=0 – наличные

<paymentId>=101 – банковская карта

<paymentId>=102 – подарочный сертификат

<paymentId>=103 – оплата баллами

<paymentId>=104 – предоплата

<paymentId>=105 –

кредит

    <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>




Особенности

УКМ 4 не выгружает перечень отменённых (аннулированных) чеков.