> For the complete documentation index, see [llms.txt](https://docs.expirenza.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.expirenza.com/setup/pos/rkeeper.md).

# r\_keeper

## 1. Підключення плагіна Expirenza до r\_keeper

> **Ліцензія**

Для роботи Expirenza використовується інтеграція з Касовим сервером за допомогою XML-інтерфейсу. Методи API касового сервера дозволяють “читати” довідники, створювати та оплачувати замовлення.

Для оплати з автоматичним закриттям рахунку використовується метод PayOrder, який доступний з додатковою ліцензією “R-Keeper модуль XML-интерфейс для Приложения”.<br>

{% hint style="info" %}
Використання XML-інтерфейсу за підпискою може бути недоступно в деяких версіях r\_keeper: [Documentation](https://docs.rkeeper.ru/rk7/latest/ru/ispol-zovanie-xml-interfejsa-po-podpiske-43455727.html).
{% endhint %}

> **Установка плагіну**

Плагін Expirenza необхідно встановити на один комп'ютер з Касовим сервером r\_keeper.

1. Завантажте архів з плагіном за посиланням: [r\_keeperPlugin](https://plugins.expirenza.com/s2p-rkeeper/install.zip).
2. Розпакуйте вміст архіву в теку `C:\monoPayment`.
3. Правою кнопкою миші натисніть на файл install.bat і запустіть його, використовуючи пункт контекстного меню Windows “Запустити від імені Адміністратора”.
4. Переконайтесь, що у Планувальнику завдань Windows з‘явились такі завдання:

* `expz-rkeeper-daily-%HASH%` (для своєчасного оновлення плагіна)
* `expz-rkeeper-logon-%HASH%` (для автоматичного запуску плагіна у разі перезавантаження касового сервера)

{% hint style="info" %}
Для перезапуску плагіна необхідно використовувати файл "`run_on_system_start_client.bat`".
{% endhint %}

> **Конфігураційний файл properties.txt**

1. Скопіюйте в теку `C:\monoPayment` конфігураційний файл properties.txt, який раніше отримали від менеджера Expirenza
2. Згенеруйте параметр "`usr`". Це можна зробити самостійно, згідно [з цією інструкцією](https://docs.rkeeper.ru/rk7/latest/ru/ispol-zovanie-xml-interfejsa-po-podpiske-43455727.html), або скористатись спеціальним сервісом:[ ](https://admin.expirenza.com/technical/rkeeper/usr)<https://admin.expirenza.com/technical/rkeeper/usr>
3. Вставте отримане значення "`usr`" в параметр "`SELLER_TOKEN`" в конфігураційному файлі `properties.txt`.

***

## 2. Робота з API.

> **Увімкніть роботу з API**

У менеджерській станції r\_keeper необхідно включити використання API:

1. Перейдіть в розділ "Сервіс" → "Станції та Пристрої".
2. Виберіть ваш Касовий сервер зі списку.
3. У блоці "HTTP Обмеження" встановіть такі значення: `"XML інтерфейс" = HTTP Access`;
4. У блоці "HTTP Server" встановіть такі значення: “`HTTP Data Port`” = `8099`;
5. Скопіюйте значення з "`HTTP Data Port`" в параметр "`RKEEPER_PORT`" в конфігураційному файлі `properties.txt`.

> **Створіть користувача для роботи з API**

1. Перейдіть в розділ "Персонал" → "Працівники".
2. Створіть нову роль і відкрийте вкладку "Властивості".
3. У блоці "Головне" встановіть такі значення:

* "Назва" = expirenza.
* "Статус" = Активний.

&#x20;4\.  У блоці "Обмеження" встановіть такі значення:

* "Привілей на об'єкт" = `HTTP Access`;

&#x20;5\.  У блоці "Касові обмеження" → "Операції" ввімкніть такі пункти:

<details>

<summary>5.Пункти</summary>

* Оплати → Додати передоплату.
* Оплати → Закрити чек.
* Оплати → Скасувати оплати чека.
* Довідники → Блюдо.
* Довідники → Оплати.

</details>

&#x20;6\.  У блоці "Менеджерські обмеження" → "Привілеї на об'єкти" ввімкніть такі пункти:

* `HTTP Access`

&#x20;7\.  У блоці "Менеджерські обмеження" → "Привілеї" ввімкніть такі пункти:

<details>

<summary>7.Пункти</summary>

* Меню → Меню.
* Меню → Категорії страв.
* Гроші → Валюти.
* Гроші → Причини внесення / видачі грошей.
* Гроші → Знижки і націнки.
* Персонал → Працівники.
* Персонал → Групи працівників.
* Установки → Столи.
* Установки → Атрибути столів.

</details>

&#x20;8\.  Збережіть створену роль.

&#x20;9\.  Перейдіть на вкладку "Працівники" нової ролі "expirenza".

&#x20;10\.  Створіть нового користувача з роллю "expirenza".

&#x20;11\.  Для нового користувача, в блоці "Головне" встановіть такі значення:

* "Назва" = `ExpirenzaXML`;
* "Статус" = Активний;

&#x20;12\. Вставте значення з поля “Назва” у “`XMLAPI_USER`” у конфігураційному файлі properties.txt;

&#x20;13\. Для нового користувача, в блоці "Основні" → "Обліковий запис" створіть пароль.&#x20;

* Поле "Код карти" залиште порожнім;

&#x20;14\. Збережіть створеного користувача

&#x20;15\. Вставте пароль в параметр "`XMLAPI_PASS`" в конфігураційному файлі `properties.txt`.

### Замовлення за столом

Це налаштування є опціональним,у випадку якщо ви хочете підключити функцію  "Замовлення за столом "

Для створення замовлення за столом, необхідно додати нову опцію у файл `properties.txt`.

Опція яку треба додати: `EXPIRENZA_TABLE_ORDER_CODE`

Опис опції: Код Типу замовлення, що буде створено.

Після додавання опції  у файл, треба налаштувати тип замовлення:\
`Станція менеджера → Замовлення → Типи замовленнь.`

Тип замовлення має бути доступний на касі, що використовує плагін. \
Тип замовлення має мати назву "Expirenza".

***

## 3. Оплата і закриття рахунків

> **Додайте "касира"**

1. Перейдіть в розділ "Персонал" → "Працівники".
2. Виберіть роль "Касири".
3. Створіть нового користувача з роллю "Касири".
4. Для нового касира, в блоці "Головне" встановіть такі значення:

* Назва" = Expirenza
* "Статус" = Активний

&#x20;5\.  Скопіюйте значення з поля "Головне" → "Код" і вставте в параметр "`CASHIER_CODE`" в конфігураційному файлі `properties.txt`.

> **Додайте "валюту"**

1. Перейдіть в розділ "Гроші" → "Валюта".
2. У списку виберіть тип "Кредитні карти".
3. Створіть нову валюту.
4. У блоці "Головне" встановіть такі значення:

* "Назва" = Expirenza.
* "Статус" = Активний

5. У блоці "Основне" встановіть такі значення:

* "Враховувати в звітах" = 31 Так, крім заліку передоплат;

6. У блоці "Обмеження" ввімкніть такі пункти:

* Немає в решті;
* Без решти;
* Повернення страв;

7. Скопіюйте значення з поля "Головне" → "Код" і вставте в параметр "`PAY_TYPE_CODE`" в конфігураційному файлі `properties.txt`.

> **Вкажіть ресторан для підключення**

1\. Відкрийте менеджерську станцію;

2\. Зайдіть у меню “Сервіс” → “Станції та пристрої”;

3\. Виберіть ресторан, що підключається;

4\. Перейдіть до розділу “Властивості” вибраного ресторану;

<figure><img src="/files/7M69N83DXqsTlkAG7u0b" alt=""><figcaption><p>r_keeper</p></figcaption></figure>

5. Скопіюйте значення “Код” та внесіть у параметр `RESTAURANT_CODE` у конфігураційному файлі `properties.txt`

> **Налаштуйте друк чека**

1\. Перейдіть в розділ "Сервіс" → "Станції та пристрої";

2\. Зі списку виберіть касову станцію на якій має виконуватися друк чека;

3\. Перейдіть до розділу “Властивості” обраної касової станції;

<figure><img src="/files/Hcn8kKH5szIBzay7z3BF" alt=""><figcaption><p>r_keeper</p></figcaption></figure>

4\. Скопіюйте значення з поля "Головне" → "Код" та внесіть у параметр "`CASHES_CODE`" в конфігураційному файлі `properties.txt`.

### 3.1 Режими закриття рахунків

Плагін для  r\_keeper підтримує  2 режими роботи:

1. Закриває рахунки на тип оплати вказаний у файлі properties.txt - PAY\_TYPE\_CODE
2. Автоматично обирає валюти, на які необхідно закривати рахунок. Залежить від того, до якої валюти прив'язана класифікація страв. Для роботи в цьому режимі потрібно додати у файлі -`properties.txt` - `PAY_TYPE_STRATEGY=FROM_POS`\
   У `PAY_TYPE_CODE` у такому разі потрібно надати через `" , "` перелік валют, на які налаштована оплата Expirenza.\
   Приклад:  `PAY_TYPE_CODE=98,99,100`

{% hint style="warning" %}
Важливо!\
Надіслані валюти повинні покривати всі категорії класифікації страв. Якщо в рахунку буде страва з категорії, яка не прив'язана до жодної з валют, система не зможе визначити, якою валютою потрібно закрити рахунок.
{% endhint %}

Приклади:\
&#x20;1\. **Як НЕ правильно**&#x20;

PAY\_TYPE\_CODE=98,99\
Валюти прив'язані до класифікації:

\
Закриває категорії - Expirenza ТОВ - код 98

* Пиво
* Ром
* Горілка

Закриває категорії -Expirenza ФОП - код 99

* Пиво
* Тістечка
* Риба

НЕ правильно - так як категорія Горілка, прив'язане для обох валют, система не зможе зрозуміти яку саме з валют потрібно закрити страву з категорії Пиво.

2. **Як допустимо**

PAY\_TYPE\_CODE=98,99\
Валюти прив'язані до класифікації:

Закриває категорії - Expirenza ТОВ - код 98

* Пиво
* Ром
* Горілка

Закриває категорії -  Expirenza ФОП - код 99

* Тістечка
* Риба

Закриває категорії - Гривня ФОП - код 100

* Пиво

Допустимо - так як “Пиво” НЕ дублюється в рамках переданих валют (98 и 99). А валюту з кодом 100 - система не розглядає.

***

## 4. Розрахунки

Expirenza автоматично розподіляє кошти від продажу на відповідні банківські рахунки вашого закладу. Для цього використовується класифікація страв.&#x20;

Після завершення етапу технічного підключення ви зможете налаштувати розподіл коштів в розділі "Банківські рахунки" електронного кабінету закладу.

> **Налаштуйте класифікацію страв та напоїв**

1\. Перейдіть в розділ "Меню" → "Класифікації страв".

2\. Виберіть зі списку класифікацію, згідно з якою розподілятимуться кошти від продажів у закладі, що підключається. **Як правило**, партнери обирають класифікацію "Відділ ФР".

<figure><img src="/files/nkb7clw9OfSd5gSfzo2M" alt=""><figcaption><p>r_keeper</p></figcaption></figure>

3\. Перейдіть до розділу “Властивості” вибраної класифікації страв;

4\. Скопіюйте значення “Код” та внесіть у параметр `CLASSIFIER_CODE`у конфігураційному файлі `properties.txt` .

> **Перевірте класифікацію страв та напоїв**

1\. Перейдіть в розділ "Меню" → "Меню";

2\. Переконайтеся, що для кожної страви у блоці “Класифікації встановлено коректне значення "Відділ ФР".

***

## 5. Персонал

> **Налаштування персоналу**

Expirenza автоматично завантажує список персоналу з вашої системи. Це дозволяє нам:

* Відправляти персоналу ресторану повідомлення про успішні оплати через Telegram-бот;
* Перераховувати офіціантам їхні чайові на особисту картку.

Система завантажує дані тільки тих співробітників, у яких заповнене поле "Моб. телефон", тому **першим кроком необхідно додати цей параметр**:

1. Перейдіть в розділ "Налаштування" → "Налаштування" → "Розширені властивості" і виберіть пункт "Властивості для довідників".
2. На вкладці "Типи розширених властивостей" додайте "Новий тип розширених властивостей" з такими параметрами:

* "Системне ім'я" = mobilePhone
* "Назва" = Моб. телефон
* "Коментар" = Моб. телефон

3. Натисніть на “три крапки” біля параметра "Список Типів", виберіть пункт "Додати елемент";
4. За допомогою меню вставки виберіть пункт "Додати елемент";
5. Виберіть тип об'єкта "Працівник";
6. В меню "Персонал" виберіть "Працівники" → "Розширені властивості". Для співробітників з посадами "касир", "офіціант", "бармен" (і / або іншими посадами, за якими співробітники в вашому закладі беруть участь в проведенні оплати і закриття рахунків) заповніть поле "Моб. телефон "в форматі" +380673435656 ".

***

## 7. Налаштування передачі додаткових даних для фіскального чеку <a href="#acquiring" id="acquiring"></a>

{% hint style="warning" %}
Даний крок є опціональним, технічно без нього оплати все також будуть працювати, але цей крок все одно **важливо виконати** при налаштуванні плагіну.&#x20;

Тому як чек збагачується новими даними, котрих [вимагає закон](https://zakon.rada.gov.ua/laws/show/z0220-16#Text).&#x20;

Аби уникнути штрафів за "незбагачений" чек - важливо виконати це налаштування.
{% endhint %}

Перед початком налаштування впевніться що версія вашого плагіну -> 60 або вище.

1. У файлі налаштувань плагіну Expirenza необхідно додати строку:

```json
EXPZ_PLUGIN_PORT=1234
```

Номер порту має бути тим який надалі буде використовуватись для з'єднання з касовою станцією r\_keeper.

{% hint style="info" %}
Порт має бути вільним, або плагін не запуститься.

Якщо порт не вказаний, плагін запускається на випадковому вільному порті.
{% endhint %}

2. На касову станцію с фіскальними реєстраторами додаємо драйвер у розділі "Пристрої" :
   1. `http auth terminal driver (xml) ver 2`
   2. У рядку підключення драйверу вказуємо наступний шлях:

      1. `http://127.0.0.1:1234/api/terminal/`

{% hint style="info" %}
Шлях підключення драйверу обов'язково має закінчуватись на -`"/"`

`:1234 -`порт що раніше був вказаний у файлі налаштувань плагіну Expirenza.

`127.0.0.1` - якщо каса та плагін знаходяться на одному пристрої, то адреса вказується `127.0.0.1`

У іншому випадку - адреса пристрою на якому запущено плагін.
{% endhint %}

<figure><img src="/files/QWUd3QUATKHBgRx7U0wL" alt=""><figcaption></figcaption></figure>

3. Вкладка " Принтер "
   1. Створюємо новий принтер с найменуванням "`AuthShakeToPay`".
   2. У властивостях принтера треба обрати модуль `http auth terminal driver (xml) ver 2` , проставити галочку "журналювати".

{% hint style="info" %}
Логи драйверу записуються у корінь папки каси. Наприклад: `..\Rk7Cash\cvhttpv2_0.LOG`
{% endhint %}

4. &#x20;властивостях станції для термінала авторизації призначаємо створений нами принтер.
5. У довіднику "валюти" ставимо галочку на валюті Expirenza -> "використовувати термінал авторизації"
6. У довіднику "документи та макети" відкриваємо макет Чек (який використовується в схемах друку) і якщо він порожній, то додаємо `bnd` з джерелом даних "оплати", усередині бенду створюємо `memo` і додаємо в memo - "`[СліпАвторизації]`" перед ним додаємо `<Footer>`, щоб дані друкувалися внизу чека

<figure><img src="/files/LA5wzBwJcpykJOuFEUaJ" alt=""><figcaption></figcaption></figure>

7. У довіднику "документи та макети" для документів результат авторизації у властивостях включаємо "журналування".
8. У довіднику "схеми друку" обираємо схему друку, що використовується, і на поданні макета "результат авторизації" ставимо "не друкувати".

### 7.1 Варіант налаштувань фіскального чеку  для fpUAcheckOnline

1. У файлі налаштувань плагіну Expirenza необхідно додати строку:

```json
EXPZ_PLUGIN_PORT=1234
```

Номер порту має бути тим який надалі буде використовуватись для з'єднання з касовою станцією r\_keeper.

{% hint style="info" %}
Порт має бути вільним, або плагін не запуститься.

Якщо порт не вказаний, плагін запускається на випадковому вільному порті.
{% endhint %}

2. На касову станцію с фіскальними реєстраторами додаємо драйвер у розділі "Пристрої" :

   1. `http auth terminal driver (xml) ver 2`
   2. У рядку підключення драйверу вказуємо наступний шлях:

      1. `http://127.0.0.1:1234/api/v2/terminal`

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>Шлях підключення драйверу обов'язково має закінчуватись на -<code>"/"</code></p><p><code>:1234 -</code>порт що раніше був вказаний у файлі налаштувань плагіну Expirenza.</p><p><code>127.0.0.1</code> - якщо каса та плагін знаходяться на одному пристрої, то адреса вказується <code>127.0.0.1</code></p><p>У іншому випадку - адреса пристрою на якому запущено плагін.</p></div>

<figure><img src="/files/VgCt3AAr9rZ5X9LECynU" alt=""><figcaption></figcaption></figure>

3. Вкладка " Принтер "
   1. Створюємо новий принтер с найменуванням "`AuthShakeToPay`".
   2. У властивостях принтера треба обрати модуль `http auth terminal driver (xml) ver 2` , проставити галочку "журналювати".

{% hint style="info" %}
Логи драйверу записуються у корінь папки каси. Наприклад: `..\Rk7Cash\cvhttpv2_0.LOG`
{% endhint %}

4. &#x20;властивостях станції для термінала авторизації призначаємо створений нами принтер.
5. У довіднику "валюти" ставимо галочку на валюті Expirenza -> "використовувати термінал авторизації"

<details>

<summary>F.A.Q</summary>

<mark style="color:orange;">Q.</mark> Отримуємо помилку при оплаті:

```
<Errors>
    <Error RK7ErrorN="3484" Component="Authorization terminal">
    Ошибка авторизации: Интерфейс &quot;&quot; 
    не загружен или не поддерживает платежные транзакции.</Error>
 </Errors>

```

<mark style="color:green;">A.</mark> Якщо окрім "валюти" Expirenza є інші валюти пов'язані з банківськими терміналами:&#x20;

Потрібно додати у схемі печаті окреме представлення документа "Авторизація термінала" з призначенням принтера для печаті - "Для термінала авторизації AuthExpirenza"

***

<mark style="color:orange;">Q.</mark> Отримуємо помилку при оплаті:

{% code overflow="wrap" %}

```
<Error RK7ErrorN="2018" Component="Printer">
Помилка при блокуванні принтера &quot;
AuthShakeToPay(6)&quot; 
на &quot;01_Каса 1654&quot;:&quot;
ZUZU3: Printer (cvhttpv2.dll, 1) XmlInit error (hard = 0, soft = 1): 
HTTPpost Exception: Socket Error # 10061&#13;&#10;
Connection refused..&quot;.
</Error>

```

{% endcode %}

![](/files/AehMQpusK1sBg7yw24fQ)

<mark style="color:green;">A.</mark> Вірогідно вказана неправильна адреса плагіну відносно каси. Перевірте пункт 7.2 про налаштування шляху драйвера.

</details>

## 8. Налаштування видалення створеного замовлення за столом

З версії 249 beta, 250 stable додалась можливість видаляти створене замовлення за столом.

Попередьно необхідно :&#x20;

Cтворити причину видалення замовлення або вказати існуючу.\
Користувачу Expirenza видати права на видалення чеку - 'Видалити закритий чек' в пос системі

1. В станції менеджера перейти в розділ Замовлення -> причини видалення.
2. Створити  або обрати існуючу причину видалення, яка буде доступна для використання з плагіном Expirenza.
3. Значення з поля "Код" потрібно додати в файл properties.txt. Наприклад: \
   `DELETE_ORDER_REASON=5`

При видаленні замовлення в телеграм боті або адмінці ресторану плагін буде видаляти замовлення з вказаною причиною автоматично.

## 9. Налаштування створення задач для перезапуску плагіну

У Windows Task Scheduler (він же планувальник задач) - запустити примусово одну з задач:

1. expz-rkeeper-daily-%HASH% (для своєчасного оновлення плагіна)
2. expz-rkeeper-logon-%HASH% (для автоматичного запуску плагіна у разі перезавантаження касового сервера)

Якщо плагін було встановлено доволі давно, назви задач можуть бути іншими, назви задач старого зразку:

1. rkeepre-monobank-client-daily-task
2. rkeepre-monobank-client-on-logon-task

## 10. Завершення технічного підключення

Для завершення етапу "Технічне підключення" заповніть, будь ласка, контрольну анкету.&#x20;

Після того, як анкета буде заповнена, ми перевіримо підключення на нашому боці та надішлемо вам подальші інструкції.

{% hint style="success" %}
[Заповнити контрольну анкету](https://forms.gle/RY4oYvfagTvvJ4sv6)
{% endhint %}