Начиная с версии 4.6.132 для отправки сообщений о бонусных транзакциях используется только очередь Artix-Queue.

Начиная с версии 4.6.149-5 осуществлен полноценный переход с интерфейса thrift на rest.

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

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

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

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

...

...

...

...

...

...

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

Модуль Артикс Бонус на кассе в режиме 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 при при добавлении карты в чек на экран выводится диалог ввода анкетных данных (номер телефона, дата рождения, пол м/ж).,

  Info
  Карты необходимо прогрузить на кассу.

  
  

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

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

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

...

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

...

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

...

возможным начислением баллов

...

Информационный чек с возможным начислением баллов является отличным инструментом мотивации клиента на получение карты системы лояльности при ее отсутствии. Шаблоном для печати информационного чека является файл /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 запрос на сервер отправляется при добавлении карты в чек.

Наименование	Тип данных	Возможные значения	Описание	Примечания
requestCardBalanceIfNecessary	логический	true false	Запрашивать баланс карты системы лояльности с сервера	По умолчанию false.

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

...

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

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

...

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

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

...

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

...

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

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

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

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

...

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

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

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

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

При использовании Qpid в случае недоступности очереди сообщение об операции с бонусами записывается в файл в формате json с названием <id сообщения>.<метод> в директорию /linuxcash/cash/data/qpid/artixbonus. Запись данных в файл позволит восстановить данные и скорректировать баланс карты, если по какой-либо причине сообщение о начислении/списании бонусных баллов не было отправлено.

{
  "additionalInfo": {
    "date_cash": 1489135331
	"cashCode": "888"
	"shopCode": "2"
	"shiftNumber": "222"
	"checkNumber": "111"
  },
  "amount": "950.40",
  "assetGroup": {
    "data_beg": 0,
    "data_end": 0,
    "groupId": "1",
    "weight": 0
  },
  "cardNumber": "123",
  "errortime": "2017-03-10_15:42:11:900",
  "hosts": [
    "199.169.6.16:7778" 
  ],
  "method": "add",
  "sessionId": "_cash_101_c66ed80f$222.17.9.0.154211897$9$17",
  "terminalId": "_cash_101_c66ed80f" 
}

В

В кассовом ПО 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 баллы списываются начиная с последней позиции и заканчивая первой. С каждой позиции списывается максимально возможное количество баллов.

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

...

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 реализована возможность передачи источника и причины транзакций на кассовый сервер.

...

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

Для обеспечения контроля бонусных транзакций в кассовом ПО 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

Логирование проверки доступности сервера происходит в файле /linuxcash/logs/current/taskmanager.log 

Настройка пути соединения с сервером Артикс Бонус

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

[ArtixBonus]
...
; Базовый путь REST API бонусного сервера
; По умолчанию /ACC/rest/v1/
;endPoint = /ACC/rest/v1/

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

...

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