Модуль Артикс Бонус предназначен для идентификации покупателей посредством считывания карт клиентов на кассе, выполнения операций по начислению и списанию бонусных баллов. Правила начисления и списания баллов задаются с помощью утилиты администрирования Yuki или в системе лояльности Artix Loyalty Management.

Модуль Артикс Бонус на кассе в режиме online взаимодействует с бонусным сервером, передавая данные для списания и начисления баллов. Если сервер недоступен, то списание накопленных баллов невозможно. 

Начисление бонусов может производиться в режиме offline. При отсутствии связи с сервером сообщения о начислении сохраняются в очередь и передаются на сервер после восстановления связи.

Отмена оплаты бонусами может производиться в режиме offline. При отсутствии связи с сервером сообщения об отмене оплаты сохраняются в очередь и передаются на сервер после восстановления связи. 

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

Конфигурирование модуля

Для подключения модуля Артикс Бонус необходимо в директории /linuxcash/cash/conf/plugins создать файл с расширением .xml, в котором необходимо указать идентификатор модуля, размещение плагина и прочие параметры. Например, /linuxcash/cash/conf/plugins/artix_bonus.xml.

Данные об идентификаторе терминала задаются на кассовом сервере и передаются на кассу. При обращении кассы к бонусному серверу наличие идентификатора терминала в первую очередь проверяется в файле artix_bonus.xml, а при отсутствии terminalId в данном файле его значение получается из параметра cash.code конфигурационного файла /linuxcash/cash/sync/properties/cash.ini. Настройки файла cash.ini получаются автоматически с кассового сервера, изменение данных вручную не рекомендуется, т.к. при следующем получении настроек с кассового сервера данные будут перезаписаны.

В случае невозможности получить идентификатор бонусные воздействия не могут быть применены, на экран кассира выводится сообщение "Ошибка бонусного сервера: терминал не найден".

<objects>
    <object id="ArtixBonus" plugin="/linuxcash/cash/plugins/libArtixBonus.so" >
	<property name="address">
		<map>
			<entry>
				<key>localhost</key>
				<value>8080</value>
			</entry>
		</map>
	</property>
	<property name="connectTimeout">
		<value>2000</value>
	</property>
	<property name="recvTimeout">
		<value>10000</value>
	</property>
	<property name="sendTimeout">
		<value>10000</value>
	</property>
	<property name="terminalId">
		<value>term123</value>
	</property>
	<property name="roundPrecision">
		<value>0.1</value>
	</property>
    <property name="roundModeForEarn">
        <value>roundToDown</value>
    </property>
	<property name="roundPrecisionForSpend">
		<value>0.1</value>
	</property>
	<property name="proportionalEarnBonus">
		<value>false</value>
	</property>
    <property name="useDiscOnChange">
        <value>false</value>
    </property>
    <property name="cancelBonusOnlyOnPosition">
		<value>false</value>
	</property>
    <property name="inputClientInfo">
        <value>false</value>
    </property>
    <property name="calculateDummyPoints">
        <value>false</value>
    </property>
    <property name="dummyCardNumber">
        <value></value>
    </property>
	<property name="proportionalSpendBonusOnPosition">
        <value>false</value>
    </property>
    <property name="cancelEarnBonusWithID">
        <value>false</value>
    </property>
    <property name="printDetailedBonusInfo">
        <value>false</value>
    </property>
    <property name="user">
        <value></value>
    </property>
    <property name="password">
        <value></value>
    </property>
 	</object>
</objects>

Ввод анкетных данных

Для сбора информации о клиентах торговой сети реализована функция ввода анкетных данных, задаваемая параметром inputClientInfo при конфигурировании модуля Артикс Бонус:

• при значении true при добавлении карты в чек на экран выводится диалог ввода анкетных данных (номер телефона, дата рождения, пол м/ж),

  Карты необходимо прогрузить на кассу.
