/
Беларусь ◾️ iKassa v2

Публичное пространство

Беларусь ◾️ iKassa v2

Описание

В связи с законодательными изменениями в Республике Беларусь для программного фискализатора iKassa был разработан новый протокол версии 2.0, поддерживающий работу с маркированными товарами.

 

Ценность

Поддержка законодательных изменений в части маркировки.

 

Глоссарий

  • СИ - средства идентификации

  • УКЗ - унифицированный контрольный знак

  • GTIN - Global Trade Item Number, глобальный номер товарной продукции в единой международной базе товаров GS1.

  • СКНО - средство контроля налоговых органов

  • СКО - средство контроля оператора

  • СККО - система контроля кассового оборудования

 

Изменения в версии iKassa v2

1. В версии iKassa v1 разрешен возврат только одной позиции из чека. Версия 2 позволяет добавить в чек возврата неограниченное количество позиций.

2. Добавлена возможность работы с маркировкой:

  • реализована передача данных СИ и УКЗ в iKassa;

  • также реализована передача корректного GTIN. Подробнее в главе Передача GTIN в iKassa v2.

3. Аннулирование СКНО доступно только для последнего документа и только если он является документом продажи. Подробнее в главе Аннулирование СКНО.

4. Блокирующие ошибки обрабатываются кассой и отображаются на экране в том виде, в каком они получены от iKassa (актуально для pos-, touch-касс, а также для КСО на базе SetRetail SCOv2).

5. КСО: при возникновении блокирующих ошибок во время работы покупателя на КСО также осуществляется световая и звуковая сигнализация, как описано в статье CSI-K, SetSCO (4:3) ◾ Вывод звуковых сигналов колонками при работе покупателя с КСО.

 

Передача GTIN в iKassa v2

При импорте товара из ERP выгружается признак к какой товарной группе маркировки относится товар:

  • Для маркированных СИ товаров на кассу загружен признак, что товар относится к маркированным.

  • Для товаров, маркированных УКЗ, на кассу загружен признак, что товар относится к маркированным УКЗ.

  • В карточке товара загружены ШК товара, в том числе с признаком GTIN (barcode-type="GTIN"). У товара могут отсутствовать ШК с признаком GTIN или быть более одного ШК с признаком GTIN.

При добавлении товара в чек продажи или чек возврата касса определяет GTIN товара. В фискальный регистратор iKassa v2 GTIN передается по следующему принципу:

  • Если товар добавлен сканированием ШК и для него загружен признак GTIN (<bar-code code="710000178431" barcode-type="GTIN">) в фискализатор передается именно этот GTIN. Если в карточке товара загружено несколько ШК с признаком GTIN - передается любой.

  • Если товар добавлен не сканированием ШК на товаре, а иным способом: через поиск, по артикулу, по коду и т.д.:

    • если для товара загружен хоть один ШК с признаком GTIN, передается этот GTIN.

    • если ШК с признаком GTIN несколько - передается первый из них.

  • Если товар с признаком маркировки СИ, то GTIN берется из СИ, загруженные ШК с признаком GTIN игнорируются.

  • Если нет ни одного ШК с признаком GTIN:

    • для немаркированных товаров передается ШК без признака GTIN,

    • для маркированных товаров - продажа запрещена.

При экспорте GTIN сохраняется в плагинное свойство gtin.

Проверка GTIN на соответствие формату

https://crystals.atlassian.net/browse/SRTG-68

https://crystals.atlassian.net/browse/CR-13082

10.4.15.0

Начиная с версии 10.4.15.0 при добавлении в чек ШК с типом GTIN проверяется на соответствие формату EAN8, EAN13 или EAN14:

  • Если первый проверяемый ШК с признаком GTIN не соответствует формату, тогда проверяется следующий загруженный в карточку товара ШК признаком GTIN, и в случае соответствия формату - передается в чековой позиции.

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

  • Если в карточку товара загружены все ШК с признаком GTIN и все не соответствуют формату - в чековой позиции сохраняется любой ШК, признак GTIN не передается (для немаркированных товаров), для маркированных - касса запрещает продажу.

 