• при значении false сбор информации о владельцах карты системы лояльности не осуществляется.

Функция сбора данных предназначена только для работы с картами системы лояльности, имеющими статус "Анонимная".

При вводе данных осуществляется валидация полей. Если введены некорректные данные, то они будут подсвечены красным цветом, и программа не позволит перейти к оплате. Необходимо исправить введенные данные или отменить ввод данных. 

Ввод данных не обязателен, кассир может закрыть окно, нажав ESC. Для карт с признаком "Отображать информацию по карте" после заполнения анкетных данных информация по карте (ФИО, баланс, дата последнего обновления) показывается автоматически. 

Выгрузка данных осуществляется в формате Штрих отдельной транзакцией при условии, что хотя бы одно из полей заполнено. Запрос данных будет производиться до тех пор, пока карта имеет статус "Анонимная". 

Печать информационного чека с рекламой и возможным начислением баллов

Информационный чек с возможным начислением баллов является отличным инструментом мотивации клиента на получение карты системы лояльности при ее отсутствии. Шаблоном для печати информационного чека является файл /linuxcash/cash/reports/dummypoints.xml.

Механизм расчета возможного начисления баллов основывается на данных номинальной карты. Для настройки печати информационного чека необходимо:

1. Создать группу карт с типом Артикс Бонус.
2. Добавить карту с номером, соответствующим маске группы карт (см. п.1).
3. В файле /linuxcash/cash/conf/plugins/artix_bonus.xml:
   1. Для параметра calculateDummyPoints установить значение true,
   2. В параметре dummyCardNumber указать номер номинальной карты (см. п.2),
4. Настроить бонусную акцию.

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

Продажа

Для начисления и списания баллов с карты Артикс Бонус необходимо добавить карту в чек.

Получение баланса карты с сервера системы лояльности

При использовании карты системы лояльности в чеке необходимо направлять запрос на сервер системы лояльности для получения сведений о количестве бонусных баллов. Момент отправки запроса определяется параметром requestCardBalanceIfNecessary в конфигурационном файле /linuxcash/cash/conf/ncash.ini в секции [Misc]:

• при значении true баланс карты запрашивается при получении информации о карте или оплате чека бонусами,
• при значении false запрос на сервер отправляется при добавлении карты в чек.

[Misc]
...
;Запрашивать баланс карты системы лояльности с сервера
;true - только при необходимости (запрос информации о карте, оплата бонусами), false - при добавлении карты в чек
requestCardBalanceIfNecessary = false
...

Начисление баллов

Расчет суммы баллов к начислению выполняется на кассе при переходе в режим оплаты. Сумма баллов к начислению пересчитывается после списания баллов. Правила пересчета бонусов к начислению задаются параметром proportionalEarnBonus при конфигурировании модуля Артикс Бонус:

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

При использовании в чеке карт нескольких систем лояльности количество баллов к начислению зависит от порядка списания баллов. Подробнее можно прочитать в разделе "Использование карты в чеке".

Начисление баллов на набор

Модуль Артикс Бонус позволяет создавать различные виды акций, в том числе и начисление бонусных баллов на набор. Настройка правил начисления и списания баллов задается через утилиту администрирования Yuki. 

Для того чтобы начисления были применены необходимо:

• наличие активной акции с прописанными правилами начисления и списания,
• наличие карты системы лояльности в чеке.

Если в одном чеке применяются операции начисления и списания баллов, то после списания баллов происходит пересчет начисленных баллов.

Режим округления для начисления баллов

Правило округления суммы баллов к начислению задается параметром roundModeForEarn в файле конфигурации /linuxcash/cash/conf/plugins/artix_bonus.xml:

При значении параметра:

• roundToUp – округление происходит до ближайшего большего значения,
• roundMathematical – округление происходит математически без потери,
• roundMathematicalWithLoss – округление происходит математически с потерей,
• roundToDown – округление происходит до ближайшего меньшего.