Настройка

Сервер

Добавьте оборудование Программная касса iKassa v2 на сервере (Кассовый модуль → Кассовое оборудование → Фискальный регистратор/принтер чеков).

 

Касса

1. Скачайте файл скрипта ikassa_start.sh запуска службы tsrv → скопируйте его в папку /home/tc/storage/crystal-cash/scripts/.

2. Откройте на редактирование конфигурационный файл /home/tc/storage/crystal-cash/config/plugins/fiscalPrinter-rb_ikassav2-config.xml

3. Установите подключение программной части:

  • pin - пин-код для авторизации в СКО;

  • vendorId - идентификатор производителя принтера;

  • productId - идентификатор модели принтера.

4. На кассе в режиме конфигуратора выберите и задействуйте устройство Программная касса iKassa v2.

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

 

Аннулирование СКНО

В Республике Беларусь для аннулирования ошибочно пробитых документов используется функциональность "Аннулирование СКНО", т.е. чек, закрытый оплатой и подписанный СКО, можно отменить. Юридически документ аннулируется полностью, т.к. "аннулирование СКНО" означает, что чек продажи закрыт некорректно.

Пример: кассир закрывает чек оплатой наличными, а на самом деле покупатель хотел расплатиться банковской картой. В этом случае делается не "возврат", а "аннулирование СКНО".

В версии программного фискализатора iKassa v2 для этой функциональности установлено ограничение:

Аннулировать чек продажи можно только последний успешно закрытый. Если документ не является чеком продажи, то аннулирование СКНО невозможно.

Примеры сценариев работы

Клавиатурная касса

Сценарий демонстрации №1 

1. Кассир осуществляет продажу.

2. Кассир выбирает функцию «Аннулирование СКНО».

3. Вводит номер чека продажи для аннулирования (предыдущий чек).

4. Касса производит аннулирование документа.

Сценарий демонстрации №2 

1. Кассир осуществляет продажу.

2. Кассир выбирает функцию «Аннулирование СКНО».

3. Вводит номер чека продажи для аннулирования (номер чека в текущей смене, не последний).

4. Касса отображает на экране ошибку “Аннулирование возможно только последнего чека продажи”.

 

Возврат всего чека

https://crystals.atlassian.net/browse/SRTZ-3734

https://crystals.atlassian.net/browse/CR-12973

10.4.10.0

В версии SetRetail 10.4.10.0 добавлена возможность выполнять возврат всего чека на кассах SetTouch, если это не последний чек (т.к. по нему проходит аннулирование СКНО).

Сценарий демонстрации №1 Touch касса

1. Кассир осуществляет продажу.

2. Кассир переходит в режим Возврата по чеку.

3. Вводит номер чека продажи (номер чека в текущей смене, не последний).

4. На кассе доступны кнопки “Возврат всего чека” и “Возврат позиций”.

5. По кнопке “Возврат всего чека” происходит возврат чека.

Сценарий демонстрации №2 Touch касса 

1. Кассир осуществляет продажу.

2. Кассир переходит в режим Возврата по чеку.

3. Вводит номер чека продажи (последний чек).

4. На кассе доступны кнопки “Подтвердить чек” и “Возврат позиций”.

5. По кнопке “Подтвердить чек” происходит аннулирование СКНО документа.

 

Предоплата в виде товара

https://crystals.atlassian.net/browse/CR-12143

https://crystals.atlassian.net/browse/SRTZ-3781

10.4.11.0

Добавлена поддержка процесса работы с внесением аванса за товары, которые покупатель получит позднее. 

Товар импортируется со свойством <goods-feature>prepayment</goods-feature>, в соответствии с интеграционной документацией.

Пример работы

  1. На кассе поднимается заказ SetKit с товаром с признаком goods-feature = prepayment и стоимостью 50 руб.

  2. Кассир переходит к оплате.

  3. Покупатель оплачивает любым способом.

  4. При фискализации в iKassa передается признак товара в структуре Item → code: передается поле prepayment с ценой товара в копейках.

 

"items" : [ { "id" : "4333341000009", "price" : "50.00", "quantity" : "1.000", "discount" : "0.00", "code" : { "prepayment" : "5000" }, "name" : "Товар с свойством prepayment2", "tax_rate" : "tax20" }]

 

Печать дополнительной информации в чеке

https://crystals.atlassian.net/browse/SRTZ-3709

https://crystals.atlassian.net/browse/CR-12899

10.4.10.0

Возможность печатать дополнительную информацию на чеке: ШК, рекламу, информацию лояльности.

Вывод информации доступен для следующих чековых форм:

  • check-sale.xml (чек продажи);

  • check-return.xml (чек возврата).

Доступна печать подстановок только из следующих секций чековых форм:

  • в начале чека:

    • header;

  • в конце чека:

    • bonuses;

    • includedSlips;

    • footer.

 

Настройка

1. Для печати секции с бонусами и накоплениями внутри чека продажи на сервере в шаблоне кассы (Кассовый модуль → Шаблоны касс) перейдите на вкладку ПРОЦЕСС ТОРГОВЛИ → НАСТРОЙКИ → в разделе При регистрации чека печатать информацию установите флажок

О накоплениях → кликните
.

2. Для печати купонов внутри кассового чека установите настройку В составе чека в акции с результатом печати купона или рекламы в чеке.

3. Добавьте в шаблоны чековых форм check-sale.xml и check-return.xml пустую секцию <section id="includedSlips"></section>.

4. Добавьте 2 дополнительных пробела в конце строк в секциях includedSlips и footer. При печати эти секции обрамляются символом “*” в начале и конце строки, чтобы пробелы в начале и конце строки не обрезались на стороне tsrv.

<text align="right" filler="space" width="2" value=" " clip="true"/>

Ограничения

  • Доп. данные не будут печататься для Z/X отчетов, а также при аннулировании СКНО.

  • Размер QR-кода не редактируемый.

  • При печати купонов со штрихкодами существуют ограничения по длине штрихкода: Пирит - 14 символов, Xprinter - 12 символов. Если длина штрихкода купона превышает указанные значения - используйте вывод номера купона с помощью QR-кода.

Пример чека

Печать информации о подарочной карте

https://crystals.atlassian.net/browse/SRTZ-3835

https://crystals.atlassian.net/browse/CR-11528

10.4.12.0

Начиная с версии 10.4.12.0 доступна печать сведений по подарочной карте в чеке для информирования покупателей об операциях и остатке средств на подарочной карте.

Добавлена отправка секции presentCard, в которой можно печатать информацию как при оплате, так и при продаже ПК.

Доступны следующие подстановки для данных из оплат в секции presentCard:

  • payment_present_card_number - номер подарочной карты;

  • payment_present_card_balance - баланс карты (у элемента precision="2");

  • is_payment_present_card - условие, что в чеке есть оплата по Подарочной карте;

  • is_product_present_card - условие, что в чеке продан товар Подарочная карта.

Настройка

В форму чека продажи check-sale.xml добавьте следующую секцию:

Добавьте 2 дополнительных пробела в конце строк. При печати секция обрамляется символом “*” в начале и конце строки, чтобы пробелы в начале и конце строки не обрезались на стороне tsrv.

 

Пример секции presentCard
<section id="presentCard"> <list> <line font="normal"> <condition name="Оплата по ПК"> <operand key="equal"> <varLogical> <element value="is_payment_present_card" width="0" align="left"/> </varLogical> <varLogical> <boolean value="true"/> </varLogical> </operand> </condition> <text align="left" filler="space" width="4" value="ПК: " clip="true"/> <element align="right" filler="space" precision="2" width="40" value="payment_present_card_number"/> <text align="right" filler="space" width="2" value=" " clip="true"/> </line> <line font="normal"> <condition name="Оплата по ПК"> <operand key="equal"> <varLogical> <element value="is_payment_present_card" width="0" align="left"/> </varLogical> <varLogical> <boolean value="true"/> </varLogical> </operand> </condition> <text align="left" filler="space" width="8" value="Баланс: " clip="true"/> <element align="right" filler="space" precision="2" width="10" value="payment_present_card_balance"/> <text align="right" filler="space" width="2" value=" " clip="true"/> </line> <line font="normal"> <condition name="Товар ПК"> <operand key="equal"> <varLogical> <element value="is_product_present_card" width="0" align="left"/> </varLogical> <varLogical> <boolean value="true"/> </varLogical> </operand> </condition> <text align="right" filler="space" width="40" value="Продана Подарочная карта " clip="true"/> </line> </list> </section>