Точность суммы для начисления баллов задается параметром roundPrecision. По умолчанию округление происходит до 1 знака после запятой.

Списание баллов

Для списания баллов необходимо в утилите администрирования Yuki на клавишу настроить действие "Оплата бонусами" с командой COMMAND_PAYWITHBONUS. При нажатии клавиши "Оплата бонусами" вызывается диалог оплаты баллами, в котором в поле ввода автоматически подставляется максимальное количество баллов для списания.

В кассовом ПО Artix реализована возможность автоматического вызова диалога оплаты баллами при наличии в чеке карты Артикc Бонус и переходе в подытог. Автоматический вызов диалога оплаты баллами регулируется параметром spendBonusDialog в секции [ArtixBonus] конфигурационного файла /linuxcash/cash/conf/ncash.ini.d/artixbonus.ini:

• при значении true при переходе в подытог, если в чек добавлена карта Артикc Бонус, на экране автоматически отображается диалог оплаты баллами,
• при значении false диалог оплаты баллами отображается только по нажатию клавиши "Оплата бонусами".

[ArtixBonus]
...
; Оплата бонусами при наличии карты в чеке и переходе в подытог
; По умолчанию false
;spendBonusDialog = false

Для резервирования баллов с целью последующего списания модуль Артикс Бонус обращается к бонусному серверу.

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

После закрытия чека на бонусный сервер через очередь отправляются сообщения:

• о начислении бонусов (метод add),
• об отмене начисления бонусов без указания идентификатора исходной операции (метод sub),
• о списании бонусов (метод sub),
• об отмене начисления бонусов с указанием идентификатора исходной операции (метод revertEarnBySessionId),
• о подтверждении операции (метод commit),
• об отмене списания бонусов (метод back).

В кассовом ПО Artix реализована возможность применения скидки на мелочь, при оплате бонусными баллами, задается параметром useDiscOnChange в файле конфигурации /linuxcash/cash/conf/plugins/artix_bonus.xml:

• значение параметра true при оплате чека бонусными баллами скидка на мелочь остается в чеке,
• значение параметра false при оплате чека бонусными баллами скидка на мелочь удаляется из чека.

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

Пропорциональное списание баллов на позицию

Пропорциональное списание баллов на позицию задается параметром proportionalSpendBonusOnPosition в файле конфигурации /linuxcash/cash/conf/plugins/artix_bonus.xml:

• при значении true баллы при списании будут пропорционально распределены на позиции,
• при значении false баллы списываются начиная с последней позиции и заканчивая первой. С каждой позиции списывается максимально возможное количество баллов.

Срок действия бонусов

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

Печать информации о бонусах, которые истекают в ближайшее время

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

1. Включить настройку printDetailedBonusInfo для получения информации о бонусах.
2. Настроить шаблоны документов sale.xml и cardBalance.xml, используя параметры:
   • cardRecord.nearExpirationBonus – сумма бонусов, которые истекают в ближайшее время,
   • cardRecord.nearExpirationBonusDate – дата истечения бонусов.

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

Возврат

При возврате товара по чеку продажи осуществляется отмена операций начисления и списания баллов.

Отмена начисления

При начислении в БД Documents таблицу BonusItem поле transactionId записывается идентификатор транзакции, который может быть использован при отмене операции. Правила отмены начисления определяются параметром cancelEarnBonusWithID задаваемым в конфигурационном файле /linuxcash/cash/conf/plugins/artix_bonus.xml:

• при значении true в запросе отмены начисления указывается идентификатор исходной операции, списание баллов будет произведено из той группы бонусов, в которую они были начислены,

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

При проведении отмены начисления в transactionId записывается идентификатор операции отмены (независимо от значения параметра cancelEarnBonusWithID).

Отмена списания

При списании в БД Documents таблицу Discitem поле sessionid записывается идентификатор транзакции, который используется при отмене операции.