Пример печати

 

Печать информации о чеке продажи в чеке возврата

https://crystals.atlassian.net/browse/SRTZ-3754

https://crystals.atlassian.net/browse/CR-12165

10.4.12.0

Начиная с версии 10.4.12.0 добавлена возможность в чеке возврата печатать информацию по чеку продажи, на основании которого осуществляется возврат.

Доступны следующие подстановки:

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

  • supernumber - номер чека продажи;

  • supercash - номер кассы;

  • supershift - номер смены.

На копии чека возврата печать не поддерживается.

Настройка

В форму чека возврата check-return.xml в секцию footer добавьте следующий фрагмент кода:

<line font="normal"> <condition name="Возврат по чеку"> <operand key="equal"> <varLogical> <element value="has_super_check" width="0" align="left"/> </varLogical> <varLogical> <boolean value="true"/> </varLogical> </operand> </condition> <text value="Чек продажи:" width="12"/> <element align="left" filler="space" width="5" value="supernumber"/> <text value="Касса:" width="6"/> <element align="left" filler="space" width="5" value="supercash"/> <text value="Смена:" width="6"/> <element align="left" filler="space" width="5" value="supershift"/> </line>

 

Отключение печати заголовка из юридического лица в чеке

https://crystals.atlassian.net/browse/SRTG-16

https://crystals.atlassian.net/browse/CR-13085

10.4.13.0

Начиная с версии SetRetail 10.4.13.0 для iKassa v2 доступна возможность отключить печать заголовка из юридического лица ("шапку") в документах, для оптимизации печати чека за счет исключения дублирующей информации.

На сервере в шаблоне кассы (Кассовый модуль → Шаблоны касс) перейдите на вкладку ПРОЦЕСС ТОРГОВЛИ → НАСТРОЙКИ → в разделе Работа с чеком снимите флажок

Печать заголовка из юридического лица на документах → кликните
.

Примеры печати

Печать дополнительной информации в Z-отчете

https://crystals.atlassian.net/browse/SRTG-206

https://crystals.atlassian.net/browse/CR-14127

10.4.18.0

Начиная с версии SetRetail 10.4.18.0 реализована печать дополнительной информации в Z-отчете:

  • Номер кассы в магазине

  • Серийный номер кассы (токена)

  • Сумма скидок по смене

  • Нарастающий итог (по настройке)

Для печати нарастающего итога установите параметр <property key="printIncomeInReport" value="true"> в конфигурационном файле /home/tc/storage/crystal-cash/config/plugins/fiscalPrinter-rb_ikassav2-config.xml.

Примеры печати

Настройка печати накопительных итогов ВЫКЛЮЧЕНА

Настройка печати накопительных итогов ВКЛЮЧЕНА

X-отчет

Z-отчет

Печать количества операций по банковской карте и детализация по типам оплат в Z-отчете

https://crystals.atlassian.net/browse/SRTG-348

https://crystals.atlassian.net/browse/CR-14684

10.4.22.0

В версии 10.4.22.0 реализована печать дополнительной информации в Z-отчете:

  • печать количества операций по безналичным оплатам;

  • печать сумм оплат разных типов с группировкой по типам оплат (Наличные, Банковская карта, Внешний терминал).

Настройка

Настройка чековых форм

Для печати подстановок по типам оплат добавьте в шаблон отчёта следующие подстановки: (кроме них ничего в секциях быть не должно)

  1. Оплата наличными: секция <section id="report_cash" clean="false">

Для этой секции доступны следующие подстановки:

  • sumCashPurchase - сумма продаж наличными;

  • sumCashReturn - сумма возвратов наличными;

  • turnoverCash - оборот наличных в смене.

Пример использования подстановок:

<section id="report_cash" clean="false"> <line font="normal"> <text align="center" width="36" clip="true" value=" НАЛИЧНАЯ ПРОДАЖА " filler="dash"/> </line> <line font="normal"> <text width="11" value="Сумма продажи :" align ="left" clip="true"/> <element width="15" clip="true" align="right" precision="2" value="sumCashPurchase" /> <text width="4" value="руб" align = "right" prefix="space" clip="true"/> </line> <line font="normal"> <text width="11" value="Сумма возврата :" align ="left" clip="true"/> <element width="15" align="right" clip="true" precision="2" value="sumCashReturn" /> <text width="4" value="руб" align = "right" prefix="space" clip="true"/> </line> <line font="normal"> <text width="11" value="Оборот :" align ="left" clip="true"/> <element width="15" align="right" clip="true" precision="2" value="turnoverCash" /> <text width="4" value="руб" align = "right" prefix="space" clip="true"/> </line> </section>

  1. Безналичный расчёт, секция <section id="report_cashless" clean="false">

Для этой секции доступны следующие подстановки:

  • paymentType - название конкретного типа оплаты;

  • sumCashlessPurchase - сумма продаж с данным типом оплаты;

  • sumCashlessReturn - сумма возвратов с данным типом оплаты.

Пример использования подстановок:

<section id="report_cashless" clean="false"> <line font="normal"> <element align="center" width="36" clip="true" value="paymentType" filler="dash"/> </line> <line font="normal"> <text width="11" value="Сумма продажи :" align ="left" clip="true"/> <element width="15" clip="true" align="right" precision="2" value="sumCashlessPurchase" /> <text width="4" value="руб" align = "right" prefix="space" clip="true"/> </line> <line font="normal"> <text width="11" value="Сумма возврата :" align ="left" clip="true"/> <element width="15" align="right" clip="true" precision="2" value="sumCashlessReturn" /> <text width="4" value="руб" align = "right" prefix="space" clip="true"/> </line> </section>


Для печати количества оплат по безналичному расчёту в секцию <footer> добавьте следующую подстановку:

<line font="normal"> <text value="Безналичных оплат:" width="21" align="left"/> <element value="countcashlesspurchase" width="16" filler="space" clip="true" align="right"/> </line>
Примеры чековых форм

  • X-отчет -

  • Z-отчет -

В базе данных

Для печати оплат банковскими картами с детализацией по подтипам выполните скрипт в базе данных set → перезагрузите кассовый модуль.

Пример печати Z-отчета

image-20251217-042027.png

Печать банковского слипа внутри чека

Начиная с версии 10.4.20.0 реализована функциональность в iKassa v2 при оплате по банковской карте, печатать банковский слип внутри чека продажи, чтобы выдавать покупателю один чек и снизить затраты по чековой ленте.

  • Расположение тега slip всегда в конце чека, вне зависимости от шаблонов.

    • При количестве символов в слипе ≥ 44 переносится на следующую строку кассовой ленты.

  • Слип выделяется символами * по краям строки.

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

Для установки настройки перейдите в Кассовый модуль → Шаблоны касс → кликните требуемый шаблон → перейдите на вкладку ПРОЦЕСС ТОРГОВЛИ → НАСТРОЙКИ → Работа с чеком →

Печатать безналичные слипы внутри чека → кликните 
.

Печать штрихкода номера документа

https://crystals.atlassian.net/browse/SRTG-308

https://crystals.atlassian.net/browse/CR-14521

10.4.21.0

Начиная с версии 10.4.21.0 реализована печать штрихкода с номером документа для дальнейшего поиска чека. Штрихкод печатается на следующих типах документов:

  • чек продажи;

  • копия чека продажи;

  • отложенный чек

Для установки настройки перейдите в Кассовый модуль → Шаблоны касс → кликните требуемый шаблон → перейдите на вкладку ПРОЦЕСС ТОРГОВЛИ → НАСТРОЙКИ → Работа с чеком →