При возврате по чеку продажи может быть запрещена отмена списания бонусных баллов. Данное поведение задается опцией карты "Запрет возврата бонусных баллов" (БД Dictionaries таблица Card поле options), может быть загружено в справочниках в формате AIF.

Списание баллов на позицию при возврате товара

Функция списания баллов на позицию при возврате товара позволяет отменять при возврате не все бонусы на товар, а только бонусы на позицию (бонусы на чек сохраняются).

Списание баллов по заданному правилу осуществляется только в тех чеках, которые при возврате были изменены (например, вернули только часть товара). Правило списания задается опционально при помощи параметра cancelBonusOnlyOnPosition в файле конфигурации /linuxcash/cash/conf/plugins/artix_bonus.xml:

• при значении true при возврате товара отменяются только бонусы на позиции на возвращаемый товар,
• при значении false при возврате товара отменяются все бонусы (на чек и на позиции) на возвращаемый товар.

Формирование идентификатора транзакции

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

Идентификационный номер формируется следующим образом:

Контроль бонусных транзакций

Для обеспечения контроля бонусных транзакций в кассовом ПО Artix реализована возможность передачи источника и причины транзакций на кассовый сервер.

Источник и причина транзакций задаются настройками sourceTransaction и reasonTransaction в секции [ArtixBonus] конфигурационного файла /linuxcash/cash/conf/ncash.ini.d/artixbonus.ini.

Для указания значений настроек могут быть использованы только свойства объекта document.

[ArtixBonus]
; Источник транзакции
;sourceTransaction = "%(document.shopCode[04d])%(document.cashCode[02d])%(document.shift[04d])%(document.num[07d])%(document.dateTimeBeg[hhmmss])"
; Причина транзакции
;reasonTransaction = "cash_%(document.shopCode[04d])_%(document.cashCode[02d])"

Настройками кассового ПО Artix может быть предусмотрен запрос ПИН-кода карты клиента при оплате чека бонусными баллами. Запрос ПИН-кода определяется параметром usePincode в секции [ArtixBonus] конфигурационного файла /linuxcash/cash/conf/ncash.ini.d/artixbonus.ini:

• при значении true во время оплаты чека бонусными баллами будет запрошен ПИН-код карты клиента,
• при значении false оплата чека бонусными баллами осуществляется без запроса ПИН-кода.

В целях обеспечения безопасности ПИН-код скрыт в поле ввода.

В кассовом ПО Artix реализована возможность запрещать ввод пин-кода вручную при оплате чека бонусными баллами, регулируется параметром forbidPincodeManualInput в секции [ArtixBonus] конфигурационного файла /linuxcash/cash/conf/ncash.ini.d/artixbonus.ini:

• при значении true на экран будет выведено сообщение "Сканируйте ПИН-код для оплаты бонусными баллами", ввод пин-кода вручную запрещен,
• при значении false на экран будет выведен диалог "Введите ПИН-код для оплаты бонусными баллами", доступен ввод пин-кода вручную.

[ArtixBonus]
...
; Вводить ПИН-код при оплате бонусными баллами
; По умолчанию false
;usePincode = false

; Запретить ввод пин-кода вручную
; По умолчанию false
;forbidPincodeManualInput = false

В кассовом ПО Artix добавлена возможность задавать интервал проверки доступности сервера системы лояльности Артикс Бонус, регулируется настройкой pingInterval в секции [ArtixBonus] конфигурационного файла /linuxcash/cash/conf/ncash.ini.d/artixbonus.ini.

[ArtixBonus]
... 
; Интервал проверки доступности сервера Артикс.Бонус в секундах
; По умолчанию выключено (-1)
;pingInterval = -1

Операции выполняемые в offline режиме

В offline режиме могут выполняться операции:

• начисление баллов, 
• отмена начисленных баллов, 
• возврат списанных баллов.

Информация о перечисленных операциях передается на бонусный сервер через очередь Artix-Queue.