Печатать штрихкод номера чека → кликните 
.

В шаблоне чека в секции footer добавьте подстановку:

<line font="small"> <barcode type="code39" value="documentbarcode" height="40"/> </line>

 

Пример чековой формы: check-sale.xml 

Пример печати

Отправка чека покупателю в электронном виде на почту

https://crystals.atlassian.net/browse/SRTG-255

https://crystals.atlassian.net/browse/CR-14140

10.4.21.0

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

Настройка

В шаблоне кассы (Кассовый модуль → Шаблоны касс → требуемый шаблон) перейдите на вкладку ПРОЦЕСС ТОРГОВЛИ → НАСТРОЙКИ → в секции Работа с чеком установите следующие настройки:

  • image2021-3-24_11-29-30.png Использовать анкетные данные покупателя для отправки электронной версии чека;

  •  Не печатать бумажный чек →  выберите требуемый вариант → кликните .

Дополнительно можно установить настройку image2021-3-24_11-29-30.png Информировать кассира об отказе от печати чека.

При отсутствии адреса электронной почты чек печатается всегда, даже если выбран вариант настройки “всегда, даже если электронный чек не отправлен”

image-20251106-120613.png

У держателя карты должно быть включено разрешение на отправку данных по email.

chrome_TRc8V8asr0.png

Настройка межстрочного интервала для принтера чеков Пирит

https://crystals.atlassian.net/browse/SRTG-356

https://crystals.atlassian.net/browse/CR-14647

10.4.22.0

Периодически сбивается межстрочный интервал после перезапуска кассы или замены чековой ленты. В версии 10.4.22.0 реализована возможность настраивать межстрочный интервал для ПЧ Пирит в конфигурационном файле iKassa. При старте модуля на принтер отправляется команда для установки межстрочного интервала.

  1. В конфигурационный файл /home/tc/storage/crystal-cash/config/plugins/fiscalPrinter-rb_ikassav2-config.xml добавьте параметр <property key="lineSpacing" value="100" description="Размер межстрочного интервала"/>

  2. Укажите значение в атрибуте value по формуле:
    Требуемый интервал (в мм) × 16

    Например, для стандартного интервала ПЧ Пирит 4,25 мм:
    4,25 × 16 = 68 → value="68"

  3. Значение указывается только в десятичной системе счисления.

image-20251201-123019.png

Примеры печати:

image-20251201-133242.png

 

Подключение чекового принтера CSI Print X

Настройка устройства

1. Для корректной работы установите настройки для устройства через программу POS_Printer_Test_V3.2.zip.

2. Подключите принтер к любому персональному компьютеру через USB → запустите POS_Printer_Test.

3. Выберите 

USB → кликните 
.

4. Введите значение 17 → кликните 

 → кликните 
 → в секции Chinese mode установите 
NO → в секции Serial baudrate установите 115200 → кликните 
 и закройте окно → в секции InputBox Codepage установите 866 - Cyrillic(DOS) → кликните 
 → кликните 
 и закройте программу.

Подключение к кассе

1. На сервере Кассовый модуль → Кассовое оборудование → добавьте и установите флажок на модели фискального регистратора Программная касса iKassa v2.

2. Откройте на редактирование файл /home/tc/storage/crystal-cash/config/plugins/fiscalPrinter-rb_ikassav2-config.xml.

3. В параметр printerClass в значение value вставьте ru.crystals.pos.fiscalprinter.documentprinter.printx.DocumentPrinterPrintX → сохраните файл → выберите на кассе для подключения оборудования из списка Программная касса iKassa v2 и нужный порт → перезагрузите кассовый модуль.

Печать логотипа на принтере Print X

Настройка

1. Откройте на редактирование файл  /home/tc/storage/crystal-cash/config/plugins/fiscalPrinter-nonfiscalmode_axiohm-config.xml

2. Добавьте параметр <property key="useLogo" value="true"/> → сохраните файл.

3. Загрузите логотип в память принтера. Скачайте и запустите утилиту POS_Printer_Test_V3.2.zip.

4. Нажмите .