# Про Expirenza

## Один QR-код для всього

### Меню, оплата рахунку, чайові, бронювання та відгуки

{% embed url="<https://www.youtube.com/watch?v=etRjEB8gv50>" %}


# Приєднання до оферти

#### Це перший етап підключення EXPIRENZA

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

***

### Перед початком

Ваш аккаунт-менеджер Expirenza надішле вам посилання на кабінет ресторану. Збережіть його — воно знадобиться для авторизації та налаштування.

#### Важливі умови

* Для підписання документів підписувач має бути клієнтом monobank: ФОП, бухгалтер або директор ТОВ.
* У вашого ФОП або ТОВ має бути відкритий рахунок у monobank.

### Крок 1. Авторизуйтесь у кабінеті

Перейдіть за посиланням, яке ви отримали від аккаунт-менеджера.

### Крок 2. Додайте банківські рахунки

1. Відкрийте розділ **«Банківські рахунки»**.
2. Натисніть **«Додати новий рахунок»**.
3. Введіть дані вашого рахунку monobank (ФОП або ТОВ) і дотримуйтесь підказок на екрані.

### Крок 3. Підпишіть документи в додатку monobank

Після додавання рахунку система автоматично:

* сформує необхідні документи, зокрема публічну оферту;
* надішле їх на підпис у ваш мобільний додаток monobank.

Підписувач (ФОП, бухгалтер або директор ТОВ) отримає push-сповіщення в додатку monobank. Відкрийте документ і підпишіть його.

> **Увага:** без підпису документів підключення рахунку не буде завершено.

### Відеоінструкція

Для зручності ми підготували коротке відео з усіма кроками:

🎥 <https://www.youtube.com/watch?v=Tt1JAp0-8-Q>

### Потрібна допомога?

Якщо у вас виникли запитання, зверніться до свого аккаунт-менеджера Expirenza або до служби підтримки.


# Технiчне підключення

Необхідно налаштувати інтеграцію з вашою POS системою:

{% content-ref url="/pages/Dd8xAcr58bV6Tpx3jT4x" %}
[r\_keeper](/setup/pos/rkeeper)
{% endcontent-ref %}

{% content-ref url="/pages/2FaGdgjX1vq524ql35Cs" %}
[Poster](/setup/pos/poster)
{% endcontent-ref %}

{% content-ref url="/pages/lk4UUIeGp9wQO0p6E4pU" %}
[Syrve](/setup/pos/syrve)
{% endcontent-ref %}

{% content-ref url="/pages/joUlNSfWRrtTRyHScpgM" %}
[SmartTouch](/setup/pos/smarttouch)
{% endcontent-ref %}

{% content-ref url="/pages/fRaLv6q0sIicv2eO2PL6" %}
[BarBoss](/setup/pos/barboss)
{% endcontent-ref %}

{% content-ref url="/pages/0mjPs0x5WA1YaR6LDu2n" %}
[SkyService](/setup/pos/skyservice)
{% endcontent-ref %}

{% content-ref url="/pages/hRcCLuPXp8dfX3N6KepX" %}
[Інші POS-системи](/setup/pos/other)
{% endcontent-ref %}


# 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 %}


# Налаштування QR на пречек

Печать qr на пречек у r\_keeper не пов'язана напряму з системою Expirenza. Налаштовується виключно ділером в менеджерській станції. Expirenza зі свого боку ніяк не управляє цим налаштуванням.

{% hint style="info" %}
Cкрипт у інструкції адаптован під ширину макета - 40.&#x20;

За нашої інформацією саме цю ширину використовує більшість ресторанів.
{% endhint %}

## Налаштування в менеджерській станції

Для того щоб перевірити ширину макета\
Виберіть Установки > Друк > Документи та макети\
Перейдіть до розділу Розрахунок з покупцем і виберіть пункт Прокр.

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

1.У менеджерській станції перейдіть до меню Налаштування > Налаштування > Розширені властивості

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

2.В “Свойства до справочников”, добавить расширенное свойство -&#x20;

pusherCode

* Назва: pusherCode
* Системне ім'я: pusherCode
* Статус: Активний

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

expzUrl

* Назва: expzUrl
* Системне ім'я: expzUrl
* Статус: Активний

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

3.Оберіть властивість pusherCode у розділі Основне натисніть **Список Типів**, потім на 3 точки.

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

4.У вікні що відкрилось  **Список типів для розширеної властивості** натисніть правою кнопкою миші у вільному полі та виберіть Додати елемент

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

5.Для властивості pusherCode додайте Ресторан із підрозділу Система

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

Після додавання об'єкта Ресторан у властивість pusherCode у розділі Основне в Списку Типів зміниться кількість типів елементів\
Для перевірки змін , оберіть властивість pusherCode у розділі Основне натисніть Список Типів, потім на 3 точки. Вікно, що відкрилося, має містити тип для розширеної властивості з найменуванням ClassInfo:Ресторан

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

6. Повторити п.3 - п.5 для властивості expzUrl

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

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

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

7\. Закройте Менеджерскую станцию и заново запустите Менеджерскую станцию&#x20;

8\. Перейдите в настройки ресторанов Сервис > Станции и устройства > Ресторан > Свойства > Расширенные свойства и заполните у ресторанов свойства pusherCode. (Получить в поддержке моно) и expzUrl. - значение <https://mbnk.biz/>

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

9. Перейдіть до меню: Налаштування > Друк > Використання схем друку. Дізнайтеся схему друку, яка використовується зараз: пріоритет знизу вгору — чим нижча, то пріоритетніше. (наприклад на скрині найпріоритетнішою є схема друку Основна Офіціант)

<figure><img src="/files/4OGWM9pw3sgmrtJJrl9T" alt=""><figcaption></figcaption></figure>

10. Перейдіть до меню: Налаштування > Друк > Схеми друку

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

11. Виберіть схему друку, яку ви дізнаєтеся в пункті 9. Знайдіть документ Провід, дізнайтеся який макет: номер і назва зараз використовується за замовчуванням.

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

12. Виберіть Налаштування > Друк > Документи та макети

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

13. Перейдіть до розділу **Розрахунок з покупцем** і виберіть пункт Пречек.

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

14. Скопіюйте макет поточного пречека назву та номер якого ви подивилися у **Схемі друку**. Натисніть на іконку пречеку правоб кнопкою миші і виберіть **Копіювати**, потім на порожньому місці **Вставити**

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

15.Введіть назву Пречек expz і переведіть **Статус** з **Чернетки** до **Активний**

<figure><img src="/files/9xf27Q5IlkMRThXhHcFP" alt=""><figcaption></figcaption></figure>

16. Перейдіть до редагування дизайну макета, натиснувши лівою кнопкою на ... у полі **Макет** або двічі натиснувши **\[Дизайн макета]**\ <mark style="color:red;">На даний момент скрипт адаптований під ширину макета - 40.</mark>

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

17. Знизу макета створіть новий **Віртуальний бенд**, для цього натисніть **правою кнопкою миші на біле поле** і натисніть **"Створити бенд"**, після цього оберіть "**Віртуальний**". Розтягніть мишкою бенд вниз.\
    Потім усередині бенда клацніть правою кнопкою миші і натисніть "**Створити мемо**". Розтягніть мемо за його краї на ширину чека.

<div><figure><img src="/files/uKRuXVIUo0RSZY53zx7h" alt=""><figcaption></figcaption></figure> <figure><img src="/files/xPCwcm9xi72Z2AcXbcxB" alt=""><figcaption></figcaption></figure> <figure><img src="/files/SdpoKDPyRhYTMLNMvENG" alt=""><figcaption></figcaption></figure></div>

Разом **бенд із вмістом мемо** матиме такий вигляд

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

18. Увійдіть у режим редагування, натиснувши правою кнопкою мишки на мемо, і вибравши пункт "**Режим редагування**" **і клацніть по мемо лівою кнопкою двічі** для відкриття вікна редагування мемо.

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

19. У мемо вставте скрипт.\
    Можливі проблеми в залежності від ширини макету. (Зараз за замовчуванням скрипт адаптований під ширину макета – 40)

{% hint style="warning" %}
Номер мемо в скрипті (Memo7) збігається з номером редагованого Memo, це обов'язкова умова для коректної роботи скрипта.&#x20;
{% endhint %}

<details>

<summary>Script</summary>

var&#x20;

&#x20; sQR, billId, normilizeBillId, url: string;&#x20;

begin

&#x20;    billId := \[Заказы.GUID];

&#x20;    normilizeBillId := Copy(billId, 2, 36);

&#x20;    url := \[System.Ресторан.expzUrl];

&#x20; begin                        &#x20;

&#x20;     sQR := url + \[System.Ресторан.pusherCode] + '/orderId\_' + normilizeBillId;

&#x20;     Memo7.text  :=  Char(#10)

&#x20;                  \+ 'Сплатити цей рахунок можна за QR-кодом' + Char(#10)

&#x20;                  \+ '             \<QRCode ' + sQR + '>' + Char(#10)

&#x20;                  \+ 'Наведіть камеру смартфона або QR-сканер' + Char(#10)

&#x20;  end;

end

</details>

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

20. Збережіть макет, натиснувши кнопку OK.
21. Знову відкрийте поточну схему друку, назву якої ви подивилися раніше у використання схем друку, оберіть поточний макет пречек, перегляньте який Клас осн. принтера вибрано, чи варто галочка Пакувати перед печаткою, запам'ятайте це.

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

22. Додайте створений раніше макет пречека: натисніть правою кнопкою миші на вільному місці, потім виберіть **Додати подання документа** \
    Виберіть розділ Розрахунок з покупцем, підрозділ прочок і двічі натисніть на макет.

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

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

23. У полі Клас осн. принтера виберіть той клас осн. принтера, і стан галочки Пакувати перед печаткою, які ви запам'ятали раніше зі старого макета, тобто необхідно порівняти налаштування полів Клас осн. принтера та Пакувати перед друком старого макета Пречек та нового Пречек expz

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

24. ВАЖЛИВО! \
    Видаліть старий макет з схеми друку, натиснувши на нього правою кнопкою мишки, потім Видалити. (Можливо можна зробити **неактивним** або не видаляти)

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

25. Перейдіть до налаштувань обладнання Сервіс > Станції та Пристрої та встановіть у налаштуваннях всіх принтерів, які друкують розриви розмір QR-коду:

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

26. Для кожної касової станції подивіться, який принтер використовується для друку бруньок
27. Для цього виберіть станцію, вкладка Властивості, у розділі Призначення принтерів перегляньте який принтер використовується Для пречеков, або іншого класу, якщо у схемі друку як Клас осн. принтера вказано інший клас.
28. У вкладці Принтери знайдіть цей принтер і перегляньте модуль, який він використовує.
29. У вкладці Пристрої знайдіть цей модуль та пропишіть наступні значення: Для термопринтерів (модуль EPSON):

QRCodeXYSize = 200 QRCodeIndent = 135 Для фіскальних реєстраторів (модуль Universal driver for fiscal printers) більшості типів:

BarcodeHeight = 200

Для фіскальних реєстраторів (модуль Universal driver for fiscal printers) типу 169 FR Atol DTO10:

BarcodeHeight = 100

Для фіскальних реєстраторів (модуль Universal driver for fiscal printers) типу 182 FR Custom:

BarcodeHeight = 50


# Останні зміни

### Версія #249 beta, #250 stable (07.02.2025)

* Додалась можливість видаляти створене замовлення за столом.

### Версія #244 (20.01.2025)

* Суттєво пришвидшили оновлення і кешування замовлень.

### Версія #225 (30.10.2024)

* Додали проактивну синхронізацію списка офіціантів.

  [<br>](https://docs.expirenza.com/setup/pos/syrve/loyalty)

### Версія #208 (8.10.2024)

* Відображення модифікаторів та комбо-елементів в чеку.


# Poster

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

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

Poster стягує **щомісячну** плату за використання інтеграції з Expirenza.

Вартість такої ліцензії складає 300₴ на місяць.

{% hint style="info" %}
Плата стягується за підключення плагіна Expirenza до облікового запису Poster, незалежно від кількості торгових точок в обліковому записі.
{% endhint %}

> **Встановлення плагіна**

{% hint style="warning" %}
Здійснювати підключення Expirenza **рекомендується** від імені власника облікового запису Poster.
{% endhint %}

Для підключення Expirenza у вашому ресторані виконайте наступні кроки:

1. Авторизуйтесь у адмін-панелі Poster вашого закладу.
2. [Перейдіть за посиланням](https://joinposter.com/applications/mono-1), та натисніть “Спробувати”.

<figure><img src="/files/r8B2NWpeLW2UHuVTyEL5" alt=""><figcaption><p>Poster</p></figcaption></figure>

3. На сторінці натисніть кнопку “Підключити”.

<figure><img src="/files/VZIrmV6lOmRTxsv35v6M" alt=""><figcaption><p>Poster</p></figcaption></figure>

4. Надайте необхідні для роботи плагіна дозволи натиснувши “Дозволити доступ”.

<figure><img src="/files/Nw4Sbb58uhXZ9rtF91VY" alt=""><figcaption><p>Poster</p></figcaption></figure>

***

## 2. Налаштування плагіна Expirenza

> **Активація вашого закладу у плагіні Expirenza**

Для активації закладу виконайте наступні кроки:

1. У лівому нижньому куту оберіть додаток Expirenza;
2. У вкладці “Авторизація” оберіть заклад, який хочете активувати та натисніть кнопку “Підключити”;
3. Скопіюйте `RESTO_ID` та `SECRET_KEY` з файлу `properties.txt`, який раніше отримали від менеджера Expirenza, і вставте у відповідні поля;
4. Натисніть "Зберегти";
5. Навпроти закладу має зʼявитись зелений індикатор “Підключено”.

<figure><img src="/files/MTHRHUsxPNVPzjfFAAxV" alt=""><figcaption><p>Poster</p></figcaption></figure>

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

Плагін Expirenza автоматично завантажує список персоналу з вашої POS-системи.&#x20;

Це потрібно для того, щоб співробітники могли:

* Отримувати сповіщення про оплату замовлень у Telegram-бот;
* Додати особисту картку для чайових, якщо так заведено у вашому закладі.

Для синхронізації співробітника виконайте наступні кроки:

1. Перейдіть у вкладку “Користувачі” плагіна Expirenza;
2. Переконайтесь, що у списку присутні всі співробітники, які приймають та обслуговують замовлення у вашому закладі. Зазвичай, це офіціанти та бармени.

{% hint style="info" %}
Якщо у списку відсутній хтось зі співробітників, будь ласка, додайте їх у налаштуваннях Poster, згідно з цією інструкцією: [Як додати співробітника](https://knowledge-base.joinposter.com/uk-ua/how-to-add-an-employee).

Та натисніть кнопку “Оновити”;
{% endhint %}

3. Вкажіть для кожного співробітника їхній номер мобільного телефону у відповідному полі та натисніть “Зберегти”.&#x20;
4. Після цього співробітники автоматично з’являться у розділі “Персонал та чайові” електронного кабінету закладу.

<figure><img src="/files/bYTRv3ZmN5bMDaoPM2pF" alt=""><figcaption><p>Poster</p></figcaption></figure>

> **Нумерація столів**

{% hint style="warning" %}
Для коректної роботи Expirenza, переконайтесь, що у вашому закладі всі столи мають унікальний числовий номер.&#x20;

Якщо назва стола містить будь-які символи, окрім цифр, такий стіл не буде завантажено у систему.
{% endhint %}

Перевірте нумерацію столів:

1. У адмін-панелі Poster, перейдіть у розділ "Налаштування" → "Столи";
2. Переконайтесь, що у назві всіх столів наявні лише цифри;

<figure><img src="/files/L9UoH2n4MtrtJy3TkTdE" alt=""><figcaption><p>Poster</p></figcaption></figure>

{% hint style="info" %}
Як змінити нумерацію столів можно [прочитати у цій інструкції](https://support.joinposter.com/uk/articles/6306458-як-розмістити-столи-на-плані-залу).
{% endhint %}

> **Інші налаштування**

За замовчуванням, плагін Expirenza автоматично відправляє команду фіскалізувати чек під час закриття рахунку у Poster.

Щоб відключити автоматичну фіскалізацію, необхідно виконати наступні кроки:

1. Перейдіть у вкладку “Налаштування” плагіна Expirenza;
2. Переведіть перемикач “Автоматична фіскалізація” у неактивне положення;
3. Дочекайтесь сповіщення “Дані збережено” у правому верхньому куті.

<figure><img src="/files/ZSA9qq7bhf9mHvy2xqT7" alt=""><figcaption><p>Poster</p></figcaption></figure>

***

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

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

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

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

***


# Оплата за обслуговування

## Загальна інформація

Для забезпечення роботи оплати за послуги обслуговуваня на ФОП рахунок ресторану необхідно завести в Poster окремий продукт - `Expirenza Обслуговування`.

\
Після цього, якщо у ресторана активована опція сплати за послуги обслуговування на ФОП і клієнт залишає оплату за обслуговування, плагін, отримавши цю інформацію від backend, перевірить поточний чек в Poster. Якщо в чеку ще не було додано позицію `Expirenza Обслуговування` на оплачену суму, плагін отримає з Poster дані про заведений продукт.

\
Якщо він є і відповідає всім вимогам, плагін зробить спробу додати позицію в чек. Якщо продукт не заведено, або заведено не правильно, плагін поверне помилку на backend, а в фоні спробує оновити продукт **Expirenza** **Обслуговування**, якщо він був заведений.&#x20;

**Якщо продукт не заведений, то він автоматично не створиться.**

У випадку, коли плагін перевіряє чек і вже бачить що продукт **Expirenza** **Обслуговування** був доданий і сума збігається з тією, що вказав клієнт, то чек буде закритий, без додаткових дій. Якщо сума не збігається - плагін поверне помилку.

## Параметри продукту **“Expirenza** **Обслуговування”**

Для того, щоб плагін зміг успішно додати позицію для переказу оплати за обслуговування на ФОП - **Expirenza** **Обслуговування**, він має бути заведений в Poster з наступними параметрами:

* Мати назву `Expirenza Обслуговування`, зі збереженням регістру, без інших символів (пробіли на початку, в кінці, точки, коми, тощо)
* Страва має бути вагова
* Страва доступна на споті який використовується рестораном
* Ціна за 100 грамм - 100 копійок для споту який використовується рестораном

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

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

## Фонове оновлення продукту **“Expirenza** **Обслуговування”**

Процес фонового оновлення запускається в двох випадках:

1. Отримання плагіном параметру налаштування про включення в ресторані оплати за обслуговування на фоп
2. При закритті рахунку, якщо продукт **Expirenza** **Обслуговування** не проходить валідацію.

При цьому плагін отримує інформацію, чи був у ресторана раніше заведений продукт і чи відомий його Id в Poster.&#x20;

Якщо **так**, то по АПІ `menu.getProduct` отримуєм продукт, якщо його вже немає - видаляємо раніше збережений Id продукта в плагіні і процес оновлення завершується помилкою.\
Якщо продукт є і він проходить валідацію - додаткових дій не потрібно. Якщо ж валідацію не проходить - параметри продукту буде оновлено до необхідних (через АПІ - `menu.updateProduct`).

Якщо ж плагін не має Id продукту **Expirenza** **Обслуговування**, то спробує отримати всі продукти з Poster ( АПІ - `menu.getProducts`) і знайти по імені продукту. Якщо продукт буде знайдено, то його id буде збережено в плагіні та так само плагін провалідує і якщо необхідно оновить продукт в Poster).

## АПІ Poster,  які використовуються в процесі

1. Отримати продукт по id - [Документація по API Poster](https://dev.joinposter.com/ua/docs/v3/web/menu/getProduct?id=menugetproduct-%d0%92%d0%bb%d0%b0%d1%81%d1%82%d0%b8%d0%b2%d0%be%d1%81%d1%82%d1%96-%d1%82%d0%be%d0%b2%d0%b0%d1%80%d1%83-%d0%b0%d0%b1%d0%be-%d1%82%d0%b5%d1%85-%d0%ba%d0%b0%d1%80%d1%82%d0%b8)
2. Зміна параметрів продукту - [Документація по API Poster](https://dev.joinposter.com/ua/docs/v3/web/menu/updateProduct?id=menuupdateproduct-%d0%97%d0%bc%d1%96%d0%bd%d0%b0-%d0%b2%d0%bb%d0%b0%d1%81%d1%82%d0%b8%d0%b2%d0%be%d1%81%d1%82%d0%b5%d0%b9-%d1%82%d0%be%d0%b2%d0%b0%d1%80%d1%83)
3. Отримати список продуктів - [Документація по API Poster](https://dev.joinposter.com/ua/docs/v3/web/menu/getProducts?id=menugetproducts-%d0%a1%d0%bf%d0%b8%d1%81%d0%be%d0%ba-%d1%82%d0%be%d0%b2%d0%b0%d1%80%d1%96%d0%b2-%d1%96-%d1%82%d0%b5%d1%85-%d0%ba%d0%b0%d1%80%d1%82)
4. Додати позицію в чек - [Документація по API Poster](https://dev.joinposter.com/ua/docs/v3/web/transactions/addTransactionProduct?id=transactionsaddtransactionproduct-%d0%94%d0%be%d0%b4%d0%b0%d0%b2%d0%b0%d0%bd%d0%bd%d1%8f-%d1%82%d0%be%d0%b2%d0%b0%d1%80%d1%83-%d0%b4%d0%be-%d1%87%d0%b5%d0%ba%d0%b0)


# Syrve

## Підключення плагіну Expirenza до Syrve

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

Запросіть у вашого менеджера Syrve додаткову ліцензію "`Syrve API Payment Connector`".&#x20;

Вона буде потрібна під час налаштування Syrve POS, для підключення додаткового методу оплати.

***

## Налаштування Syrve Office / Syrve HQ

### **Налаштування основного типу оплати**

1. Виберіть пункт меню "Роздрібні продажі" → "Типи оплати" і натисніть кнопку "Додати".
2. Заповніть форму наступним чином:
   * В поле "Найменування" введіть “Expirenza”
   * У випадаючому списку параметра "Тип" виберіть значення "Банківські картки"
   * В поле "Назва в чеку" введіть “Expirenza”
3. Позначте такі опції:
   * Забороняти вводити вручну
   * Застосовувати для всіх категорій страв
   * Друкувати товарний чек (опціонально)
   * Може прийматися ззовні
   * Є фіскальним.
4. У випадаючому списку параметра "Проведення оплат" виберіть значення "Як зовнішній, так і на стороні ресторану".
   * В поле "Код" встановіть значення "EXPZ"
5. Натисніть "Зберегти".

<figure><img src="/files/2xAlTbxpVMSRYZzSh18E" alt=""><figcaption><p>Правильно створений тип оплати</p></figcaption></figure>

### **(опціонально) Налаштування типу оплати для Dark Kitchen**

{% hint style="info" %}
Для оплати замовлень створених за допомогою модулю Syrve Delivery, Expirenza використовує окремий тип оплати. Його налаштування дещо відрізняються від базового типу оплати "Expirenza".
{% endhint %}

1. Виберіть пункт меню "Роздрібні продажі" → "Типи оплати" і натисніть кнопку "Додати"
2. Заповніть форму наступним чином:
   * В поле "Найменування" введіть “EXPZ Delivery”
   * У випадаючому списку параметра "Тип" виберіть значення "Банківські картки"
   * В поле "Назва в чеку" введіть “EXPZ Delivery”
3. Позначте такі опції:
   * Можна комбінувати з іншими типам оплат
   * Застосовувати для всіх категорій страв
   * Друкувати товарний чек (опціонально)
   * Може прийматися ззовні
   * Є фіскальним
4. В пункті "Проведення оплат" встановіть значення "Як зовнішній, так і на стороні ресторану".
   * В поле "Код" встановіть значення "DELIV"
5. Натисніть "Зберегти".

<figure><img src="/files/b2DWDnvxZNDv6bM6tYU2" alt=""><figcaption><p>Приклад коректно створеного типу оплати для Dark Kitchen</p></figcaption></figure>

***

### Налаштування типу замовлення Expirenza для замовлень за столом

#### 1. Створення типу замовлення

Шлях у меню:\
Роздрібні продажи → Типи замовлень

#### Кроки

1. Перейдіть: Роздрібні продажи → Типи замовлень.
2. Натисніть Додати (створення нового типу замовлення).
3. Заповніть поля:

* Найменування: `Expirenza`
* Режим обслуговування: `Звичайне замовлення`

Натисніть Зберегти / Зберіжіть зміни.

✅ Результат: у довіднику “Типи замовлень” з’явиться новий тип Expirenza.<br>

#### 2. Як це працює (логіка підстановки в замовленні за столом)

Під час створення замовлення за столом:<br>

1. Спочатку система шукає тип замовлення з назвою Expirenza.
2. Якщо Expirenza не знайдено, система використовує перший доступний тип замовлення, який “попався” у списку (це поточна логіка).

> Примітка: логіка fallback (“взяти перший що попався тип”) спрацьовує лише якщо Expirenza відсутній/не створений/недоступний.

#### 3. Де побачити поточний тип замовлення

Тип замовлення можна переглянути в картці/формі створеного замовлення за столом у полі “Тип замовлення” (або аналогічному полі в заголовку/деталях замовлення).

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

#### 4. Перевірка налаштування

1. Переконайтесь, що тип Expirenza створений і збережений у Типи замовлень.
2. Створіть нове замовлення за столом.
3. Перевірте, що в замовленні підставився Тип замовлення = Expirenza.

#### Типові проблеми

* Тип замовлення **Expirenza** не підставляється: перевірте, що назва введена точно `Expirenza` і зміни збережені.
* Тип не видно в списку / не знаходиться: перевірте права доступу до довідника/налаштувань та чи активний запис (якщо у вашій системі є ознака активності).
* Підставляється “не той” тип: це очікувано, якщо Expirenza не знайдено — тоді спрацьовує підстановка першого типу за поточною логікою.

***

### **Створення віртуального касира**

1. Виберіть пункт меню "Співробітники" → "Співробітники" і натисніть кнопку "Додати".
2. На сторінці "Основні відомості":
   * В поле "Ім'я в системі" введіть “Expirenza”
   * В полі “Посада” виберіть “Системний адміністратор”
   * Активуйте опцію "Тільки для плагінів"
   * Активуйте опцію "Співробітник"

<figure><img src="/files/4pyaL9v0T5ty76a9dVq6" alt=""><figcaption><p>Приклад коректно створеного віртуального касира</p></figcaption></figure>

3. Перейдіть на сторінку "Додаткові відомості" та встановіть унікальний ПІН-код з 4-6 цифр (він знадобиться пізніше для налаштування Syrve POS)
4. Натисніть “Зберегти”

<figure><img src="/files/VGOS8jj8V50UwJN7pOVa" alt=""><figcaption><p>ПІН-код віртуального касира Expirenza у Syrve</p></figcaption></figure>

{% hint style="warning" %}
**ЗВЕРНІТЬ УВАГУ!** Наразі, перелік мінімально необхідних прав для віртуального касира Expirenza виглядає так:
{% endhint %}

<table><thead><tr><th width="156">Код</th><th>Найменування</th></tr></thead><tbody><tr><td>F_APIO</td><td>Авторизувати касові внесення та вилучення</td></tr><tr><td>F_CASH</td><td>Приймати платежі</td></tr><tr><td>F_CLOR</td><td>Переглядати закриті замовлення</td></tr><tr><td>F_CLOS</td><td>Переглядати суми в закритих замовленнях</td></tr><tr><td>F_PRPRE</td><td>Проводити передоплату</td></tr><tr><td>F_CGC</td><td>Змінювати кількість гостей</td></tr><tr><td>F_CHO</td><td>Відкривати замовлення в якості офіціанта</td></tr><tr><td>F_DNPI</td><td>Видаляти ненадруковані рядки</td></tr><tr><td>F_CCB</td><td>Авторизовувати операції повʼязані зі скасуванням попереднього чека</td></tr><tr><td>F_OMO</td><td>Відкривати кілька замовлень на один стіл</td></tr><tr><td>F_REP</td><td>Авторизувати видалення передоплати</td></tr><tr><td>F_AOT</td><td>Створювати і редагувати замовлення інших офіціантів</td></tr><tr><td>F_COW</td><td>Авторизувати перенесення замовлення іншому офіціантові</td></tr><tr><td>F_CPOTB</td><td>Роздруковувати попередній чек на замовлення інших офіціантів</td></tr><tr><td>D_DEP</td><td>Видаляти зовнішні платежі</td></tr><tr><td>B_CEXORD</td><td>Створювати зовнішні замовлення</td></tr><tr><td>F_PAW</td><td>Приймати оплату у якості офіціанта</td></tr><tr><td>PS_ADM</td><td>Проводити адміністративні операції з платіжними системами</td></tr><tr><td>F_EFA</td><td>Дозволяти вводити дробову кількість товару</td></tr><tr><td>F_MPR</td><td>Обʼєднувати столи з віддрукованими стравами</td></tr><tr><td>F_APA</td><td>Підтверджувати нарахування бонусних балів</td></tr><tr><td>F_ID</td><td>Встановлювати надбавку і знижку для замовлення</td></tr><tr><td>F_IDCN</td><td>Встановлювати надбавку і знижку за карткою гостя без її прокатки</td></tr><tr><td>F_IDGC</td><td>Встановлювати надбавку і знижку по картці гостя</td></tr><tr><td>F_CMP</td><td>Змінювати номер столу з віддрукованими стравами</td></tr></tbody></table>

### **Категорії та розрахунки**

Переконайтесь, що у Syrve Office / Syrve HQ для кожної страви встановлено значення "Категорія" (наприклад, “Бар алкоголь”, “Бар безалкогольний”, “Кухня” тощо), адже Expirenza за цією ознакою розподіляє кошти від продажу страв і напоїв на відповідні банківські рахунки.&#x20;

Ви зможете налаштувати розподіл коштів у адмін-панелі Expirenza у розділі "Банківські рахунки".

{% hint style="success" %}
Приклад правильно встановлених категорій - **Усім стравам призначені категорії**
{% endhint %}

<figure><img src="/files/AWz1zuzij9qsLjzaIFpA" alt=""><figcaption><p>Кожна страва має категорію</p></figcaption></figure>

{% hint style="danger" %}
Приклад неправильно встановлених категорій - **Існують страви без категорій**
{% endhint %}

<figure><img src="/files/v2cwki0r3heK0FU2eqRO" alt=""><figcaption><p>Порожні категорії для страв</p></figcaption></figure>

1. Перевірте список ваших категорій:
   * Виберіть пункт меню "Товари і склади" → "Страви" і натисніть кнопку "Дії".
   * У списку, виберіть пункт "Редагувати список категорій".
   * Якщо список категорій не відповідає вашій номенклатурі, тоді додайте нові категорії.

<figure><img src="/files/6nK9zUCQTqlWEPOmphGc" alt=""><figcaption></figcaption></figure>

2. Для присвоєння категорії кільком стравам одночасно, виділіть мишкою всі страви в теці і натисніть "Дії" → "Редагувати".
3. Встановіть необхідну категорію в пункті "Категорія"
4. Натисніть "Зберегти".

<figure><img src="/files/6IcSvSXJBn4ZHwcJQjNV" alt=""><figcaption></figcaption></figure>

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

{% hint style="info" %}
Expirenza автоматично завантажує список персоналу з вашої системи. Це дозволяє нам:

* Надсилати їм сповіщення про успішні оплати через Telegram-бота.
* Перераховувати офіціантам (та курʼєрам закладів Dark Kitchen) їхні чайові на особисту картку.
  {% endhint %}

Система завантажує дані лише тих працівників, у кого заповнене поле “Моб. телефон”.

* Виберіть пункт меню "Співробітники" → "Співробітники".&#x20;
* Для зручності відсортуйте персонал за ознакою "Посада".

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

1. Переконайтесь, що у співробітників з посадами "касир", "офіціант", "бармен", "кур'єр" (і / або іншими посадами, за якими співробітники у вашому закладі беруть участь в проведенні оплати і закриття рахунків) заповнене поле "Моб. телефон".
2. Якщо поле "Моб. телефон" не заповнене, то додайте кожному співробітнику номер телефону в форматі "`+380XXXXXXXXX`" в поле "Моб. телефон" і натисніть "Зберегти".

### **Нумерація столів**

Для коректної роботи системи, переконайтесь, що у вашому закладі (в термінах Syrve - “групі”) всі столи мають **унікальний** номер.&#x20;

Expirenza сприймає столи з однаковими номерами, як один і той самий стіл, навіть, якщо ці столи знаходяться у різних залах.

1. Перейдіть в пункт меню "Адміністрування" → "Налаштування торговельного підприємства";
2. Оберіть відділення зі списку та перейдіть на вкладку “Налаштування столів”;
3. Порівняйте нумерацію столів у кожному відділенні;
4. Якщо номери столів дублюються, змініть нумерацію столів таким чином, щоб кожен стіл мав унікальний номер.

{% hint style="info" %}
**Приклад:** У вашому закладі є відділення “Зал” та “Бар”, в кожному з яких існує стіл №5.&#x20;

У такому разі, ви можете лишити нумерацію стола у відділенні “Зал” без змін, а у відділенні “Бар” змінити номер стола на №105.
{% endhint %}

### **Оплата та закриття замовлень**

Після отримання оплати від гостя, Expirenza автоматично закриває замовлення у вашій системі.&#x20;

Для коректної роботи плагіну, переконайтесь, що в Syrve Office / Syrve HQ виконані наступні налаштування:

1. Перейдіть в пункт меню "Адміністрування" → "Налаштування торговельного підприємства";
2. Оберіть відділення зі списку та перейдіть на вкладку “Загальні налаштування”;
3. Ввімкніть опцію “Дозволити оплату замовлення без пречека”;
4. Збережіть зміни;
5. Повторіть ці дії для всіх відділень вашого закладу.

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

### **Налаштування відкладеного сканування маркування товару**

POS-системі Syrve замовлення, які містять акцизні товари (алкоголь, тютюн) не можуть бути оплачені та закриті доти, доки не проскановано код маркування або не вказано, що його немає.&#x20;

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

Зважаючи, що закриття замовлення плагіном відбувається без участі персоналу закладу, для коректного закриття замовлень, переконайтеся, що у Syrve Office / Syrve HQ налаштування виконані, як зазначено нижче:

1. Перейдіть в пункт меню "Адміністрування" → "Налаштування торговельного підприємства";
2. Оберіть відділення зі списку та перейдіть на вкладку "Загальні налаштування";
3. Відключіть опцію "Дозволити відкладене сканування марок";
4. Збережіть зміни;
5. Повторіть ці дії для всіх відділень вашого закладу.

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

### **Налаштування друку сервісних чеків**

Перед закриттям замовлення, Syrve обовʼязково перевіряє чи були надруковані сервісні чеки ("зустрічки"). Якщо сервісні чеки не були надруковані, то закрити замовлення буде неможливо.

1. Перейдіть в пункт меню "Адміністрування";
2. Виберіть розділ "Налаштування торгового підприємства";
3. Оберіть групу зі списку;
4. На вкладці "Загальні налаштування" активуйте опцію "Сервісний друк під час виходу із замовлення";
5. Збережіть зміни;
6. Повторіть такі дії для всіх груп вашого закладу.

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

### **(опціонально) Налаштування округлення сум**

Якщо у вашому закладі використовується округлення сум, для коректного зарахування коштів на банківські рахунки, переконайтеся, що налаштування округлення в Syrve Office / Syrve HQ відповідають наведеним нижче:

1. Виберіть “Адміністрування” → “Налаштування торгового підприємства”;
2. Перейдіть на вкладку "Налаштування валюти";
3. У блоці "Округлення" → "Округлення у Syrve POS" перевірте такі налаштування:
   * Відключіть опцію "Округляти вартість замовлення до цілого на користь гостя";
   * Увімкніть опцію "Округлення ціни за одиницю на користь гостя".
4. Натисніть “Зберегти зміни”.

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

***

## Налаштування Syrve POS

> **Встановлення плагіну Expirenza**

{% hint style="warning" %}
Ящо у вашому закладі є декілька станцій з Syrve POS, то плагін необхідно встановити лише на головну станцію.
{% endhint %}

1. Завантажте архів з плагіном[ за посиланням.](https://plugins.expirenza.com/syrve-plugin-v7/Resto.Front.Api.monoPayment.zip)
2. Закрийте програму Syrve POS;
3. Визначте шлях для розпакування архіву - через провідник Windows подивіться де встановлена тека "iiko".

   Можливі варіанти:

   * `C:\Program Files\`
   * `C:\Program Files (x86)\`
4. Залежно від версії, пройдіть подальший шлях по теках "iiko" → "iikoRMS" → "Front.Net" → "Plugins"
5. Створіть в теці "Plugins" теку “`Resto.Front.Api.monoPayment`”
6. Розпакуйте в цю теку вміст архіву з кроку 1.
7. Після коректного розпакування архіву файли будуть знаходитися за одним з двох шляхів:
   * C:\Program Files\iiko\iikoRMS\Front.Net\Plugins\Resto.Front.Api.monoPayment
   * C:\Program Files(x86)\iiko\iikoRMS\Office\Plugins\Resto.Front.Api.monoPayment
8. Вставте в теку “`Resto.Front.Api.monoPayment`” файл “`properties.txt`”, який раніше отримали від менеджера Expirenza.

> **Налаштування ключів**

1. Зайдіть в теку "Resto.Front.Api.monoPayment" і відкрийте файл "properties.txt" за допомогою редактора Блокнот.
2. Встановіть наступні значення:
   * `RESTO_ID` - заповнюється менеджером Expirenza;
   * `SECRET_KEY` - заповнюється менеджером Expirenza;
   * `PLUGIN_USER` - ПІН-код з чотирьох цифр користувача Expirenza, якого ви створили під час налаштування Syrve Office / Syrve HQ.<br>
3. Закрийте Блокнот вибравши варіант "Зберегти зміни".

<figure><img src="/files/bv5VBQArCXPqvZl6ZjrU" alt=""><figcaption><p>Приклад коректно заповненого блокнота</p></figcaption></figure>

> **Перевірка плагіна в Syrve POS**

1. Запустіть Syrve POS і перейдіть в меню “Доповнення”;
2. Виберіть пункт “Expirenza”;

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

3. У блоці "Основні налаштування" перевіряються обов'язкові умови для роботи плагіна Expirenza у ресторані. Тобто результат всіх перевірок у цьому блоці має бути "так".
4. У блоці "Додаткові налаштування" перевіряються умови які потрібні лише закладам зі специфічним типом обслуговування, як от додатковий тип оплати для Dark Kitchen, або не стосуються безпосередньо плагіна.&#x20;

   **Наприклад**, як активація друку платіжних QR-кодів на попередньому чеку або накладній доставки.

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

***

## Можливі проблеми у процесі установки

<details>

<summary><strong>Блокування файлів брандмауером Windows</strong></summary>

Залежно від налаштувань безпеки вашого комп'ютера, брандмауер Windows може блокувати деякі типи файлів.&#x20;

Для коректної роботи плагіна Expirenza необхідно переконатися, що його файли не були заблоковані.

**Як перевірити і розблокувати файли плагіна?**

1. Зайдіть в теку "Resto.Front.Api.monoPayment".
2. Правою кнопкою миші натисніть на перший файл, а потім виберіть "Властивості" і перейдіть у вкладку "Загальні".
3. Якщо у вкладці "Загальні" ви бачите повідомлення про блокування файлу (як на зображенні нижче, то файл необхідно розблокувати.
4. Біля повідомлення про блокування файлу натисніть кнопку "Розблокувати", а потім натисніть кнопку "Застосувати".
5. Аналогічним чином перевірте і, за потреби, розблокуйте всі файли в теці "Resto.Front.Api.monoPayment".
6. Після розблокування файлів, перезавантажте Syrve POS і повторіть дії описані в пункті "Перевірка Syrve POS" вище.

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

</details>

<details>

<summary><strong>Syrve: плагін Expirenza падає при запуску через Планувальник завдань Windows</strong></summary>

### Опис проблеми <a href="#opis-problemi" id="opis-problemi"></a>

Плагін Expirenza для Syrve не запускається, якщо Syrve запущено через Планувальник завдань Windows (Windows Task Scheduler). Плагін працює у неправильній робочій директорії (`C:\Windows\System32`) замість директорії встановлення Syrve.

### Симптоми <a href="#simptomi" id="simptomi"></a>

Плагін падає при запуску з такими помилками:

```
File C:\Windows\System32\Plugins\Resto.Front.Api.monoPayment\download is not present
Could not find a part of the path 'C:\Windows\System32\Plugins\Resto.Front.Api.monoPayment\download'
Could not find a part of the path 'C:\Windows\System32\Plugins\Resto.Front.Api.monoPayment\properties.txt'
Couldn't create plugin instance
```

### Причина <a href="#prichina" id="prichina"></a>

Коли завдання в Планувальнику задач Windows запускає виконуваний файл або скрипт без вказаної директорії **Start In**, Windows за замовчуванням використовує `C:\Windows\System32` як робочу директорію. Плагін Expirenza використовує відносні шляхи для пошуку своїх файлів, тому шукає їх у `System32` замість директорії Syrve.

### Розв'язання <a href="#rozvyazannya" id="rozvyazannya"></a>

#### Якщо Syrve запускається через Планувальник завдань Windows <a href="#yaksho-syrve-zapuskayetsya-cherez-planuvalnik-zavdan-windows" id="yaksho-syrve-zapuskayetsya-cherez-planuvalnik-zavdan-windows"></a>

Необхідно встановити директорію **Start In** для завдання:

1. Відкрийте **Планувальник завдань** (`taskschd.msc`)
2. Знайдіть завдання, яке запускає Syrve
3. Відкрийте **Властивості** завдання → вкладка **Дії**
4. Оберіть дію та натисніть **Змінити**
5. У полі **Start in (необов'язково)** вкажіть шлях до директорії встановлення Syrve

**Приклад:**

| Поле            | Значення                           |
| --------------- | ---------------------------------- |
| Програма/скрипт | `C:\Program Files\Syrve\start.bat` |
| Start in        | `C:\Program Files\Syrve`           |

6. Натисніть **ОК** та збережіть завдання
7. Запустіть завдання знову та перевірте, що плагін стартує коректно

</details>

***

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

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

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


# Оновлення плагіна

## Як запустити автоматичне оновлення плагіна для Syrve?

Що запустити автоматичне оновлення плагіна, будь ласка, перезавантажте програму Syrve POS на головній станції вашого закладу.

Система самостійно завантажить та встановить оновлення.

***

## Як оновити плагін для Syrve вручну?

Плагін Expirenza можна оновити вручну. Для цього необхідно виконати такі дії:

Завантажте архів з плагіном за посиланням в залежності від версії syrve для версії Syrve 7.9 - 8.7 (syrve api v7) - <https://plugins.expirenza.com/syrve-plugin-v7/Resto.Front.Api.monoPayment.zip> (Лише підтримуємо цю версію) Буде актуальним до версії syrve 9.4.

Для версії Syrve 8.7 (Syrve Api v8) та вище - рекомендується встановлювати плагін за посиланням [https://plugins.expirenza.com/syrve-plugin-v8/Resto.Front.Api.monoPayment.zip ](<https://plugins.expirenza.com/syrve-plugin-v8/Resto.Front.Api.monoPayment.zip >) (актуальний плагін)

1. На головній касі повністю вимкніть програму Syrve POS;
2. Розпакуйте завантажений архів у теку з плагіном. Зазвичай вона знаходиться за таким шляхом:

`С:\ProgramFiles\iiko\iikoRMS\Front.Net\Plugins\Resto.Front.Api.monoPayment`

4. Коли система запропонує замінити файли у теці, виберіть "Так для всіх";

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


# Друк QR-коду на пречеку

### **Друк платіжного QR-коду на пречеку / накладній доставки**

{% hint style="warning" %}
Друк платіжного QR-коду на пречеку та накладній доставки доступний лише закладам, що завершили підключення і налаштування Expirenza.
{% endhint %}

Переконайтесь, що:

1. В шаблоні попередньому чеку / накладної доставки додано такий код:

```html
​<whitespace-preserve>
@Raw(string.Join(Environment.NewLine, Model.Extensions.AfterFooter))
</whitespace-preserve>
```

2. З боку Expirenza для закладу активована можливість проводити оплату замовлень.


# Програма лояльності Expirenza

## Як налаштувати знижку для програми лояльності Expirenza у POS-системі Syrve?

1. У Syrve Office перейдіть до розділу “Дисконтна система” -> “Знижки та надбавки”&#x20;

2. Натисніть “Додати” для створення нової знижки

3. Налаштуйте крок "Основні параметри знижки" наступним чином:
   * Назва: Знижка Expirenza
   * Назва в попередньому чеку: Знижка Expirenza<br>

     <figure><img src="/files/QI1RvjOWrD5hy1eaGlUJ" alt="" width="375"><figcaption><p>Приклад налаштування кроку "Основні параметри знижки"</p></figcaption></figure>

4. Натисніть “Далі”

5. Налаштуйте крок "Налаштування знижки" наступним чином:
   * Активуйте опцію "Можна призначати по картці"
   * Активуйте опцію "Вибір страв на розсуд офіціанта"
   * В блоці "Місця продажів, де застосовується знижка" оберіть "Усі місця для продажів"
   * В блоці "Режим обслуговування, в якому застосовується знижка" активуйте всі доступні режими обслуговування - "*Звичайне замовлення", "Доставка курʼєром", "Доставка самовивезенням"*
   * Активуйте опцію "Можна використовувати з іншими знижками"<br>

     <figure><img src="/files/K1z0N5Gj0kyveI5NhoT7" alt="" width="375"><figcaption><p>Приклад налаштування кроку "Налаштування знижки"ʼ</p></figcaption></figure>

6. Натисніть “Далі”

7. Налаштуйте крок "Розмір і тип (знижка або надбавка)" наступним чином:&#x20;
   * В блоці "Метод застосування" оберіть "До повної суми замовлення"
   * В блоці "Тип" оберіть "Знижка", "Фіксована сума" та активуйте опцію "Призначати суму"
   * Активуйте опцію "Застосовувати для всіх категорій страв"<br>

     <figure><img src="/files/JGcfjC2cLGAMHb8sJhtb" alt="" width="375"><figcaption><p>Приклад налаштування кроку "Розмір і тип (знижка або надбавка)"ʼ</p></figcaption></figure>

8. Натисніть “Далі”

9. Налаштуйте крок "Статус знижки" наступним чином:
   * Активуйте опцію "Активувати знижку"<br>

     <figure><img src="/files/2mQITzOsTwBhuosj5gHv" alt="" width="375"><figcaption><p>Приклад налаштування кроку "Статус знижки"</p></figcaption></figure>

10. Натисніть “ОК”


# Оплата за обслуговування

Для підключення послуги зарахування оплати за обслуговування на розрахунковий рахунок закладу у POS-системі Syrve необхідно виконати ряд налаштувань. Цей функціонал дозволяє автоматично фіскалізувати цю послугу та відправляти сплату за неї на розрахунковий рахунок ФОП закладу.

## Передумови

Для налаштування зарахування оплати за обслуговування на ФОП закладу необхідно:

* Мати встановлений плагін Expirenza для Syrve
* Володіти правами адміністратора в Syrve Office
* Мати налаштований розрахунковий рахунок закладу в системі Expirenza з відповідним КВЕД&#x20;

## 1. Створення позиції для оплати за обслуговування

1. Зайдіть в Syrve Office через свій обліковий запис
2. Перейдіть у розділ Довідники → Меню → Страви
3. Натисніть Додати для створення нової страви
4. Заповніть форму з такими параметрами:
5. Назва: Expirenza Обслуговування
6. Тип: Послуга
7. Ціна: Вільна
8. Рух по складу: Вимкнено
9. Збережіть зміни

{% hint style="warning" %}
Назва страви повинна бути саме Expirenza Обслуговування. \
Система автоматично шукає цю позицію за назвою.\
Налаштування в Syrve Office
{% endhint %}

## 2. Налаштування фіскального принтера

Для коректної фіскалізації послуги необхідно налаштувати фіскальний принтер:

1. У Syrve Office перейдіть до розділу Адміністрування → Плагіни
2. Знайдіть кнопку Expirenza Обслуговування\
   **Примітка**: Кнопка відображається лише для закладів, у яких підключено послугу оплати за обслуговування на ФОП і створено відповідну позицію меню
3. Натисніть на кнопку та оберіть потрібний фіскальний реєстратор зі списку
4. Поточний фіскальний реєстратор буде виділено у списку
5. Підтвердіть вибір

<div><figure><img src="/files/jGdy8pyr27AlcmKhUjlf" alt=""><figcaption></figcaption></figure> <figure><img src="/files/wQKGXNyJqhAes4w1w6QR" alt=""><figcaption></figcaption></figure></div>

## Принцип роботи

1. Гість сплачує рахунок через Expirenza (включно з оплатою за обслуговування)
2. Система визначає, що кошти за обслуговування мають бути зараховані на рахунок закладу
3. Плагін автоматично додає позицію Expirenza Обслуговування до чеку з відповідною сумою&#x20;
4. Система друкує пречек (на цьому етапі чек може розподілятися за місцями приготування)
5. Закриваються дочірні чеки (якщо такі є)
6. Плагін підтверджує закриття рахунку та формує деталізацію
7. Кошти за обслуговування фіскалізуються як “послуга обслуговування” та зараховуються на розрахунковий рахунок закладу, вказаний у налаштуваннях

### Особливості та обмеження

* Система автоматично визначає фіскальний принтер, але в деяких випадках потрібне ручне налаштування
* При розділенні рахунку на кілька частин до оплати, необхідно вказати фіскальний реєстратор вручну
* Зміна суми позиції Expirenza Обслуговування вручну в POS-системі призведе до помилки

## Можливі проблеми та їх вирішення

| Проблема                                    | Код помилки                        | Вирішення                                                        |
| ------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------- |
| Страва Expirenza Обслуговування не знайдена | RESTAURANT\_TIPS\_NOT\_CONFIGURED  | Перевірте коректність створення позиції меню з точною назвою     |
| Не обрано фіскальний реєстратор             | RESTAURANT\_TIPS\_NOT\_CONFIGURED  | Налаштуйте фіскальний реєстратор через меню Плагіни              |
| Рахунок уже закрито іншою системою          | ALIEN\_PAY\_NEED\_RESTAURANT\_TIPS | Зверніться до технічної підтримки                                |
| Рахунок закрито без урахування чайових      | RESTAURANT\_TIPS\_BILL\_CLOSED     | Перевірте налаштування типів оплат та зв'яжіться з техпідтримкою |
| Сума чайових змінена вручну                 | RESTAURANT\_TIPS\_WRONG\_AMOUNT    | Не змінюйте суму вручну після додавання позиції системою         |

## Тестування налаштувань

Для перевірки правильності налаштувань:

1. Створіть тестовий рахунок у закладі
2. Додайте будь-які позиції з меню
3. Ініціюйте оплату з сплатою за обслуговування через Expirenza: веб або апп застосунок
4. Переконайтеся, що в чеку автоматично з'явилася позиція Expirenza Обслуговування з правильною сумою
5. Завершіть оплату
6. Перевірте надходження коштів на розрахунковий рахунок закладу


# Останні зміни

### **Версія #421**

* Додана підтримка отримання винагороди за обслуговування на ФОП для замовлень за столом.
* Додана підтримка типу замовлення "Expirenza" для замовлень за столом.

### Версія #410

* Підтримка отримання винагороди за обслуговування на ФОП

### Версія #406

* Підтримка Syrve API v8

###

### Версія #318

* :warning: Останній мажорне оновлення плагіну для Syrve v7. Далі буде тільки підтримка і виправлення критичних проблем. \
  Закликаємо оновлюватися до Syrve v8 і plugin v.400+ &#x20;
* Додано можливість автоматичної міграції з API v7 на API v8
* Різні дрібні покращення для Syrve API v7

### Версія #293 (24.10.2024)

* Покращення технічної роботи плагіну

### Версія #292 (9.10.2024)

* Покращення технічної роботи плагіну

### Версія #285 (12.08.2024)

* Додали realtime синхронізацію списка офіціантів


# SmartTouch

## Вимоги до програмного забезпечення

Перед налаштуванням інтеграції Expirenza у POS-системі SmartTouch необхідно:

1. Перевірити версію платформи 1С Підприємства.
2. Інтеграція тестувалася на платформі версії 8.3.10.2252 та вище.
3. Рекомендовано оновити безпосередньо SmartTouch до поточної версії.

{% hint style="warning" %}
Платформа 8.2 – не підтримується.
{% endhint %}

***

## Ініціалізація

Необхідно відкрити перейти в меню “Операції/Обробки…” та вибрати пункт “(Службові) Панель отладки”.

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

У вікні, що відкрилося, потрібно перейти на вкладку "Ініціалізація", а потім на вкладену вкладку "Банки"

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

Необхідні для заповнення параметри:

* *“Ідентифікатор ресторану (restoId)*” та “Секретний ключ (Secret)” будуть надіслані на електронну пошту, вказану під час реєстрації облікового запису Expirenza. Також ці дані можна уточнити у вашого акаунт-менеджера Expirenza.

Слід заповнити такі реквізити:

* У полі “*Каса*” необхідно вказати станцію, де закриваються рахунки, тобто. робоче місце касира.
* У полі "*Вид Оплати*" внести вид оплати, на який буде закриватися рахунки через систему Shake to Pay
* Поле "Довідник для категорій" можна вибрати довідники, які будуть вивантажені в обліковий запис Shake to Pay як категорії. На даний момент, доступні для вибору "*Організації*" та "*Категорії страв*".
* Для включення/відключення інтеграції з Expirenza є галочка “*Включити*”.
* Для того, щоб зберегти всі перераховані вище реквізити потрібно натиснути кнопку “*Оновити*”.

Також при натисканні кнопки "*Оновити*" відбудеться наступне:

* Якщо не було заповнено поле "Вигляд оплати" - буде створено новий службовий вид оплати "Shake to Pay (monobank)".&#x20;
* Увімкнеться контроль унікальності числових номерів столів.&#x20;
* Якщо встановлена галочка "Увімкнути" (у поточній версії) здійснюється тестове підключення до Expirenza.

***

## Зв'язок з Expirenza

Після ініціювання кнопкою "*Оновити*" при встановленій галочці "*Включити*" буде спроба встановити канал зв'язку з Expirenza.

За логом, що відображається у вікні повідомлень, можна визначити, чи правильно заповнені параметри “*Ідентифікатор ресторану*” та “*Секретний ключ*”.&#x20;

**При коректному заповненні** можна побачити наступне:

<figure><img src="/files/IkEpZEugwNIHdHJ3AcC7" alt=""><figcaption><p>Коректне заповнення даних</p></figcaption></figure>

**У протилежному випадку** буде:

<figure><img src="/files/V8PWUUZJ1IaiTP7mnd5C" alt=""><figcaption><p>Не коректно заповнені дані</p></figcaption></figure>

Щоб перервати тестове підключення, ініційоване натисканням кнопки “*Оновити*”, слід вийти з програми.

Щоб станція з поля “*Каса*” встановила зв'язок із Expirenza, на ній потрібно перезапустити SmartTouch.

При цьому слід враховувати, що можна встановити лише один канал зв'язку з Expirenza.&#x20;

При спробі встановити одночасне з'єднання з іншою станцією у лозі буде виведено наступне:

<figure><img src="/files/pz7bB2atyrqZot8MgsMn" alt=""><figcaption><p>Помилка, якщо встановлено більше одного коннекту</p></figcaption></figure>

За необхідності лог обміну за останній тиждень можна переглянути у регістрі “*Діалог із зовнішніми системами" (смарт)*.

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

***

## Синхронізація столів

Для синхронізації столів необхідно у картці столу заповнити реквізит “Номер столу” (число)

<figure><img src="/files/aXl8s8cDHuSPRai8k1DF" alt=""><figcaption><p>Картка столу</p></figcaption></figure>

<figure><img src="/files/flT9uKDcJKQp9i2ArBGj" alt=""><figcaption><p>Справочник</p></figcaption></figure>

Експортовані в Expirenza столи можна знайти у розділі “Столи та QR-коди"

<figure><img src="/files/bsBZmLcWRYorl5LRaFVQ" alt=""><figcaption><p>Admin-panel Expirenza</p></figcaption></figure>

***


# BarBoss

## Підключення плагіна Expirenza до BarBo$$

### Ліцензія

{% hint style="info" %}
Робота плагіну можлива з версією BarBo$$ 10 і вище, а також на компʼютерах з Windows 8, або Windows Server 2012.
{% endhint %}

Для роботи з Expirenza необхідно активувати ліцензію `BarBoss Local Connector` , або `BarBoss Server Connector`

Деталі щодо придбання ліцензії можна отримати у вашого менеджера або у [телеграм боті](https://t.me/barbossua_bot) BarBoss.

***

### Встановлення плагіна

{% hint style="info" %}
Здійснювати підключення плагіну Expirenza рекомендовано за допомогою наших спеціалістів
{% endhint %}

1. Завантажте архів з плагіном за посиланням: [barBoss\_lc](https://webterminal.bar-boss.com/Expz.rar)
2. Розпакуйте вміст архіву в теку `D:\BarBoss`
3. Запустіть файл `BarBossExpzService Setup` і проведіть інсталяцію в ту саму теку
4. Перейдіть у теку `D:\BarBoss\Expz` і замініть файл `SetRegestry`, наданий менеджером BarBo$$
5. Запустіть файл `SetRegestry` від імені адміністратора для заміни налаштувань
6. Запустіть додаток служби та запустіть службу `BarBoss Expz`

***

### Нумерація столів

{% hint style="info" %}
Для коректної роботи плагіну Expirenza, переконайтесь, що у вашому закладі всі столи мають унікальний числовий номер.&#x20;

Якщо назва стола містить будь-які символи, окрім цифр, такий стіл не буде завантажено у систему.

Якщо у вас версія нижче 10.3 - зверніться до Вашого менеджеру для налаштування столів.
{% endhint %}

В нових версіях:

* Виберіть пункт меню “Сервіс” → “Параметри системи” → “Налаштування столів”
* За необхідністю змініть назву столів


# SkyService

## Підключення та налаштування

### Вартість

Вартість використання інтеграції SkyService з Expirenza складає 500 грн на місяць.

{% hint style="info" %}
Оплата стягується за підключення плагіна Expirenza до компанії в обліковому записі помісячно.&#x20;

Наприклад, у вас створено дві компанії, перша компанія - ресторана діяльність, друга компанія - кав’ярня.&#x20;

Підключення Expirenza обійдеться для двух компаній обійдеться в 1000 грн на місяць.
{% endhint %}

### Отримання ключа

* Отримайте файл "properties.txt" від аккаунт-менеджера який веде ваш ресторан.
* Або авторизуйтесь в  [адмін-панелі Expirenza](https://admin.expirenza.com):
  * У розділі "Підключення" натисніть "Завантажити ключ" та збережіть його, він ще знадобиться.

## Підключення плагіну Expirenza до SkyService

### Активація плагіну

Для підключення Expirenza виконайте наступні дії:

* Авторизуйтесь у вашому обліковому записі [SkyService](https://auth.skyservice.online/) та оберіть компанію, до якої плануєте підключати плагін Expirenza.
* В панелі адміністрування у лівому кутку натисніть "Мої додатки"
* У спадному меню натисніть "Всі додатки"

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

* У блоці "Expirenza" натисніть “Детальніше”

<figure><img src="/files/52OXKbjavPhKKjto7KEi" alt=""><figcaption></figcaption></figure>

* Натисніть "Додати"

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

У вікні налаштування заповніть наступні поля:

* Активуйте точки та каси, на яких працюватиме Expirenza by mono, для цього вкажіть:
* RESTO\_ID, його можна скопіювати з файлу “properties.txt”, який ми отримали в пункті - [ Отримання ключа](#otrimannya-klyucha).
* SECRET\_KEY, його можна скопіювати з файлу "properties.txt", який ми отримали в пункті -  [Отримання ключа.](#otrimannya-klyucha)

{% hint style="info" %}
Якщо “пташка” не обрана до точки та каси, у POS-терміналі не буде відбуватися підключення до Expirenza.
{% endhint %}

* Натисніть "Додати"

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

## Налаштування столів

### Додавання залів

Додайте розташування залів в **Адмін-панелі SkyService**:

* Відкрийте вкладку "**Налаштування" → "Зал"** і натисніть кнопку "**Додати"**

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

* Вводьте "**Найменування"** і натискаєте "**Додати"**

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

### Додавання столів за кожним залом

* Відкрийте розділ **"Налаштування" → "Столи"**

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

* Виберіть "**Зал"**, для додавання столу на карту – натисніть "**Додати"**
* Виберіть стіл і **перемістіть** , так само введіть "**найменування"**
* Затисніть і потягніть за нижній будь-який кут, щоб **змінити розмір** столу
* Виберете стіл, і натисніть на кошик, щоб видалити стіл
* Натисніть "**Додати"**

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

Відображення столів підключається до **каси**.&#x20;

Тому на одній і тій же точці за різними касами можна працювати відповідно з та без столів. В розділі **Налаштування → Каси** оберіть касу. Та увімкніть столи у блоці **Глобальні параметри**.

<figure><img src="/files/6f3nQxL2ciklFuymdcMX" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Якщо заклад пропонує страви тільки на винос, і не має потреби в столах, вимкніть їх.
{% endhint %}

Для цього перейдіть в розділ "**Налаштування" → "Торгові точки" → Виберіть точку**, і далі в полі "**Столи" оберіть** "**Ні"** і збережіть зміни.

<figure><img src="/files/5alBojKWsyeDwMMDL5Yr" alt=""><figcaption></figcaption></figure>

### Завершення налаштування столів та залів

* Авторизуйтесь в [адмін-панелі Expirenza.](https://admin.expirenza.com)
* Відкрийте розділ "Столи та QR-коди"

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

{% hint style="info" %}
Столи та зали автоматично підтягуються при запуску POS-терміналу в SkyService.

Перегляньте зали та столи, за необхідністю деактивуйте столи до яких не буде закріплена оплата.
{% endhint %}

### Перевірка підключення

Для перевірки підключення до Expirenza by mono, необхідно перейти в POS-термінал або оновити сторінку.

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

<figure><img src="/files/9DG32kXbUiwg4Y9rFT2M" alt=""><figcaption></figcaption></figure>


# TurboPOS

## Вартість

Turbo POS стягує щомісячну плату за використання інтеграції з Expirenza.

Вартість користування складає 300 ₴ на місяць.

## Підключення Expirenza для закладу

Для активації закладу виконайте наступні кроки:

1. Авторизуйтеся в особистому кабінеті за [посиланням](https://app.turbopos.net/login?returnUrl=%2Flogin).
2. В боковому меню оберіть розділ "Налаштування" →  "Інтеграції".
3. Відкрийте налаштування функції Experienza.
4. Активуйте інтеграцію з Expirenza.&#x20;
5. Перенесіть RESTO\_ID та SECRET\_KEY з файлу properties.txt, який раніше отримали від менеджера Expirenza, біля закладу.
6. Натисніть кнопку Підключити.
7. Біля закладу має з’явитися зелений індикатор Підключено.

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

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

Працівники завантажуються автоматично\
\
Для перегляду списку працівників необхідно:&#x20;

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

1. Натиснувши на кнопку Працівники.&#x20;
2. Переконайтесь, що до списку додано всіх співробітників.&#x20;
3. Скорегувати доступ працівників можна за допомогою повзунка біля імені працівника.<br>

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

Якщо у списку відсутній співробітник, додайте їх у налаштуваннях працівників, [згідно інструкції.](https://app.turbopos.net/info-base/article#adding-employee)

Expirenza автоматично імпортує список співробітників із вашої POS-системи.

Це дозволяє співробітникам:

* Отримувати сповіщення про оплату замовлень в Telegram-боті;
* Додати особисту картку для чайових, якщо це передбачено у вашому закладі.

## Нумерація столів

Всі столи повинні мати номери.

Номери столів в залах не повинні повторюватися.

Для перевірки нумерації столів необхідно:

1. В особистому кабінеті відкрийте розділ "Налаштування" →  "Заклади".
2. Відкрийте функцію Карта столів у налаштуваннях закладу.&#x20;

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

Для зміни нумерації столів скористайтеся цією [інструкцією](https://app.turbopos.net/info-base/article#table-map-settings).

## Налаштування терміналу

Для коректної роботи функції Expirenza необхідно виконати "Меню" →  "Синхронізація".

Для налаштування функції Expirenza на POS-терміналі необхідно:&#x20;

1. Авторизуйтеся в системі POS-терміналу.
2. З лівого боку натисніть кнопку "Меню" →  "Expirenza".&#x20;
3. Увімкніть функцію Expirenza.&#x20;
4. Для завантаження функції карти столів натисніть Оновити карту столів.&#x20;
5. Для актуального відображення меню закладу необхідно натиснути кнопку Оновити меню.&#x20;

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


# Інші POS-системи

{% hint style="info" %}
Якщо ваша POS-система відрізняється від представлених у цій документації, зверніться до вашого дилера.
{% endhint %}

Список інших POS-систем з якими Expirenza має інтеграцію:

<table data-view="cards" data-full-width="false"><thead><tr><th></th><th align="center"></th><th></th><th data-hidden data-type="files"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td></td><td align="center"><a href="http://www.pos-trade.com.ua/partners/">LunchPOS</a></td><td></td><td></td><td></td></tr><tr><td></td><td align="center"><a href="http://profit.com.ua">Profit Solutions</a></td><td></td><td></td><td></td></tr><tr><td></td><td align="center"><a href="https://triosoft.kiev.ua/index.html">Trio POS</a></td><td></td><td></td><td></td></tr><tr><td></td><td align="center"><a href="https://serviosoft.com/uk/kontakty">Servio</a></td><td></td><td></td><td></td></tr><tr><td></td><td align="center"><a href="https://rikosoft.com/">LIBRO</a></td><td></td><td></td><td></td></tr></tbody></table>


# Операційна готовність

## 1. Адміністратори

> **Додайте адміністраторів електронного кабінету**

Адміністратор - це користувач електронного кабінету закладу, який може змінювати схему розподілу коштів на рахунки підприємств за категоріями страв і напоїв, управляти чайовими і офіціантами, додавати і видаляти інших адміністраторів, керувати столами та інше.&#x20;

Також, тільки адміністратори можуть скасовувати оплати здійснені з Expirenza та завантажувати звітність.

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

Ви можете додати стільки адміністраторів, скільки побажаєте.
{% endhint %}

> **Як додати адміністратора?**

Щоб додати адміністратора, перейдіть у розділ "Адміністратори" електронного кабінету, натисніть кнопку "Додати адміністратора" у правому нижньому куті, заповніть дані адміністратора.

<figure><img src="/files/v4Zepj363Zf4ulwjnSYv" alt=""><figcaption><p>Додавання адміністраторів ресторану</p></figcaption></figure>

{% hint style="warning" %}
Адміністратор **має бути клієнтом monobank**, тому як для безпечної авторизації в електронному кабінеті закладу ми використовуємо підтвердження входу через мобільний додаток monobank.
{% endhint %}

> **Рівні доступу адміністратора**

Ви можете надати адміністратору електронного кабінету права: додавати, редагувати, видаляти інших адміністраторів.

Для цього на екрані додавання або на екрані редагування даних адміністратора, необхідно активувати опцію "Може додавати, редагувати, видаляти інших адміністраторів".

<figure><img src="/files/jn1PRtzQO7Q8E3lCmZEJ" alt=""><figcaption><p>Надання адміністратору прав</p></figcaption></figure>

***

## 2. Банківські рахунки

> **Налаштуйте розподіл коштів між підприємствами**

У розділі "Банківські рахунки" ви можете налаштувати розподіл коштів від продажу страв та напоїв на рахунки підприємств в залежності від категорії.&#x20;

{% hint style="info" %}
Це особливо зручно, якщо у вашому закладі оплату за бар приймає одне підприємство, а за кухню - інше.
{% endhint %}

Щоб зв'язати категорію з рахунком підприємства, перейдіть у розділ "Банківські рахунки" електронного кабінету.

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

> **Виберіть рахунок за замовчуванням**

У розділі "Банківські рахунки" необхідно вибрати рахунок "за замовчуванням".&#x20;

Якщо, раптом, з’явиться категорія не закріплена за підприємством, або страва без категорії, то кошти від їх продажу перераховуватимуться на “Рахунок за замовчуванням”.

{% hint style="info" %}
Зазвичай, як "Рахунок за замовчуванням" обирають рахунок підприємства, яке приймає оплату за кухню.
{% endhint %}

***

## 3. Чайові

> **Як  працюють чайові?**

Однією з важливих функцій Expirenza є можливість **залишити чайові одночасно з оплатою рахунку**.

Закладу потрібно обрати спосіб збору чайових - збирати на спільну картку і потім ділити, або одразу перераховувати чайові на особисту картку кожному офіціанту окремо.

> **Додайте спільну картку для чайових у розділі "Перснал та чайові"**

Це "спільний кошик" вашої команди.&#x20;

На цю картку перераховуватимуться чайові всієї команди, якщо ви оберете таку опцію. Також, ця картка слугує “планом Б”, на той випадок, якщо хтось із співробітників не додав особисту картку, або під час переказу виникла помилка.

{% hint style="warning" %}
Спільною карткою для чайових має бути картка monobank, бо лише так ми можемо забезпечити безперебійне зарахування коштів.
{% endhint %}

Зазвичай для цього використовують "білу" картку monobank когось з адміністраторів закладу.

> **Оберіть спосіб збору чайових**

Якщо у вашому закладі заведено збирати чайові у "спільний кошик", то нічого робити не треба, чайові будуть зараховуватись на “Спільну картку для чайових”.

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

Якщо ж у вашому закладі кожен офіціант забирає чайові від замовлень, які обслуговував, окремо, то вам потрібно активувати опцію “Переказувати чайові на особисту картку”.

***

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

> **Перевірте список персоналу**

{% hint style="info" %}
Плагін Expirenza автоматично завантажує список персоналу з вашої POS-системи та показує отримані дані у розділі “Персонал та чайові”.
{% endhint %}

Будь ласка, **переконайтесь**, що у списку присутні всі співробітники, які приймають та обслуговують замовлення у вашому закладі. Зазвичай, це офіціанти та бармени.\
\
Якщо у списку персоналу не вистачає когось зі співробітників, [зверніться до цієї інструкції](/features/waiter), щоб дізнатися, як додати їх.

Якщо у списку персоналу є зайві співробітники, ви можете їх деактивувати. Для цього виконайте такі дії:

* Знайдіть у списку персоналу співробітника, якого хочете деактивувати;
* Натисніть кнопку "Деактивувати"

<figure><img src="/files/Nv2owDJndBbr0YGu6VTw" alt=""><figcaption><p>Деактивація персоналу</p></figcaption></figure>

* Співробітника буде деактивовано. Він не зможе отримувати сповіщення в Telegram-бот та чайові на особисту картку.

> **Якщо ви обрали переказувати чайові на особисту картку**

Для підключення карток вашого персоналу до Expirenza перейдіть у розділ "Офіціанти та чайові" електронного кабінету і натисніть "+" навпроти кожного члена команди.

За номером телефону працівника ми відправимо пропозицію додати особисту картку для чайових - у додаток **monobank**, якщо офіціант є клієнтом monobank, або через СМС, якщо ні.&#x20;

{% hint style="info" %}
Ми рекомендуємо заздалегідь попередити команду, що їм може надійти подібне повідомлення.

Офіціанти можуть додати картку для чайових лише Monobank.
{% endhint %}

***

## 5. Сповіщення

> **Як працюють сповіщення?**

Для швидкого інформування ваших співробітників, щодо оплат здійснених з Expirenza та інших важливих подій, ми надсилаємо сповіщення в ПЗ вашого закладу, а також у Telegram-бот.

> **Підключення персоналу до Telegram-бота**

Для підключення потрібно виконати наступні кроки:

* Перейдіть за посиланням <https://t.me/shake2pay_alerts_bot>
* На запит Telegram-бота, поділитись своїм номером телефону.

{% hint style="warning" %}
Наша система налаштована таким чином, що сповіщення надсилатимуться лише на номери телефону адміністраторів і персоналу конкретного закладу.
{% endhint %}

> **Які сповіщення відправляються у ПЗ закладу?**

* Сповіщення про успішну оплату рахунку;
* Сповіщення про помилки закриття замовлень.

> **Які сповіщення відправляються у Telegram-бота?**

* 1\. Сповіщення про успішну оплату рахунку;
* 2\. Сповіщення про помилки закриття замовлень;
* 3\. Сповіщення про повернення оплати;

Також, за допомогою Telegram-бота можна ініціювати повернення оплати.

Повернення оплати можуть ініціювати тільки адміністратори.

***

## 6. Завершення налаштування закладу

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

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


# Тестова оплата

Це останній етап підключення Expirenza

На цьому етапі нам необхідно переконатися, що вся система налаштована і працює правильно:

1. Кошти від продажів зараховуються на правильні банківські рахунки.
2. Чайові переводяться на правильну картку
3. Сповіщення доставляються співробітникам через Telegram-бот
4. Фінансові операції правильно відображені у звітності.

Для завершення етапу "Тестова оплата" виконайте перевірки описані нижче порівнюючи результат з [контрольною анкетою](#4.-zavershennya-nalashtuvannya-zakladu).

***

## 1. Випробуйте повернення оплати

> **Виконайте наступні кроки**

1. У програмному забезпеченні вашого закладу створіть замовлення з будь-якою позицією з меню. Цей рахунок треба буде скасувати, тому рекомендуємо вибрати не фіскальну позицію;
2. Відскануйте QR-код столу, щоб отримати рахунок;
3. Додайте чайові;
4. Сплатіть рахунок;
5. У Telegram-боті натисніть кнопку “Повернути оплату” під сповіщенням про отримання оплати.

{% hint style="warning" %}
Повернути оплату можна лише **протягом 1 години** з моменту її здійснення. Ця функція доступна лише користувачам, яких додано у розділі Адміністратори.
{% endhint %}

6. Знайдіть закритий рахунок у програмному забезпеченні закладу, та виконайте повернення.

{% hint style="warning" %}
Після скасування оплати, переконайтесь, що відповідні зміни було внесено у програмне забезпечення вашого закладу. Наразі, це потрібно робити вручну.
{% endhint %}

***

## 2. Випробуйте успішну оплату

> **Виконайте наступні кроки**

1. У програмному забезпеченні вашого закладу відкрийте рахунок з однією позицією для кожного підприємства, що приймає оплату у вашому закладі (зазвичай, кухня та алкоголь);
2. Відскануйте QR-код, щоб отримати рахунок у додатку monobank;
3. Додайте чайові;
4. Сплатіть рахунок;
5. Дочекайтесь зарахування коштів на відповідні банківські рахунки закладу\*, та чайових на картку офіціанта (або спільну картку закладу).

{% hint style="info" %}
Перерахунок коштів здійснюється одним платежем, близько 8:00 наступного банківського дня.
{% endhint %}

***

## 3. Випробуйте отримання звіту

> **Виконайте наступні кроки**

1. Перейдіть у розділ "Звітність";
2. Виберіть період, коли проводилося випробування;
3. Натисніть кнопку "Отримати звіт" та виберіть “Оплати”.
4. Завантажте таблицю зі звітом та перевірте коректність даних. У звіті має бути, мінімум один запис про повернення оплати і один запис про зарахування коштів для кожного підприємства, що приймає оплату у вашому закладі.

***

## 4. Завершення налаштування закладу

Після того, як будуть проведені всі описані вище перевірки, будь ласка, відправте контрольну анкету і переходьте до наступного етапу - “[Підготовка до запуску](/setup/ready-to-launch)”

{% hint style="success" %}
[Відкрити контрольну анкету](https://forms.gle/92iUwsRFv1A5zHmN8)
{% endhint %}


# Підготовка до запуску

## 1. Підготуйте наліпки з QR-кодами

Найпростіший спосіб для гостя отримати та сплатити свій рахунок - це відсканувати QR-код розміщений на столі.

{% hint style="info" %}
&#x20;Ви можете розробити власний дизайн або використовувати наші макети.
{% endhint %}

Всі необхідні ресурси та інструкції ви знайдете[ **у нашому Медіа Кіт**](https://drive.google.com/drive/folders/1i6kCmQgUXHfh_VQuwU8mxlsvUhJHVR-A)**.**

***

## 2. Надрукуйте наліпки з QR-кодами

Кожен стіл має свій унікальний QR-код для отримання рахунку.&#x20;

Розмістивши відповідний QR-код на столі ви мінімізуєте ризик того, що гість отримає чужий рахунок.&#x20;

Посилання для формування QR-кодів ви можете завантажити у розділі “Столи та рахунки” електронного кабінету закладу.

***

## 3. Проведіть інструктаж персоналу

> "Краще один раз побачити, ніж сто разів почути" - народна мудрість

Ми **рекомендуємо** наочно показати вашим співробітникам, як працює Expirenza. Таким чином, їм буде простіше пристосуватися до нового досвіду.&#x20;

Також, багато корисної інформації [є в інструкції для персоналу](https://drive.google.com/drive/folders/19mXDDctjohf6CnJFzmhV4Hxi8uIdGj9y), щодо роботи з Expirenza.

Після проведення інструктажу переконайтесь, що всі офіціанти, адміністратори та касири підписалися на бота "Expirenza - Сповіщення" у Telegram за цим посиланням:<br>

{% hint style="info" %}
Telegram: <https://t.me/shake2pay_alerts_bot>

Цей бот - найшвидше і найбільш надійне джерело інформації, щодо отриманих оплат для вашого персоналу.
{% endhint %}

***

## 4. Завершення підготовки до запуску

Після виконання всіх попередніх кроків, оберіть бажану дату запуску та заповніть контрольну анкету.

> **Зверніть увагу!** Ми не зможемо погодити запуск на “сьогодні”.&#x20;
>
> Також, ми **не рекомендуємо** призначати запуск на п’ятницю, суботу та неділю.

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


# НБУ та правила

<figure><img src="/files/STLStZWwksFquQh0MiMr" alt="" width="300"><figcaption></figcaption></figure>

## Національний банк України&#x20;

Шановні партнери!

Вас вітає команда **expirenza by monobank**❤️

Дякуємо вам та вашій команді за те, що користуєтеся QR-кодами для прийому оплат, чайових, відгуків та інших сервісів.

Національний банк України оновлює правила роботи з еквайрингом. Відтепер кожен бізнес (ФОП/ТОВ), який приймає карткові платежі, має укласти прямий договір еквайрингу з банком.

Оплата по QR-коду — це також еквайринговий переказ, такий самий, як і через банківський POS-термінал, де у вас є прямий договір з банком.

#### Це означає, що:

* вашому закладу необхідно відкрити рахунок у **monobank**, який надає послугу еквайрингу;
* **саме monobank забезпечуватиме надходження коштів на ваш рахунок**, а за вашою вимогою — переказуватиме їх на рахунки в інших банках;&#x20;
* такі умови є обов’язковими для прийому оплат по QR-коду картками згідно з новими вимогами НБУ.
* **Безкоштовно.** Відкриття та обслуговування рахунку за 0 грн і ніяких комісій за платежі.&#x20;
* **Вигідно.** Якщо на рахунку ТОВ більше 100 000₴, то нараховується 14% річних

👉 **Що потрібно зробити вже зараз:**

* **Відкрити рахунок у monobank.** За вашим бажанням ми можемо активувати функцію автоплатежів на рахунок в іншому банку.

🎯**Термін відкриття рахунків для ТОВ/ФОП — до 15.10.2025.**

**Наша команда готова допомогти вам у цьому процесі:** від підготовки документів і відкриття рахунку — до підключення всіх сервісів. Це дозволить і надалі безперебійно приймати оплати по QR-коду від ваших гостей та користуватися усіма можливостями expirenza by monobank.

Щоб відкрити рахунок, будь ласка, напишіть своєму акаунт-менеджеру або у чат підтримки [@expirenza\_finance\_bot](https://t.me/expirenza_finance_bot)

#### Додаткові матеріали:

* [Текст постанови НБУ](https://bank.gov.ua/admin_uploads/article/proekt_2025-06-03.pdf?utm_source=chatgpt.com)
* [Новина від НБУ](https://bank.gov.ua/ua/news/all/startuye-obgovorennya-zmin-do-poryadku-ekvayringu-platijnih-instrumentiv?utm_source=chatgpt.com)
* [Новина від НБУ №2](https://bank.gov.ua/ua/news/all/viznacheno-klyuchovi-oznaki-zdiysnennya-ekvayringu-ta-poryadok-avtorizatsiyi-i-valyutnogo-litsenzuvannya-uchasnikiv-platijnogo-rinku-scho-yogo-zdiysnyuyut)
* [Затверджена постанова №107 від 28.08.2025](https://bank.gov.ua/ua/legislation/Resolution_28082025_107)
* [Затверджена постанова №103 від 28.08.2025](https://bank.gov.ua/ua/legislation/Resolution_28082025_104)
* [Рахунок юрособи](https://monobank.ua/business-account)
* [Рахунок ФОП](https://monobank.ua/fop)


# Додавання офіціанта

{% content-ref url="/pages/jHuP3zkSEeBXwnAJn0iA" %}
[В Poster](/features/waiter/poster)
{% endcontent-ref %}

{% content-ref url="/pages/bFiSsjhQ62gYDALe8esx" %}
[В Syrve](/features/waiter/syrve)
{% endcontent-ref %}

{% content-ref url="/pages/bLgQz4CUdKEdfDeJRonm" %}
[В r\_keeper](/features/waiter/v-r_keeper)
{% endcontent-ref %}

{% content-ref url="/pages/SVWQex0ycVH81EX1MC74" %}
[В SmartTouch](/features/waiter/v-smarttouch)
{% endcontent-ref %}

{% content-ref url="/pages/P0wweGU3Ifopthoy5hDJ" %}
[B BarBoss](/features/waiter/b-barboss)
{% endcontent-ref %}

{% content-ref url="/pages/xGbWzg1kcP5M4AcQ9ht6" %}
[В SkyService](/features/waiter/skyservice)
{% endcontent-ref %}

{% content-ref url="/pages/ON2kQoWCKlWiaAJz8lI3" %}
[В інші POS-системи](/features/waiter/other)
{% endcontent-ref %}


# В Poster

## Як додати офіціанта?

**Додайте співробітника в Poster**

Система завантажує список персоналу з програмного забезпечення вашого закладу. Щоб додати співробітника, будь ласка, виконайте такі кроки:

1. Авторизуйтесь в адмін-панелі Poster;
2. Додайте нового співробітника вашого закладу у Poster згідно з цією інструкцією: \
   [Інструкція Poster.](https://knowledge-base.joinposter.com/uk-ua/how-to-add-an-employee)
3. Перейдіть у вкладку “Користувачі” плагіна Expirenza by mono \
   (плагін можна знайти у лівому нижньому куті адмін-панелі Poster);<br>

   ![](https://expirenza.monobank.ua/assets/img/poster5.1cb95438.png)
4. Натисніть кнопку “Оновити”, щоб синхронізувати перелік співробітників;
5. Вкажіть номер мобільного телефону співробітника у відповідному полі;
6. Натисніть “Зберегти”;
7. Поверніться у розділ “Персонал та чайові” електронного кабінету закладу та перезавантажте сторінку.

***

## Офіціант не з’явився в електронному кабінеті?

**Пошук і усунення проблем у налаштуваннях персоналу**

1. Переконайтесь, що офіціант раніше не був деактивований в електронному кабінеті закладу:<br>

   <img src="https://expirenza.monobank.ua/assets/img/employee.1ec3df27.png" alt="" width="563">
2. Переконайтесь, що номери телефонів не дублюються. Якщо два або більше співробітників мають однаковий номер телефону, то їхні дані не будуть завантажені у систему.


# В Syrve

## Як додати офіціанта?

> **Додайте співробітника в** Syrve Offic&#x65;**(або** Syrve H&#x51;**)**

Система завантажує список персоналу з програмного забезпечення вашого закладу.&#x20;

Щоб додати співробітника, будь ласка, виконайте такі кроки:

1. Авторизуйтесь у Syrve Office (або Syrve HQ);
2. Виберіть пункт меню "Співробітники" → "Співробітники";
3. Відкрийте особисту картку співробітника;
4. Додайте номер мобільного телефону співробітника у форматі “+380671234567” в поле “Моб.телефон”;
5. Натисніть “Зберегти”;
6. Поверніться у розділ “Персонал та чайові” електронного кабінету закладу та перезавантажте сторінку.

***

## Офіціант не з’явився в електронному кабінеті?

> **Пошук і усунення проблем у налаштуваннях персоналу**

1. Переконайтесь, що офіціант раніше не був деактивований в електронному кабінеті закладу:

<figure><img src="/files/RTE8BDwoj132T34KxMR0" alt=""><figcaption><p>Деактивований персонал</p></figcaption></figure>

2. Переконайтесь, що номер телефону додано саме у поле “Моб.телефон”.
3. Переконайтесь, що на початку номера телефону зазначено код країни: +380\*\*\*\*\*\*\*\*\*\*.
4. Переконайтесь, що номер телефону введений у правильному форматі, **без пробілів** та **спеціальних символів.**
5. Переконайтесь, що номери телефонів не дублюються. Якщо два або більше співробітників мають однаковий номер телефону, то їхні дані не будуть завантажені у систему.
6. Переконайтесь, що Syrve POS увімкнено. Дані завантажуються за допомогою плагіну встановленого на головній станції.
7. Для синхронізації даних між Syrve Office(або Syrve HQ) та Syrve POS, може знадобитись перезавантаження останнього.


# В r\_keeper

## 1. Як додати офіціанта?

> **Додайте співробітника в r\_keeper**

Система завантажує список персоналу з програмного забезпечення вашого закладу. Щоб додати співробітника, будь ласка, виконайте такі кроки:

1. Авторизуйтесь у менеджерській станції r\_keeper;
2. Перейдіть до розділу “Персонал” → “Працівники”;
3. Відкрийте особисту картку працівника;
4. Знайдіть блок "Розширені властивості";
5. Додайте номер мобільного телефону працівника у форматі "+380671234567" у поле "Моб.телефон";
6. Збережіть зміни;
7. Поверніться до розділу "Персонал та чайові" електронного кабінету закладу та перезавантажте сторінку.

***

## 2. Офіціант не з’явився в електронному кабінеті?

> **Пошук і усунення проблем у налаштуваннях персоналу**

1. Переконайтесь, що офіціант раніше не був деактивований в електронному кабінеті закладу:

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

2. Переконайтесь, що номер телефону додано саме у поле “Моб.телефон”.
3. Переконайтесь, що на початку номера телефону зазначено код країни: +380\*\*\*\*\*\*\*\*\*\*.
4. Переконайтесь, що номер телефону введений у правильному форматі, **без пробілів** та **спеціальних символів.**
5. Переконайтесь, що номери телефонів не дублюються. Якщо два або більше співробітників мають однаковий номер телефону, то їхні дані не будуть завантажені у систему.
6. Переконайтесь, що Syrve POS увімкнено. Дані завантажуються за допомогою плагіну встановленого на головній станції.
7. Для синхронізації даних між Syrve Office (або Syrve HQ) та Syrve POS, може знадобитись перезавантаження останнього.

***


# В SmartTouch

Для того, щоб користувач експортувався до Expirenza у його картці необхідно заповнити телефон у форматі `+380XXXXXXXXX`

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

Після оновлення користувач з'явиться в Expirenza у розділі "Персонал та чайові".

<figure><img src="/files/0swCbyN44L7SaEVMXyBa" alt=""><figcaption><p>Доданий офіціант</p></figcaption></figure>


# B BarBoss

Система завантажує дані лише тих працівників, у кого заповнене поле “Моб. телефон”

* Виберіть пункт меню “Довідники” → “Список персоналу”
* Оберіть співробітника і перевірте поле “Телефон”. Якщо воно пусте - необхідно ввести телефон у форматі “+380501234567”

<figure><img src="/files/edjjCw1icRg9p42xfuVS" alt=""><figcaption><p>Додавання персоналу</p></figcaption></figure>


# В SkyService

Інтеграція з плагіном Expirenza дозволяє автоматично завантажити список персоналу зі SkyService.

{% hint style="info" %}
Як додати картку співробітника в SkyService POS ви можете побачити у цьому [уроці](https://support.skyservice.pro/uk/how-to-add-an-employee/).
{% endhint %}

Обов'язково налаштуйте права доступу співробітника до торгової точки, каси та POS-терміналу.

**Під блоком "Персонал" натисніть "Оновити список".**

* &#x20;Якщо співробітник не з'явився, перевірте доступ співробітника, чи активна картка в SkyService POS, та чи прийняв запрошення співробітник у власному кабінеті SkyService.
* Після створення картки співробітника, необхідно перезапустити POS-термінал, при запуску йде підключення до Shake To Pay, та після цього можливо знову оновити список, щоб отримати нові дані.

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

### Офіціант не з’явився в електронному кабінеті?

Пошук і усунення проблем у налаштуваннях персоналу

* Переконайтесь, що офіціант раніше не був деактивований в електронному кабінеті закладу:

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

* Переконайтесь, що надали відповідні права доступу співробітнику.
* Переконайтесь, що картка співробітника активна в ПЗ SkyService.


# В інші POS-системи

{% hint style="info" %}
Якщо ваша POS-система відрізняється від представлених у цій документації, зверніться до вашого дилера.
{% endhint %}

Список інших POS-систем з якими Expirenza має інтеграцію:

<table data-view="cards" data-full-width="false"><thead><tr><th></th><th align="center"></th><th></th></tr></thead><tbody><tr><td></td><td align="center"><a href="https://serviosoft.com/uk/kontakty">Servio</a></td><td></td></tr><tr><td></td><td align="center"><a href="http://www.pos-trade.com.ua/partners/">LunchPOS</a></td><td></td></tr><tr><td></td><td align="center"><a href="http://profit.com.ua">Profit Solutions</a></td><td></td></tr><tr><td></td><td align="center"><a href="https://triosoft.kiev.ua/index.html">Trio POS</a></td><td></td></tr></tbody></table>


# Доставка

Ця сторінка пояснює роботу системи з доставкою та замовленням за столом.

Як працює створення замовлення для гостя:

Гостю необхідно:

* відкрити меню доставки закладу,
* додати страву до кошика,
* вказати спосіб отримання замовлення (доставка / самовивіз),
* вказати адресу (для доставки),
* вказати контактні дані,
* оплатити замовлення

Що бачить гість:

<figure><img src="/files/oeQ9G5hG1YxzEm43FG6u" alt=""><figcaption><p>Гість обирає страву з меню</p></figcaption></figure>

<figure><img src="/files/uVXBCanpFuQPMXGgi0ZQ" alt=""><figcaption><p>Гість залишає дані для доставки і робить оплату</p></figcaption></figure>

<figure><img src="/files/10zSPldk6pJ5TcwsUKUZ" alt=""><figcaption><p>Гість може відслідкувати статус свого замовлення</p></figcaption></figure>

Як виглядає обробка замовлення для закладу:

* Після створення замовлення гостем, воно потрапляє в обробку закладу для підтвердження.
* Підтвердження замовлення може бути виконано за допомогою кнопки в Telegram-боті або  в адмінці ресторану (розділ “Замовлення”).
* Система не створює автоматично замовлення в POS-системі закладу.&#x20;
* У міру готовності замовлення до видачі гостю співробітник закладу оновлює статус замовлення (статуси відображаються клієнту).
* Після видачі замовлення співробітник закладу закриває це замовлення в адмінці ресторану (розділ “Замовлення”).
* Після закриття замовлення ініціюється процес виплати коштів закладу.

Особливості:

* Тип обслуговування працює лише для користувачів меню Expirenza.
* За використання цього типу обслуговування стягується додаткова комісія 1% від вартості замовлення.
* Тип обслуговування не підтримує розподіл коштів згідно з налаштуваннями ресторану ([документація](https://docs.expirenza.com/setup/ops#id-2.-bankivski-rakhunki)). Кошти завжди зараховуються на отримувача за замовчуванням.


# Налаштування  Syrve Office / Syrve HQ

## 1. Налаштування типу оплати

Для підключення послуги Expirenza Delivery, необхідно створити окремий тип оплати. Його налаштування дещо відрізняються від базового типу оплати "Expirenza".

1. Виберіть пункт меню "Роздрібні продажі" → "Типи оплати" і натисніть кнопку "Додати".
2. Заповніть форму наступним чином:&#x20;
   1. В поле "Найменування" введіть “EXPZ Delivery”
   2. У випадаючому списку параметра "Тип" виберіть значення "Банківські картки"
   3. В поле "Назва в чеку" введіть “EXPZ Delivery”
3. Позначте такі опції:
   * Застосовувати для всіх категорій страв
   * Може прийматися ззовні
   * Є фіскальним
4. У випадаючому списку параметра "Проведення оплат" виберіть значення "Як зовнішній, так і на стороні ресторану".
5. Натисніть "Зберегти".

<figure><img src="/files/92EJwczv7n4I7JiMJhoI" alt=""><figcaption><p>Коректно створений тип оплати</p></figcaption></figure>

## 2. Налаштування кур'єрів

{% hint style="warning" %}
Якщо ви плануєте користуватись лише опцією замовлення “З собою” - пропустіть цей пункт.&#x20;

Якщо ж плануєте, також, використовувати опцію замовлення з “Доставкою” - цей пункт **критично важливий для корректної роботи**.
{% endhint %}

Expirenza автоматично завантажує і синхронізує список співробітникив з вашої POS-системи. З-поміж цих співробітників ви зможете призначити курʼєрів.

Expirenza завантажує дані лише тих співробітників, у кого заповнене поле “Моб. телефон”:

1. Виберіть пункт меню "Співробітники" → "Співробітники";

<figure><img src="/files/mCA3hnqbzjYEvG3gY3Om" alt=""><figcaption><p>Список співробітників</p></figcaption></figure>

2. Переконайтеся, що всі ваші курʼєри наявні в списку співробітників;&#x20;
3. Додайте кожному курʼєру номер телефону в форматі "+380673435656" в поле "Моб. телефон" і натисніть "Зберегти".

## 3. Налаштування розділення замовлень на декілька місць друку

Якщо у вашому закладі використовується розділення замовлення на декілька місць друку, переконайтеся, що в Syrve Office/ Syrve HQ налаштування друку відповідають наведеним нижче:

1. Виберіть пункт “Адміністрування” → “Налаштування торгового підприємства”;
2. Виберіть зі списку торгову групу;
3. Перейдіть на вкладку “Загальні налаштування”;
4. У блоці “Загальні налаштування друку” вимкніть опцію “Запитувати касира про розділення замовлення на декілька місць друку”;
5. Натисніть “Зберегти зміни”.

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


# Налаштування r\_keeper

## 1. Додайте нову "валюту"

Для підключення послуги Expirenza Delivery, необхідно створити окремий тип оплати. Його налаштування дещо відрізняються від базового типу оплати "Expirenza".

1. Перейдіть в розділ "Гроші" → "Валюти";
2. У списку виберіть тип "Кредитні карти";
3. Створіть нову валюту;
4. У блоці "Головне" встановіть такі значення:
   1. "Назва" = EXPZ Delivery;
   2. "Статус" = Активний;
5. У блоці "Основне" встановіть такі значення:
   1. "Враховувати в звітах" = 31 Так, крім заліку передоплат;
6. У блоці "Обмеження" включите такі пункти:
   1. Немає в решті;
   2. Без решти;
   3. Повернення страв.
7. Скопіюйте значення з поля "Головне" → "Код" і вставте в параметр "DELIVERY\_PAY\_CODE" в конфігураційному файлі properties.txt

## 2. Налаштування кур'єрів

{% hint style="warning" %}
Якщо ви плануєте користуватись лише опцією замовлення “З собою” - пропустіть цей пункт.&#x20;

Якщо ж плануєте, також, використовувати опцію замовлення з “Доставкою” - цей пункт критично важливий для корректної роботи.
{% endhint %}

Expirenza автоматично завантажує і синхронізує список співробітникив з вашої POS-системи. З-поміж цих співробітників ви зможете призначити курʼєрів.&#x20;

Expirenza завантажує дані лише тих співробітників, у кого заповнене поле “Моб. телефон”:

1. В меню "Персонал" виберіть "Працівники" → "Розширені властивості"&#x20;
2. Переконайтеся, що всі ваші курʼєри наявні в списку співробітників;
3. Додайте кожному курʼєру номер телефону в форматі "+380671112222" в поле "Моб. телефон" і збережіть зміни.

***


# Налаштування Poster

## 1. Налаштування типу оплати

Для підключення послуги Expirenza Delivery, необхідно створити окремий тип оплати. Його налаштування дещо відрізняються від базового типу оплати "Expirenza".

1. У адмін-панелі Poster, перейдіть у розділ "Налаштування" → "Замовлення" → "Методи оплати”.
2. Натисніть кнопку "Додати".
3. Заповніть форму наступним чином:
   1. В поле "Назва методу" введіть “EXPZ Delivery”.
   2. Опцію “Відображати на терміналі” встановіть “Так”.
   3. Опцію “Тип оплати” встановіть “Безготівковий”.
   4. Опціонально, оберіть індивідуальний колір для цього методу оплати.
4. Натисніть "Зберегти".

<figure><img src="/files/ueWFXG9IwDgMx8hOYrpx" alt=""><figcaption><p>Коректно створений тип оплати</p></figcaption></figure>

## 2.Налаштування кур'єрів

{% hint style="warning" %}
Якщо ви плануєте користуватись лише опцією замовлення “З собою” - пропустіть цей пункт.&#x20;

Якщо ж плануєте, також, використовувати опцію замовлення з “Доставкою” - цей пункт критично важливий для корректної роботи.
{% endhint %}

Expirenza автоматично завантажує і синхронізує список співробітникив з вашої POS-системи. З-поміж цих співробітників ви зможете призначити курʼєрів.

Expirenza завантажує дані лише тих співробітників, у кого заповнене поле “Моб. Телефон”:

1. Перейдіть у вкладку “Користувачі” плагіна Expirenza;
2. Переконайтеся, що всі ваші курʼєри наявні в списку співробітників.\
   Якщо у списку відсутній хтось зі співробітників, будь ласка, додайте їх у налаштуваннях Poster, [згідно з цією інструкцією](https://support.joinposter.com/uk/articles/6265476-як-додати-працівника) та натисніть кнопку “Оновити”;
3. Вкажіть для кожного курʼєри їхній номер мобільного телефону у відповідному полі та натисніть “Зберегти”.

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


# Самовивіз

## Що таке "Самовивіз"?

Самовивіз — це функція в мобільному застосунку **Expirenza**, яка дозволяє користувачам замовляти їжу з собою у своїх улюблених закладах.&#x20;

Без черг, зайвих дзвінків і з приємною знижкою від 10% — **ексклюзивно для користувачів застосунку**.

Гість сам обирає час, коли йому зручно забрати страви. А ресторан — готує замовлення і видає його у вказаний проміжок.

Це ідеальний варіант, якщо:

* Після роботи хочеться щось смачненьке, але їсти в залі часу немає
* Хочеться заскочити дорогою додому і захопити улюблений салат або десерт
* В обід треба швидко щось забрати без довгого очікування

{% hint style="info" %}
**Важливо!**&#x20;

Закладу не потрібно створювати меню самостійно.&#x20;

Якщо заклад працює на меню Expirenza, то ми адаптуємо його під потреби ресторану на своєму боці. Наприклад, вимикаємо розділи, яких не має бути на самовивіз.

Якщо заклад працює на меню Choice — ми маємо інтеграцію, яка автоматично передає в Expirenza Самовивіз меню, яким заклад користується на Choice "З собою".
{% endhint %}

## Як це працює для гостя?

1. Гість відкриває застосунок Expirenza
2. Обирає бажаний заклад
3. Додає страви в корзину
4. Підтверджує кількість та чи потрібні прибори до замовлення
5. Оплачує замовлення одразу в застосунку
6. У зазначений час приходить у заклад
7. Показує номер замовлення працівнику
8. Забирає їжу — смачно, швидко, без черг

<figure><img src="/files/ayCyacUKYnCWXerb32de" alt=""><figcaption><p>Вибір закладу та перегляд меню</p></figcaption></figure>

<figure><img src="/files/FDn9SK55I7oMcupwZVEm" alt=""><figcaption><p>Додавання страв в корзину, перегляд корзини</p></figcaption></figure>

<figure><img src="/files/aVDMaAxI8VdrGWIk9Siu" alt=""><figcaption><p>Оформлення замовлення, перегляд статусів замовлення</p></figcaption></figure>

## Як це працює для закладу?

1. Заклад отримує замовлення з деталями в [адмінці ресторану](https://admin.expirenza.com/client/58b668de-2a36-4e9c-a6fc-bf45ab905d69?activeTab=table) в розділі "Замовлення" та в боті @ExpirenzaOrdersBot
2. Підтверджує його
3. Готує до обраного часу
4. Відмічає замовлення як готове
5. У вказаний проміжок гість приходить і показує номер замовлення
6. Працівник звіряє дані й видає замовлення
7. Заклад відмічає замовлення як видан

<figure><img src="/files/Z5MrUWotfGVC8Pwo97f0" alt=""><figcaption><p>Приклад сповіщення про замовлення в @ExpirenzaOrdersBot</p></figcaption></figure>

## Інтеграція з POS-системою

Інтеграція з POS-системою наразі відсутня. Закладу потрібно самостійно проводити таке замовлення в POS-системі.&#x20;

## Тариф "Самовивіз"

Для гостей — знижка від 10% на все замовлення, яку надає ресторан.

Комісія еквайрингу — 1.3%.


# Налаштування Меню і Самовивозу

## Налаштування Меню&#x20;

Для створення меню на платформі Expirenza – [необхідно зайти в особистий кабінет](https://admin.expirenza.com)

Для роботи з меню потрібен розділ «Редактор меню»

<figure><img src="/files/QXVLC8DzVRlKJVcD81pe" alt=""><figcaption><p>Вкладка "Редактор меню" </p></figcaption></figure>

В розділі «Редактор меню» - нам потрібно створити Розділи меню (наприклад, Кухня,Бар ) і&#x20;

Категорії цих розділів (наприклад, у розділі Кухня – Сніданки, Салати, Десерти)

Для створення Розділу в блоці «Розділи меню» натискаємо на кнопку «Змінити»

натискаємо + «Додати розділ» і створюємо всі необхідні нам назви.

<figure><img src="/files/ovdE2EThmA8DIv0YUJ4i" alt=""><figcaption><p>Створення розділу в меню</p></figcaption></figure>

Можемо налаштувати одразу доступність кожного з розділів,&#x20;

або постійно будутьвідображатися в меню, або у певні часові проміжки&#x20;

Наприклад: Бар працює лише з 18 до 22.

<figure><img src="/files/XKsui7rzdqD7a2euY4M2" alt=""><figcaption><p>Зберігаємо зміни</p></figcaption></figure>

Після створення Розділів потрібно для кожного створити необхідні Категорії.

В блоці «Категорії розділу» натискаємо «Змінити» і створюємо так само потрібні нам

назви Категорій.

<figure><img src="/files/wii7tZMgU0BXvML8FHcV" alt=""><figcaption><p>Створюємо категорію в розділі</p></figcaption></figure>

Після того, як ми створили необхідні нам Категорії і Розділи – можемо наповнювати меню позиціями.

Всі позиції підтягуються з Вашої POS-системи.&#x20;

Завдяки цьому не потрібно змінювати вартість в меню, коли вона змінюється в  POS.&#x20;

Щоб побачити всю номенклатуру в редакторі – нам потрібен блок «Номенклатура з POS-системи»

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

Тут натискаємо на три крапочки поруч з написом Номенклатура з POS-системи –&#x20;

і обираємо «Оновити».&#x20;

Таким чином ми затягуємо в «базу» всі позиції, які є в POS-системі.

{% hint style="warning" %}
Коли ми імпортуємо номенклатуру – потрібно, щоб каса була увімкнена, для того щоб успішно завантажити всі позиції.
{% endhint %}

Тепер можемо наповнювати наше меню позиціями.

Щоб додати певну позицію в потрібну нам категорію – шукаємо цю позицію через поле

**пошук**.&#x20;

Наприклад, хочемо наповнити розділ Кухня – в пошук пишемо назву позиції

і з результатів обираємо потрібний нам варіант – натискаємо + щоб додати його в

меню.

В пошуку позиції підписані так само, як і у вас в  POS-системі. Ці назви можна буде

змінювати для меню, яке переглядатимуть гості і ці зміни ніяк не впливатимуть на ті, які

внесені у вас в POS-системі.

<figure><img src="/files/56TpYIvgwlLpXsKZ19OG" alt=""><figcaption><p>Пошук пельменів</p></figcaption></figure>

По натисканню на "+" відкривається «картка» цієї позиції, де ми можемо змінити назву для

перегляду в меню, додати фото і опис.

За потребою, в будь-який момент, позицію можна буде відредагувати – змінити назву, опис чи фото.

І також перенести з одного розділу в інший.

<figure><img src="/files/KHIMhQzeulHkz0zMSSCB" alt=""><figcaption><p>Редагування страви</p></figcaption></figure>

Після редагування «картки» позиції – натискаємо «Зберегти» - і ці зміни протягом 5хв

відобразяться у меню для гостей.

Переглядати меню можна за посиланням, яке знаходиться вгорі сторінки.

<figure><img src="/files/k1jgR7b7O9ZbCW8VmYig" alt=""><figcaption><p>Посилання на меню</p></figcaption></figure>

## Налаштування Самовивозу

Для роботи потрібен розділ «Самовивіз»

<figure><img src="/files/wn3ggPCNV7Soex78Q4bK" alt=""><figcaption><p>Шукаємо розділ </p></figcaption></figure>

{% hint style="warning" %}
Важливо, якщо користуєтеся меню Expirenza – воно обовʼязково має бути створене.
{% endhint %}

Щоб додати необхідні розділи, категорії і позиції – потрібно лише активувати тумблери.

Спочатку Розділи. Натискаємо «Змінити» - і активуємо необхідні розділи.

<figure><img src="/files/552Pf94PThH7i47Q55Kj" alt=""><figcaption></figcaption></figure>

В тих розділах, які ми активували – вмикаємо потрібні нам Категорії.

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

Після того, як активуємо Категорії – в цих категоріях активуємо необхідні позиції, які будуть доступні на Самовивіз.

<figure><img src="/files/cOtKlJlXzCn9DaJRbjoT" alt=""><figcaption><p>Активуємо страву</p></figcaption></figure>

Підтверджуємо активацію позиції

<figure><img src="/files/S30oyyqo0l7dExxkQpbv" alt=""><figcaption><p>Точно активуємо страву</p></figcaption></figure>

Після того, як все меню для Самовивозу буде вірно створене – зверніться будь ласка, до свого аккаунт-менеджера і менеджер активує меню для гостей.


# Розділення рахунку (Split Bill)

{% embed url="<https://www.youtube.com/watch?v=oajlBhCiXXg>" %}

Функціонал доступно за замовчування у POS: Syrve, r\_keeper.\
Для інших POS: Треба додаткова [реалізація](/api/messages/split-bill).

{% hint style="info" %}
У POS-системі Syrve - знижка не буде переноситись з "оригінального" замовлення.
{% endhint %}


# Бронювання столика

{% embed url="<https://www.youtube.com/watch?v=T4dqNmYtxMM>" %}

🎉 Понад 500 000 гостей забронювали столики через expirenza by mono.&#x20;

🥇 Рекорд — 15 340 бронювань на День святого Валентина.

📲 Найчастіше бронюють через лінк на сторінці закладу в Instagram або за посиланням в електронному меню закладу.

💥 Кожне 10-те бронювання — через застосунок Expirenza!

👍Вам доступно понад 40 сучасних функцій для прийому та управління бронюваннями столиків

Для підключення функції зверніться до свого акаунт-менеджера.


# Expirenza Гості (CRM)

## Що таке Expirenza Гості?

Expirenza Гості — це **аналітичний інструмент**, який автоматично формує профілі гостей при оплаті через QR-коди Expirenza, дозволяє вивчати історію їх візитів, сегментувати аудиторію, і в реальному часі надсилати сповіщення персоналу про кожного гостя, який щойно сканував QR-код у закладі.

Головна мета CRM — **допомогти закладам** краще **розуміти своїх гостей**, бачити динаміку відвідувань, смакові вподобання та **ефективніше** працювати з поверненням постійних і залученням нових клієнтів.

Для чого ресторанам ця CRM-система?

* Щоб надсилати сповіщення про гостей офіціантам або хостес з даними для персоналізації обслуговування, в момент сканування QR-коду.
* Щоб бачити реальні дані по кожному гостю, який оплачує через Expirenza.
* Щоб покращити обслуговування за рахунок персоналізації: знати, хто зараз у залі, його ім’я, улюблені страви та історію візитів.
* Щоб аналізувати аудиторію і працювати з базою гостей.
* **Щоб повертати гостей**, які перестали приходити.

## Сповіщення про гостей

Заклад може підключити функціонал Expirenza - Гості, та отримувати сповіщення про гостей та інформацію про них, коли вони сканують QR-код.\
\
У сповіщенні міститься:

* Ім’я гостя (якщо є)
* Базовий сегмент (напр. ⭐ Повторний гість, це означає що гість у вас був декілька разів, але ще не є постійником)
* Середній чек, кількість візитів, улюблені страви
* Останній візит: дата, сума, страви

Прямий лінк на профіль гостя в CRM, де можна лишити коментар, проставити тег або зазначити ім’я гостя.<br>

<figure><img src="/files/3hE5PJamX8mriXhMOtah" alt=""><figcaption><p>Гість вперше у вас в закладі</p></figcaption></figure>

<figure><img src="/files/bieXc2hGd0y1ZFkwJgY0" alt=""><figcaption><p>Гість вже раніше був у вас в закладі</p></figcaption></figure>

Це допомагає офіціантам або хостес одразу орієнтуватися, хто перед ними, і забезпечувати персоналізоване обслуговування — що напряму впливає на лояльність і % чайових.

### Як це працює?

1. Гість сканує QR-код на столику камеру та відкриває посилання у веб-браузері, або в застосунку Expirenza
2. CRM знаходить дані про оплати.
3. Персонал ресторану одразу отримує повідомлення з даними про гостя: ім’я, кількість візитів, середній чек, улюблені страви, чайові тощо.
4. Менеджер ресторану може переглянути повний профіль гостя або всю базу гостей в табличному вигляді.
5. Менеджер може перейти за посиланням в сповіщенні та редагувати профіль гостя: ввести ім’я, теги або лишити коментар.

## Що є в профілі гостя?

<figure><img src="/files/olSF45x2oaqbCV8agxnC" alt=""><figcaption><p>Профіль гостя</p></figcaption></figure>

Станом на зараз, у профілі гостя можна побачити:

* Ім’я (із застосунку, або встановлене вручну)
* Кількість візитів
* Сума витраченого
* Середній чек
* % чайових
* Коментарі та теги, які може залишити команда закладу
* Останній візит: дата, сума, список страв
* Улюблені страви (на основі частоти замовлень)
* Відгуки, якщо гість залишав їх через Expirenza
* Сегменти — базовий: Новий, Повторний, Постійний (рахується на основі к-сті візитів), або вручну створений: Перестав ходити, VIP

{% hint style="success" %}
Дані збираються автоматично — на основі історії оплат, сканувань QR-кодів, відгуків.
{% endhint %}

## Як отримати доступ до перегляду профіля гостя в сповіщенні?

1. Вам необхідно мати роль "**Перегляд профілей гостей**" в адмінці ресторану [admin.expirenza.com<br>](http://admin.expirenza.com)Можна отримати будь-яку іншу роль, але ця роль видає доступ ВИКЛЮЧНО до перегляду профілей гостей, і НЕ дає доступ в адмінку.
2. Для цього необхідно перейти в адмінку в розділ Управління доступами.

<figure><img src="/files/D6DNGIvcGi05kzzATvXh" alt=""><figcaption><p>admin.expirenza.com</p></figcaption></figure>

3. Видати доступ до ролей "Перегляд профілей гостей" (видати може супер-адмін, або ж зверніться до вашого акаунт-менеджера)

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

## База гостей

<figure><img src="/files/iT1hNKkGxNdYxFczSaNw" alt=""><figcaption><p>crm.expiernza.com</p></figcaption></figure>

У CRM є таблиця з усією базою гостей, яку можна:

* створити вручну нові сегменти гостей, наприклад по к-ості візитів, сумі оплат тощо
* сортувати по кількості візитів, середньому чеку, % чайових, даті першого чи останнього візиту
* фільтрувати по базовими (Нові / Повторні / Постійні) та кастомними сегментами або вручну створеним сегментам
* обирати період (наприклад гості, які були за останні 30 днів)
* Перейти в конкретний профіль гостя та переглянути його деталі

### Як отримати доступ до перегляду бази гостей?

1. Вам необхідно мати роль супер-адмін або аналітика гостей в адмінці ресторану [admin.expirenza.com](http://admin.expirenza.com)
2. Для цього необхідно перейти в адмінку в розділ Управління доступами

<figure><img src="/files/D6DNGIvcGi05kzzATvXh" alt=""><figcaption><p>admin.expirenza.com</p></figcaption></figure>

3. Видати доступ до ролей "супер-адмін" або "аналітика гостей" (видати може інший супер-адмін, або ж зверніться до вашого акаунт-менеджера)

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

## Запитання та відповіді

<details>

<summary>Всі відповіді на питання тут</summary>

**Як підключити Expirenza Гості?**

Зверніться до вашого акаунт-менеджера, наразі для тестового використання підключення відбувається вручну.\
\
**Чи можна підключити Expirenza Гості, якщо я не використовую Expirenza для оплат?**\
Ні, аналітика відбувається на основі оплат Expirenza.<br>

**Чи враховуються оплати НЕ через Expirenza?**&#x20;

Ні, враховуються оплати виключно які проходять через Expirenza<br>

**Скільки коштує підключення CRM?**&#x20;

Наразі підключення CRM абсолютно безкоштовне<br>

**Якщо гість повторно відсканував QR-код, я отримаю сповіщення про це вдруге?**\
Ні, система не відправляє інформацію про того самого гостя, якщо сповіщення вже було відправлено за останні 2 години.\
\
**Сповіщення та дані про гостей будуть надходити лише про гостей із застосунку Expirenza?**\
Ні, сповіщення про сканування QR-коду та дані про гостей будуть надходити після відкриття в браузері, так і в застосунку Expirenza.

**Як знайти адмін-панель CRM?**

Вона доступна за посиланням - [crm.expirenza.com](https://crm.expirenza.com)

</details>


# Підвищення оцінки закладу на Google Maps

## 📍 Як залучити більше відгуків у Google через Expirenza?

Після того, як гість залишає гарний відгук в Expirenza, ми можемо автоматично переадресувати його на вашу сторінку в Google Maps, щоб гість продублював гарний відгук і туди.

#### 🔧 Як це працює:

1. Гість залишає оцінку в Expirenza (після оплати або з меню).<br>
2. Якщо він ставить максимальну оцінку (4 з 4):<br>
3. Ми показуємо модальне вікно з пропозицією залишити відгук на Google.<br>
4. При натисканні — відкривається ваша сторінка в Google Maps з пропозицією лишити відгук.<br>
5. Якщо гість написав текстовий коментар у відгуку Expirenza — він автоматично копіюється в буфер обміну, аби відгук можна було швидко вставити в Google.

<figure><img src="/files/QUv4WSqghuli8bI3YAkA" alt="" width="322"><figcaption></figcaption></figure>

## 🎯 Чому це корисно:

* Більше відгуків → вищий рейтинг у Google Maps.<br>
* Без спаму, без окремих QR-кодів.<br>
* Працює і в браузері, і в застосунку Expirenza.<br>

Коментарі копіюються — лишається тільки вставити.<br>

## ❗️Коли не працює:

* Якщо оцінка не максимальна (менше 4 з 4) — переадресація не спрацьовує.<br>
* Якщо заклад не має Google Maps сторінки — немає куди переадрестувати гостя.

## Як підключити функціонал?

Умови для підключення:&#x20;

1. Мати підключені оплати та відгуки **Expirenza**&#x20;
2. Звернутися до вашого акаунт-менеджера **Expirenza** для увімкнення функції


# Замовляй та плати

Функціонал дозволяє гостям замовляти їжу за столиком або в номер самостійно без виклику персоналу закладу.

Як працює створення замовлення для гостя:

Гостю необхідно:

* відсканувати QR-код Expirenza,
* додати страву до кошика,
* вказати бажаний розмір чайових,
* оплатити замовлення.

Що бачить гість:

<figure><img src="/files/e0FSOzE2C4j0rc6wY4Ah" alt=""><figcaption><p>Гість сканує QR у номері або за столом</p></figcaption></figure>

<figure><img src="/files/BOv1FlXxDHJvi8kFV4lT" alt=""><figcaption><p>Гість обирає страву з меню і додає у кошик</p></figcaption></figure>

<figure><img src="/files/anSwbHRcj66k4xL3kkTd" alt=""><figcaption><p>Гість оплачує замовлення і бачить його статус</p></figcaption></figure>

Як виглядає обробка замовлення для закладу:

* Після створення замовлення гостем воно потрапляє в обробку закладу для підтвердження.
* Підтвердження може бути ручним або автоматичним (на вибір закладу).
* Ручне підтвердження виконується за допомогою кнопки в Telegram-боті або в адмінці ресторану (розділ “Замовлення”).
* Після підтвердження система створює замовлення в POS-системі закладу та друкує чек.
* Під час приготування замовлення система відліковує 60 хвилин, протягом яких:
  * Замовлення може бути скасоване закладом із автоматичним поверненням грошей гостю;
  * Замовлення може бути закрите в ручному режимі.
* Через 60 хвилин після створення замовлення в POS-системі замовлення автоматично закривається.
* Після закриття замовлення ініціюється процес виплати коштів закладу.

Особливості:

* Замовлення за столом працює лише для користувачів меню Expirenza.
* Для коректної роботи має бути налаштована інтеграція з POS-системою.([документація](/api/messages/order-from-menu))
* Тип обслуговування підтримує розподіл коштів при оплаті страв з різних категорій меню відповідно до налаштувань ресторану ([документація](https://docs.expirenza.com/setup/ops#id-2.-bankivski-rakhunki)).
* За використання цього типу обслуговування стягується додаткова комісія 1% від вартості замовлення.


# Програма Лояльності

Ваша секретна зброя для завоювання сердець постійних гостей

## Що таке "Програма Лояльності" від Expirenza?

Програма лояльності - функція мобільного застосунку Expirenza ([iOS](https://apps.apple.com/ua/app/expirenza/id6450308718?l=ru) | [Android](https://play.google.com/store/apps/details?id=com.ftband.expz\&hl=uk)), яку може підключити заклад. Кожен ваш гість може отримувати бонуси за свої регулярні відвідування, і все відбувається **автоматично**.

В залежності від потреб, це можливість для ресторану:

в програмі лояльності типу [Штампи](#shtampi) (*10-а чашка кави в подарунок*):

1. Підвищити частоту візитів ваших гостей
2. Створити стимул обрати саме ваш заклад, а не заклад за рогом
3. Підвищити продажі конкретних категорій страв

в програмі лояльності типу [Бінго](#bingo) *(спробуй всі види салатів, отримай подарунок):*

1. Познайомити гостей з вашим асортиментом, щоб вони скуштували різні страви
2. Підвищити продажі позицій, котрі гірше продаються
3. Підвищити продажі нових/сезонних товарів

Не потрібно сканувати картку лояльності, або проставляти штамп, весь облік буде робитися автоматично системою. Клієнт сплачує через застосунок у вашому закладі, система автоматично нараховує мітки по потрібним стравам, і коли всі мітки зібрані — застосовує знижку на винагороду.

***

## Які види програм лояльності доступні в Expirenza?

### ✅ Штампи

<figure><img src="/files/8lUOkhKf4Cq8pp9bt0oP" alt=""><figcaption></figcaption></figure>

Наприклад, "10-та кава безкоштовно".&#x20;

Гості купують визначену кількість акційних товарів, і отримують один у подарунок<mark style="color:red;">\*</mark>.

Більше підходить кав’ярням, де головне - це постійна відвідуванність, і щоб купили каву у вас, а не у кав'ярні за рогом.

### 🎰 Бінго

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

Гості купують всі товари зі списку, щоб отримати випадковий подаруно&#x43A;*<mark style="color:red;">\*</mark>*. Наприклад, спробуй всі види тістечок та отримай випадковий десерт у подаруно&#x43A;*<mark style="color:red;">\*</mark>*.

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

*<mark style="color:red;">\*</mark>Під подарунком мається на увазі купівля позиції за 1 грн.*

***

## Які POS-системи підтримують функціонал?

⚠️На даний момент програму лояльності підтримує лише POS-система Syrve.

* [Посилання на налаштування знижки в Syrve](/setup/pos/syrve/loyalty)

***

## Як це працює в застосунку Expirenza?

* При оплаті в застосунку Expirenza – автоматично нараховуються мітки на акційні товари.
* Коли час настав, і всі мітки зібрано – автоматично застосовується знижка на подаруно&#x43A;*<mark style="color:red;">\*</mark>*.

### Штампи

1. На сторінці вашого закладу в застосунку Expirenza всі користувачі бачать картку програми лояльності з детальним описом умов: скільки міток треба зібрати, умови програми лояльності, та яку нагороду вони отримують.
2. Під час оплати акційних товарів користувачу автоматично нараховуються мітки. Таким чином, він стає учасником програми.
3. Після оплати користувач бачить свій прогрес у програмі лояльності.
4. Коли користувач назбирає достатньо міток, він отримує можливість отримати будь-яку із акційних страв в подаруно&#x43A;*<mark style="color:red;">\*</mark>*. В деталях програми лояльності він бачить як нею скористатися
5. Під час наступного візиту користувач просто замовляє в закладі страву зі спису, на неї система автоматично застосовує знижку, і користувач оплачує товар за 1 грн.

⚠️ Картка закривається, і відкривається нова. Користувач може збирати їх **безлімітну** к-сть разів.

<figure><img src="/files/5AvBV6fCEAfBmo1X2oN1" alt=""><figcaption></figcaption></figure>

### Бінго

1. На сторінці вашого закладу в застосунку Expirenza всі користувачі бачать картку програми лояльності з детальним описом умов: скільки міток треба зібрати, умови програми лояльності, які страви необхідно скуштувати, та яку нагороду вони отримують.
2. Під час оплати акційних товарів користувачу автоматично нараховуються мітки. Таким чином, він стає учасником програми.
3. Після оплати користувач бачить свій прогрес у програмі лояльності, які страви залишилося скуштувати, щоб зібрати Бінго картку.
4. Після оплати останньої мітки, користувач потрапляє на флоу Колеса Фортуни, де він випадковим чином отримує один із п’яти можливих варіантів.
5. Під час наступного візиту користувач просто замовляє в закладі виграну страву, на неї система автоматично застосовує знижку, і користувач оплачує товар за 1 грн.

⚠️ Картка закривається і не перевідкривається, Бінго заповнюється **один раз** за активну компанію.

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

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

***

## Як підключити програму лояльності?

1. Зверніться до вашого акаунт-менеджера та переконайтесь, що програма доступна для вашого закладу.
2. Налаштуйте знижки у вашій POS-системі відповідно до [інструкції](https://docs.expirenza.com/~/changes/uP2oT6e3rzmprFY91HZV/resto-connect/pos/syrve/loyalty)
3. Оберіть тип програми лояльності (Штампи чи Бінго)
4. Визначте умови програмі лояльності разом з аккаунт-менеджером. \
   (Строки накопичення міток, винагороди, страви які прийматимуть участь і т.п)

***

## Як гості дізнаються про програму лояльності?

**Expirenza** подбає про це: після підключення програми лояльності при оплаті через браузер, користувач побачить банер із пропозицією завантажити застосунок **Expirenza**.&#x20;

Користувачу одразу нарахуються мітки, якщо в рахунку були страви, які приймають участь у вашій програмі лояльності.<br>

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

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

***

## F.A.Q

<details>

<summary>Чи працює програма лояльності по всій мережі закладів?</summary>

На даний момент **ні**. Програма лояльності налаштовується індивідуально для кожного закладу, і не підтримує одразу цілу мережу закладів.

</details>

<details>

<summary>Який тариф на програму лояльності?</summary>

Програма лояльності наразі надається повністю безкоштовно, лише витрати на знижку на акційні позиції. Вам необхідно налаштувати Програму Лояльності у вашій POS-системі, та через акаунт-менеджера.

</details>

<details>

<summary>Що робити, якщо моя POS-система не підтримує програму лояльності?</summary>

Якщо ваш заклад зацікавлений у програмі лояльності, але вашу POS-систему ми не підтримуємо, заповніть форму[ за посиланням](https://forms.gle/FZ8teKBQwMbBNTo66). Ми розглянемо можливість додати підтримку вашої POS-системи.

[Які POS-системи підтримуються](#yaki-pos-sistemi-pidtrimuyut-funkcional)?

</details>

<details>

<summary>Чи можна підключити програму лояльності без меню Expirenza?</summary>

Ні, за виключенням меню **Choice**, яке інтегрується з нашим застосунком. У такому разі програма лояльності буде працювати так само як і з нашим меню, але варто проконсультуватися з вашим акаунт-менеджером.

</details>

<details>

<summary>Чи можна мати декілька програм лояльності одночасно?</summary>

Ні. Наразі доступна лише одна активна програма лояльності.

</details>


# Таємні Бокси

## Що таке "Таємні Бокси"?

Таємні бокси — це сервіс в мобільному застосунку Expirenza, який дозволяє користувачам купувати їжу в закладах по спеціальним цінам, яку заклади не встигли розпродати до кінця дня.&#x20;

Сама сутність називається «таємні бокси», тому що користувач не знає яка саме їжа йому дістанеться. Для прикладу, купуючи таємний бокс в Milk Bar, гість може за умовні - 149 грн. отримати різної випічки та десертів на припустимо -  400 грн.&#x20;

Ресторан може створити таку пропозицію за потреби, вона зʼявляється в мобільному застосунку Expirenza та доступна усім авторизованим користувачам додатку. Пропозиції обмежені в кількості.

Кількість таємних боксів вказує сам заклад.

{% hint style="info" %}
**Важливо!** Таємні бокси можна забирати лише в спеціально визначений для цього час. Цей час встановлює заклад, коли створює пропозицію.
{% endhint %}

Сценарії використання для гостей:

1. Іду з роботи, хочеться щось перекусити, бачу в застосунку Expirenza, що в Musafir лишилось 3 таємних бокси, в яких може бути плов, печені овочі та янтики. Бронюю та захоплю перед поїздкою додому.
2. Хочу випічку в Спельті, але там дорого. Зайшов в апку, забронював бокс, увечері заскочу та спробую те що дадуть за класну ціну.
3. Приїхав в Київ, в столиці все дорого, захожу в апку подивитись де можна урвати бокс по класній ціні.

## Як це працює?

1. Користувач обирає пропозицію з таємними боксами в закладі, який йому подобається
2. Бронює бокс (одразу оплачує) собі на вечір. Часовий проміжок для видачі боксів заклад вказав з 20:00 до 20:45
3. У 20:30 гість приходить у заклад
4. Показує офіціанту або касиру номер замовлення з додатку Expirenza
5. Працівник закладу звіряє номер та збирає бокс смаколиків для гостя
6. Віддає гостю бокс зі смаколиками

## Покупка “Таємних боксів”

**Як покупка "Таємних боксів" виглядає у застосунку Expirenza?**

1. Користувач відкриває застосунок Expirenza.
2. На головному екрані список активних пропозицій від закладів.
3. Користувач натискає на картку Namelaka.
4. Користувач ознайомлюється з деталями пропозиції.
5. Натискає «Оплатити та зарезервувати»
6. Вікдривається екран оплати
7. Користувач сплачує замовлення

<figure><img src="/files/XIyiVDhwmcxKttkKHrR0" alt=""><figcaption><p>Cплачуємо таємний бокс</p></figcaption></figure>

<figure><img src="/files/237t6v55Ac51joDOtJD9" alt=""><figcaption><p>Отримуємо бокс (цей код замовлення не дійсний :)</p></figcaption></figure>

## **Як покупка "Таємних боксів" проводиться в POS-системі закладу?**

При покупці боксів, дані в POS-систему не відправляються.

### Підключення у POS-системі

Для підключення функції  "Таємні бокси" додаткові налаштування в POS-системі не потрібні.

## Отримання “Таємного боксу”

### **Як отримання "Таємного боксу" виглядає у застосунку Expirenza?**

1. Гість (отримувач) приходить у заклад
2. Знаходить касира або іншого працівника закладу
3. Каже, що він за замовленням таємного боксу
4. Диктує або показує працівнику номер замовлення в додатку Expirenza
5. Працівник звіряє номер у себе в системі та видає бокс гостю.

<figure><img src="/files/EpaDsj6QSDzXc9V2cM03" alt=""><figcaption><p>Показуємо код для отримання боксу в ресторані</p></figcaption></figure>

## Тариф "Таємні бокси"

Жодна комісія за функцію "Таємні бокси" відсутня.

***

<details>

<summary>Запитання та відповіді</summary>

***Як ресторану отримати кошти за таємні бокси?***\
Регламент виплат нічим не відрізняється від виплат по основним замовленням.

***Чи будуть окремі звіти по виплатам?***\
У розділі звітів зʼявиться додатковий звіт по оплатам.

***Як закривається замовлення в POS-системі?***\
Ніяк. Наповнення таємного боксу знає тільки заклад. Створювати та закривати замовлення повинен співробітник закладу під час видачі боксів.&#x20;

***Як відбувається видача боксів?***\
Гість приходить у заклад, показує код замовлення співробітнику, далі працівник закладу перевіряє, що замовлення з таким кодом ще не було видано, пробиває наповнення боксу в POS-системі та видає бокс гостю.

***Чи можна запустити продаж таємних боксів, якщо заклад працює без інтеграції Expirenza з POS-системою?***

Так, можна.

***Чи можна запустити продаж таємних боксів, якщо заклад не підключений до Expirenza?***

Поки що ні, але ми вже працюємо в цьому напрямку. Слідкуйте за новинами:&#x20;

[Наш інстаграм](https://www.instagram.com/expirenza_by_mono/?hl=en)&#x20;

[Телеграм](https://t.me/expirenza_by_mono)

</details>


# Бойові

Це, як чайові, тільки чайові - це вдячність за сервіс, а бойові - це вдячність за життя.

## Що таке "Бойові"?

**Бойові** -  це функція, яка дозволяє гостям закладу залишити **бойовий донат** **для ЗСУ**  у ресторанах-партнерах, які встановили відповідну банку для збору.

{% hint style="info" %}
Відправте лінк на банку вашому акаунт-менеджеру expirenza by mono ❤️
{% endhint %}

## Як це працює?&#x20;

Після екрану чайових гість закладу побачить екран, який пропонує йому зробити бойовий донат. Після оплати рахунку обрана сума бойових перераховується на Банку.

## Як це виглядає?

### Рахунок та чайові

<div><figure><img src="/files/rLOmdeloKx8vmwPpDF8N" alt=""><figcaption><p>Плануємо сплату рахунку</p></figcaption></figure> <figure><img src="/files/T9xLs21pHVkVtJXRlKO4" alt=""><figcaption><p>Обираємо чайові</p></figcaption></figure> <figure><img src="/files/P7xh6QmzwttRHKZsXv25" alt=""><figcaption><p>Обрали чайові</p></figcaption></figure></div>

### Бойові

<div><figure><img src="/files/WXHTI0V6531VIkiv6LxQ" alt=""><figcaption><p>Обираємо суму бойових</p></figcaption></figure> <figure><img src="/files/VRTHUWKGl0eipRSfMq7W" alt=""><figcaption><p>Сплачуємо рахунок</p></figcaption></figure> <figure><img src="/files/0h4s3reKl7kJ03NttSA8" alt=""><figcaption><p>Рахунок сплачено, бойові відправлено на банку збору</p></figcaption></figure></div>


# Частування

## Що таке "Частування"?

**Частування** - це функція мобільного застосунку Expirenza, яка дозволяє користувачам пригощати один одного у вашому закладі.&#x20;

Тобто, ваші ж гості створюватимуть для вас додатковий потік відвідувачів. Бо, отримане "Частування" - це привід для людини завітати до вас, щоб використати подарунок і, обовʼязково, замовити щось іще.&#x20;

**Сценарії використання для гостей:**

{% hint style="info" %}

1. Хлопець робить своїй дівчині маленький сюрприз, купуючи десерт та каву в її улюбленій кавʼярні за рогом
2. Донька, що живе за кордоном, пригощає батьків вечерею у гарному ресторані на їхню річниц
3. Один друг купує іншому пиво, бо програв спір, щодо майбутнього фіналіста Ліги Чемпіонів
   {% endhint %}

## Як це працює?

1. Покупець обирає і оплачує Частування  що полюбилося для свого друга в закладі
2. Отримувач приходить в зручний день скуштувати смаколик
3. Під час оплати система віднімає вартість Частування з чека і закриває рахунок на суму замовлення
4. Після закриття рахунку вартість Частування буде виплачена закладу.

Все просто та прозоро!

Термін дії “Частування” складає 90 днів. Після чого, отримувач вже не зможе використати “Частування” для оплати замовлення.

### Покупка “Частування”:

#### **Як покупка "Частування" виглядає у застосунку Expirenza?**

1. Покупець, у мобільному застосунку Expirenza обирає заклад та позицію меню (це може бути будь-яка страва з меню Expirenza, яка синхронізована з номенклатурою ресторану)
2. Покупець вказує номер телефону людини, яку хоче пригостити;
3. Покупець підтверджує та оплачує "Частування";
4. Expirenza відправляє “Частування” отримувачу за номером телефону;
5. Кошти виплачуються на банківський рахунок вашого закладу пiсля використання Частування отримувачем.

<figure><img src="/files/kiqGBD5YRq7HP2SbAVq0" alt=""><figcaption><p>Покупка "Частування"</p></figcaption></figure>

#### Як покупка "Частування" проводиться в POS-системі закладу?

При покупці частування, дані в POS-систему не відправляються.

### Отримання “Частування”

#### **Як отримання "Частування" виглядає у застосунку Expirenza?**

1. Гість (отримувач "Частування") приходить у заклад;
2. Робить замовлення офіціанту: Наполеон (160 грн) та Лате (80 грн)
3. Гість переходить до розрахунку, в мобільному застосунку Expirenza;
4. Система автоматично віднімає вартість "Частування" із суми до сплати;
5. Гість оплачує замовлення та йде задоволеним.

<figure><img src="/files/nANCCc3fJo1UPtT3YYlM" alt=""><figcaption><p>Отримання "Частування"</p></figcaption></figure>

#### Як отримання "Частування" проводиться в POS-системі закладу?

1. Гість оплачує замовлення у ресторані, при цьому:
2. Expirenza віднімає із суми до оплати вартість частування.
3. Expirenza закриває у POS-системі замовлення на повну вартість (включаючи актуальну вартість частування)
4. POS-система друкує звичайний фіскальний чек на повну вартість замовлення (включаючи актуальну вартість частування)

## Тариф "Частування"

**Додаткові комісії на функцюї "Частування" відсутні**

## Підключення та налаштування

### Підключення у POS-системі

Для підключення функції "Частування" додаткові налаштування в POS-системі не потрібні.

<details>

<summary>Відповіді на часті запитання (F.A.Q.)</summary>

**Як відбувається покупка частування через застосунок Expirenza?** \
Частування доступне користувачам мобільного застосунку Expirenza. Передусім, це страви, які відображаються в застосунку завдяки електронному меню. Якщо у вашому закладі використовується електронне меню від Expirenza, то такі страви вже синхронізовані з вашою POS-системою автоматично, що означає, що гості зможуть купити та відправити частування через застосунок Expirenza.

**А якщо у мене електронне меню від іншого сервісу, наприклад, Choice?** \
Це не проблема, між Expirenza та Choice існує інтеграція, за якою страви з електронного меню Choice передаються в застосунку Expirenza. Головне, щоб ваші страви з POS-системи були синхронізовані з меню Choice. Якщо такої синхронізації немає, то покупка частування недоступна у вашому закладі. Радимо звернутися до команди Choice або до команди Expirenza.

**Якщо страва додана у стоп-лист, чи може її придбати гість?** \
У застосунку Expirenza відображаються тільки активні страви. Якщо страва додана у стоп-лист або деактивована у вашому електронному меню, то така страва не відображається в застосунку Expirenza і недоступна для покупки.\
\
**Наприклад, у березні гість купує та дарує частування своїй подрузі. Забрати частування вирішили у квітні, ціна на таку страву вже змінилася.** \
Ні, в момент використання частування враховуватиметься актуальна вартість.

**Добре, а якщо дівчина прийшла за частуванням, а такої страви вже немає у нашому меню? Ми часто змінюємо меню, тому це типова ситуація.** \
Ми часто змінюємо меню, тому це типова ситуація.&#x20;

Коли таке трапиться, дівчина може в застосунку Expirenza замінити страву Частування на іншу страву (з тією ж вартістю або нижче)

**Як одержувач дізнається, що хтось пригостив його?** \
Одержувач частування отримує повідомлення у вигляді SMS (якщо він ще не користувач застосунку Expirenza) або PUSH-повідомлення в застосунку Expirenza. На отримання частування у отримувача є 90 днів.

</details>

***


# Підтримка POS-систем

Ця сторінка описує який функціонал Expirenza підтримується кожною із POS-систем

<table data-full-width="true"><thead><tr><th width="346">Функціональність Expirenza</th><th width="80">Poster<select><option value="ch7RYgUmvEFP" label="Реалізовано" color="blue"></option><option value="gOqOcsT36dCl" label="Відсутнє" color="blue"></option><option value="eOCJNlLVa8bq" label="Poster" color="blue"></option><option value="VmZqThARWFs4" label="✅" color="blue"></option><option value="5d3zSkq9uskK" label="🚫" color="blue"></option><option value="5BUwN2oaNgeG" label="⏳" color="blue"></option></select></th><th width="101">R-keeper<select><option value="SgBoaQy9M6Ns" label="R-keeper" color="blue"></option><option value="SfIgWPfz2qcw" label="Реалізовано" color="blue"></option><option value="xHQY3CjJUDbM" label="Відсутнє" color="blue"></option><option value="pboGZcWVxjmK" label="✅" color="blue"></option><option value="vVURSoLaqxCp" label="🚫" color="blue"></option></select></th><th width="69">Syrve<select><option value="dNkB9HSn96NQ" label="Syrve" color="blue"></option><option value="eSCiSbtLfZZ0" label="Реалізовано" color="blue"></option><option value="2JqrhCe2ko4V" label="Відсутнє" color="blue"></option><option value="qUiQBeaHmDBN" label="🚫" color="blue"></option><option value="pZEtL18wdEzh" label="✅" color="blue"></option></select></th><th width="82">Servio<select><option value="wCoYMzFQFR06" label="Servio" color="blue"></option><option value="qKFHlnn6cGK3" label="Реалізовано" color="blue"></option><option value="i82LsRibEN6q" label="Відсутнє" color="blue"></option><option value="sA1oEfGrtz8d" label="✅" color="blue"></option><option value="4Oz3Zet96TWB" label="🚫" color="blue"></option></select></th><th>SmartTouchPOS<select><option value="J4nZ8IYRC4kK" label="SmartTouchPOS" color="blue"></option><option value="O7Zo57H5BbQG" label="Реалізовано" color="blue"></option><option value="6LtkL8htClWq" label="Відсутнє" color="blue"></option><option value="L4cslmItZGm7" label="✅" color="blue"></option><option value="jIm2wfkuW4Ff" label="🚫" color="blue"></option></select></th></tr></thead><tbody><tr><td><strong>Замовлення та оплата</strong></td><td></td><td></td><td></td><td></td><td></td></tr><tr><td>Оплата по QR-коду на столі</td><td><span data-option="VmZqThARWFs4">✅</span></td><td><span data-option="pboGZcWVxjmK">✅</span></td><td><span data-option="pZEtL18wdEzh">✅</span></td><td><span data-option="sA1oEfGrtz8d">✅</span></td><td><span data-option="L4cslmItZGm7">✅</span></td></tr><tr><td>Друк платіжного QR на Пречек</td><td><span data-option="VmZqThARWFs4">✅</span></td><td><span data-option="pboGZcWVxjmK">✅</span></td><td><span data-option="pZEtL18wdEzh">✅</span></td><td><span data-option="sA1oEfGrtz8d">✅</span></td><td><span data-option="L4cslmItZGm7">✅</span></td></tr><tr><td>Розділення рахунку</td><td><span data-option="5d3zSkq9uskK">🚫</span></td><td><span data-option="pboGZcWVxjmK">✅</span></td><td><span data-option="pZEtL18wdEzh">✅</span></td><td><span data-option="sA1oEfGrtz8d">✅</span></td><td><span data-option="jIm2wfkuW4Ff">🚫</span></td></tr><tr><td><strong>Меню</strong> </td><td></td><td></td><td></td><td></td><td></td></tr><tr><td>Синхронізація страв с POS</td><td><span data-option="VmZqThARWFs4">✅</span></td><td><span data-option="pboGZcWVxjmK">✅</span></td><td><span data-option="pZEtL18wdEzh">✅</span></td><td><span data-option="sA1oEfGrtz8d">✅</span></td><td><span data-option="L4cslmItZGm7">✅</span></td></tr><tr><td>Модифікатори Страв</td><td><span data-option="VmZqThARWFs4">✅</span></td><td><span data-option="pboGZcWVxjmK">✅</span></td><td><span data-option="pZEtL18wdEzh">✅</span></td><td><span data-option="4Oz3Zet96TWB">🚫</span></td><td><span data-option="L4cslmItZGm7">✅</span></td></tr><tr><td>Стоп-лісти</td><td><span data-option="VmZqThARWFs4">✅</span></td><td><span data-option="pboGZcWVxjmK">✅</span></td><td><span data-option="pZEtL18wdEzh">✅</span></td><td><span data-option="4Oz3Zet96TWB">🚫</span></td><td><span data-option="jIm2wfkuW4Ff">🚫</span></td></tr><tr><td>Оцінка страв</td><td><span data-option="VmZqThARWFs4">✅</span></td><td><span data-option="pboGZcWVxjmK">✅</span></td><td><span data-option="pZEtL18wdEzh">✅</span></td><td><span data-option="sA1oEfGrtz8d">✅</span></td><td><span data-option="L4cslmItZGm7">✅</span></td></tr><tr><td><a href="/pages/25BEwV4uwut7yjlVHdXn"><strong>Room Service</strong></a> <strong>/ Food-Court</strong></td><td><span data-option="5d3zSkq9uskK">🚫</span></td><td><span data-option="pboGZcWVxjmK">✅</span></td><td><span data-option="pZEtL18wdEzh">✅</span></td><td><span data-option="4Oz3Zet96TWB">🚫</span></td><td><span data-option="jIm2wfkuW4Ff">🚫</span></td></tr><tr><td><a href="/pages/MOkcTOzkGEpLSZfnwWiZ"><strong>Частування</strong></a></td><td><span data-option="VmZqThARWFs4">✅</span></td><td><span data-option="vVURSoLaqxCp">🚫</span></td><td><span data-option="pZEtL18wdEzh">✅</span></td><td><span data-option="4Oz3Zet96TWB">🚫</span></td><td><span data-option="jIm2wfkuW4Ff">🚫</span></td></tr></tbody></table>

<table data-full-width="true"><thead><tr><th width="346">Функціональність Expirenza</th><th width="92">BarBoss</th><th width="88">LunchPOS<select><option value="qVrxV6n3aVvj" label="Реалізовано" color="blue"></option><option value="2YJ7xJ4ceMoT" label="Відсутнє" color="blue"></option><option value="Utm3XMTu3aAx" label="✅" color="blue"></option><option value="gNzoIhe3wj8L" label="🚫" color="blue"></option></select></th><th width="79">Profit Solutions<select><option value="C3irDF8MqUrP" label="Реалізовано" color="blue"></option><option value="FSeFotBWRXpv" label="Відсутнє" color="blue"></option><option value="r61a2nRjZjN9" label="Profit Solutions" color="blue"></option><option value="MVfcaCFUR7xl" label="✅" color="blue"></option><option value="fkiuncCwI9hV" label="🚫" color="blue"></option></select></th><th width="85">SkyServicePOS<select><option value="9utumAsIcsdv" label="SkyServicePOS" color="blue"></option><option value="gL21s2D71wLc" label="Реалізовано" color="blue"></option><option value="KWgvp9lpxM4a" label="Відсутнє" color="blue"></option><option value="Bs3eh3XQx3gg" label="✅" color="blue"></option><option value="1LuVxpEGftFD" label="🚫" color="blue"></option></select></th><th>TRIO<select><option value="ma1vdusWgaNi" label="✅" color="blue"></option><option value="iviVFit4ZisW" label="🚫" color="blue"></option></select></th></tr></thead><tbody><tr><td><strong>Замовлення та оплата</strong></td><td></td><td></td><td></td><td></td><td></td></tr><tr><td>Оплата по QR-коду на столі</td><td>✅</td><td><span data-option="Utm3XMTu3aAx">✅</span></td><td><span data-option="MVfcaCFUR7xl">✅</span></td><td><span data-option="Bs3eh3XQx3gg">✅</span></td><td><span data-option="ma1vdusWgaNi">✅</span></td></tr><tr><td>Друк платіжного QR на Пречек</td><td>✅</td><td><span data-option="gNzoIhe3wj8L">🚫</span></td><td><span data-option="fkiuncCwI9hV">🚫</span></td><td><span data-option="Bs3eh3XQx3gg">✅</span></td><td><span data-option="iviVFit4ZisW">🚫</span></td></tr><tr><td>Розділення рахунку</td><td>🚫</td><td><span data-option="Utm3XMTu3aAx">✅</span></td><td><span data-option="MVfcaCFUR7xl">✅</span></td><td><span data-option="1LuVxpEGftFD">🚫</span></td><td><span data-option="iviVFit4ZisW">🚫</span></td></tr><tr><td><strong>Меню</strong> </td><td></td><td></td><td></td><td></td><td></td></tr><tr><td>Синхронізація страв с POS</td><td>✅</td><td><span data-option="Utm3XMTu3aAx">✅</span></td><td><span data-option="MVfcaCFUR7xl">✅</span></td><td><span data-option="Bs3eh3XQx3gg">✅</span></td><td><span data-option="ma1vdusWgaNi">✅</span></td></tr><tr><td>Модифікатори Страв</td><td>✅</td><td><span data-option="gNzoIhe3wj8L">🚫</span></td><td><span data-option="MVfcaCFUR7xl">✅</span></td><td><span data-option="Bs3eh3XQx3gg">✅</span></td><td><span data-option="iviVFit4ZisW">🚫</span></td></tr><tr><td>Стоп-лісти</td><td>🚫</td><td><span data-option="gNzoIhe3wj8L">🚫</span></td><td><span data-option="MVfcaCFUR7xl">✅</span></td><td><span data-option="1LuVxpEGftFD">🚫</span></td><td><span data-option="ma1vdusWgaNi">✅</span></td></tr><tr><td>Оцінка страв</td><td>✅</td><td><span data-option="Utm3XMTu3aAx">✅</span></td><td><span data-option="fkiuncCwI9hV">🚫</span></td><td><span data-option="Bs3eh3XQx3gg">✅</span></td><td><span data-option="ma1vdusWgaNi">✅</span></td></tr><tr><td><a href="/pages/25BEwV4uwut7yjlVHdXn"><strong>Room Service</strong></a> <strong>/ Food-Court</strong></td><td>🚫</td><td><span data-option="gNzoIhe3wj8L">🚫</span></td><td><span data-option="fkiuncCwI9hV">🚫</span></td><td><span data-option="1LuVxpEGftFD">🚫</span></td><td><span data-option="iviVFit4ZisW">🚫</span></td></tr><tr><td><a href="/pages/MOkcTOzkGEpLSZfnwWiZ"><strong>Частування</strong></a></td><td>🚫</td><td><span data-option="Utm3XMTu3aAx">✅</span></td><td><span data-option="fkiuncCwI9hV">🚫</span></td><td><span data-option="1LuVxpEGftFD">🚫</span></td><td><span data-option="iviVFit4ZisW">🚫</span></td></tr></tbody></table>

<br>


# API для інших POS-систем


# Інтеграція нових POS-систем

Використовуючи цей план, ви зможете максимально швидко інтегрувати Expirenza у свою POS-систему.&#x20;

{% content-ref url="/pages/IQ29MK9cJhSL2BeTcdH5" %}
[Підготовка до інтеграції](/api/integration/prepare)
{% endcontent-ref %}

{% content-ref url="/pages/UHITaE0ynnbpShwBaenf" %}
[Технічна інтеграція](/api/integration/techplan)
{% endcontent-ref %}

{% content-ref url="/pages/JzlCeCM3FZT5peuYLqPZ" %}
[Тестування технічної інтеграції](/api/integration/finishing)
{% endcontent-ref %}

***


# Підготовка до інтеграції

## З чого почати?

Перший крок для початку інтеграції - це заповнити анкету та познайомитись з нами. \
Ми розглянемо анкету і зв'яжемось з вами для обговорення деталей інтеграції.

{% hint style="success" %}
[Анкета](https://docs.google.com/forms/d/e/1FAIpQLSegXbHggWFJipjpPOyEqS2kMF5vp_itJ34R5hX8S6ai-kUTiQ/viewform)
{% endhint %}

***

## Наступний крок

Після знайомства ми:

1. Створимо для вас тестовий ресторан
2. Надамо облікові дані для доступу в [Expirenza admin-panel](https://admin.expirenza.com)
3. Надамо файл з ключами до **API Expirenza** \
   (properties.txt - цей файл також доступний в Адмін панелі) &#x20;

Файл має наступний вигляд:&#x20;

```
RESTO_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
SECRET_KEY=***
```

Після цього відбувається [етап технічної інтеграції](/api/integration/techplan).

{% hint style="info" %}
На протязі інтеграції (і після) ми будемо мати з вами окремий чат, у якому ви зможете ставити питання стосовно інтеграції та нашого API.
{% endhint %}


# Технічна інтеграція

Ця сторінка допоможе вам не загубитись на етапі інтеграції, допоможе розставити пріоритети та виділить основні команди, які треба реалізувати для максимально швидкої інтеграції вашої POS-системи з Expirenza.&#x20;

***

## Технічне підключення

Ми створили для вас список за яким можна реалізовувати команди, не обов'язково дотримуватись послідовності.

{% hint style="info" %}
&#x20;🔅 - позначає обов'язковість.
{% endhint %}

1. [Встановлення WebSocket з'єднання](/api/auth)🔅
   1. [Інформація про ваш плагін](/api/messages/othercallback#callback-versioninfo)🔅
2. Передача даних про ресторан🔅:
   1. [Передача столів та залів ресторану](/api/messages/hallplansinfo)🔅
   2. [Передача списку персоналу ресторану](/api/messages/usersinfo)🔅
   3. [Передача категорій, для розподілу по банківським рахункам](/api/messages/categoriesinfo)🔅
3. Налаштування та печать платіжних QR-кодів на чек🔅:
   1. [Передача налаштувань](/api/messages/setsettings)🔅
4. Замовлення🔅:
   1. [Отримання рахунку](/api/messages/getbill)🔅
   2. [Оплата рахунку](/api/messages/paybill)🔅
5. Меню
   1. [Передача меню](/api/messages/othercallback#callback-menuinfo)🔅
   2. [Стоп-лісти](/api/messages/othercallback#callback-stoplist)
6. Круті фічі який ресторану буде приємно мати:
   1. [Room Service](/api/messages/order-from-menu)
   2. [Split Bill](/features/splitbill)🔅
   3. [Кешування рахунків](/api/messages/orders_cache)

***

## Налаштування

**Після** встановлення WebSocket з'єднання, а також **після** реалізації обов'язкових команд - просимо звернутись до нас аби ми проставили відповідні налаштування у нашій системі.

***

## Тестова оплата

[Підпишіться на нашого бота](https://t.me/shake2pay_alerts_bot), якщо не зробили цього раніше.

Більш детальніше про функціонал бота - [ось тут](https://docs.expirenza.com/api/integration/pages/Lk0fb0zAc2L8rbkdLXVg#5.-spovishennya)

Протестуйте оплату, повернення оплати, закриття замовлення.

{% hint style="info" %}
Ваш ресторан є тестовим, це означає що кошти після оплати будуть повертатись вам назад на картку. Банківські рахунки також будуть тестовими, вам не потрібно їх додавити при налаштуванні ресторану.
{% endhint %}

***


# Тестування технічної інтеграції

На цьому етапі ми хотіли б ще раз звернути увагу на деталі які варто перевірити

## Перевірка роботи інтеграції

На цьому етапі вам варто перевірити чи правильно працюють:

1. Передача категорій ресторану
2. Чи реконнект до серверу у разі обриву зв'язку налаштований не частіше ніж раз >=15 сек.
3. Додавання персоналу
4. Передача залів та столів
5. Чи були реалізовані під-статуси Fail команди [`/callback/paybill`](/api/messages/paybill), що можуть бути застосовні у вашій POS-системі.
6. Отримання замовлення, оплата замовлення, скасування замовлення
7. Меню
8. Оцінка страв  - передача параметра dishId у [`/callback/getBill`](/api/messages/getbill) &#x20;

Якщо усе працює - ви можете починати підключати ваші перші заклади до інтеграції з Expirenza.


# Схема роботи з AПІ

1. З використанням технології websocket POS система ресторану встановлює постійне з’єднання до **back-end API Expirenza**.
2. Клієнт ресторану робить замовлення, офіціант створює його у POS системі.
3. Клієнт сканує QR код та отримує рахунок за номером столика.
4. Expirenza **відправляє запит** на перегляд рахунку до POS системи ресторану через websocket-з'єднання.
5. ПЗ **отримує запит,** готує дані та **відправляє зворотний виклик (callback)** до **API Expirenza** використовуючи  **https** з'єднання.
6. **Інформація про рахунок відображається у додатку mono\Expirenza** після отримання відповіді від POS системи ресторану.

{% hint style="info" %}
Для перегляду прикладу клієнтського програмного забезпечення, що демонструє цей сценарій, перейдіть [за посиланням на Github](https://github.com/ShaketoPay/shakeToPayJavaClientExample).
{% endhint %}


# Підтримка трасування запитів (OpenTelemetry-підхід)

## 1. Загальна схема взаємодії

Інтеграція працює за наступною схемою:

1. Сервіси Expirenza надсилають інтегратору команду через **WebSocket**.
2. Інтеграція виконує необхідні дії (свій бізнес-процес, звернення до внутрішніх сервісів тощо).
3. Інтеграція повертає результат у Expirenza через **HTTP callback**.
4. Увесь шлях запиту має бути пов’язаний одним і тим самим `traceId`.

Логічний ланцюжок виглядає так:

> Expirenza (internal service)\
> → Expirenza External Connector\
> → API інтегратора\
> → Expirenza External Connector\
> → Expirenza (internal service)

На кожному новому сервісі створюється **новий `spanId`**, при цьому:

* `traceId` залишається незмінним протягом усього життєвого циклу запиту;
* `parent-span-id` вказує, з якого span прийшов запит.

***

## 2. Структура повідомлень у WebSocket

Усі WebSocket-повідомлення від Expirenza до інтегратора мають службове поле `__headers__`.

Приклад вхідного повідомлення:

```json
{
    "rID" : "2021-03-13 00:32:04.942046#UP57RxE",
    "operation" : "categoriesInfo",
    "__headers__": {
    "traceId": "c0a8017f6f2c4d98bd70a35c90f1f01",
    "spanId": "7b9a3d3c4e2f1a90"
    }
}
```

#### 2.1. Поля в `__headers__`

* `traceId`
  * Унікальний ідентифікатор всього запиту (end-to-end).
  * Є **обов’язковим** до збереження та передачі назад у відповідь (HTTP callback).
  * Інтеграція не повинна змінювати формат чи значення `traceId`. Сприймайте його як “чорну скриньку”.
* `spanId`
  * Ідентифікатор поточного етапу (span) усередині загального запиту.
  * Для інтеграції він виконує роль **`parent-span-id`** – тобто span, від якого “відгалужується” робота інтеграції.
  * Обробка `spanId` є **рекомендованою, але не обов’язковою** (див. розділ 4).

***

## 3. Обов’язкові вимоги до інтеграції

#### 3.1. Збереження `traceId` в контексті

Після отримання WebSocket-повідомлення інтеграція повинна:

1. Прочитати `traceId` з `message.__headers__.['traceId']`.
2. Зберегти його в контексті обробки запиту (thread context, request-scoped context, MDC/лог-контекст тощо).
3. Використовувати цей `traceId` при всіх логуваннях, що стосуються даного запиту.

#### 3.2. Передача `traceId` в HTTP callback

При формуванні HTTP-відповіді (callback) інтеграція **обов’язково** має додати заголовок:

```
traceId: <значення traceId з WebSocket-повідомлення>
```

**Приклад HTTP callback:**

```json5
POST /expirenza/callback/payment HTTP/1.1
Host: api.expirenza.example
Content-Type: application/json
traceId: c0a8017f-6f2c-4d98-bd70-3a35c90f1f01

{
  "status": "SUCCESS",
  "orderId": "ORD-12345",
  "transactionId": "TX-98765"
}
```

Це дозволяє Expirenza “зшити” логи WebSocket-команди, внутрішніх сервісів та відповіді інтеграції в один наскрізний трейс.

{% hint style="warning" %}
Важливо: **передача `traceId` у callback – обов’язкова вимога**.\
Якщо `traceId` буде відсутній або змінений, трасування буде порушене.
{% endhint %}

***

## 4. Рекомендована (опційна) підтримка `spanId` та `parent-span-id`

Підтримка `spanId`/`parent-span-id` на стороні інтеграції **рекомендована**, але **не є обов’язковою**.\
Вона потрібна для більш детального трасування всередині системи інтеграції та між сервісами.

#### 4.1. Що рекомендується робити

1. Прочитати вхідний:
   * `traceId`
   * `spanId` (як **`parent-span-id`** для інтеграції)
2. Створити \*новий \* **`spanId`** для роботи інтеграції (наприклад, `spanId` інтеграції):
   * `parent-span-id` = вхідний `spanId` з WebSocket.
   * `spanId` = нове згенероване значення.
3. Якщо інтеграція викликає свої внутрішні сервіси:
   * передавати:
     * той самий `traceId`,
     * `spanId` (власний) (внутрішній сервіс запише його як `parent-span-id`)
     * Внутрішній сервіс сгенерує новий `spanId` для кожного дочірнього виклику.
4. При поверненні відповіді в Expirenza (HTTP callback) можна (опційно) передавати:

```jsonl
traceId: <обов'язково>
spanId: <span-id інтегратора з якого було здійснено http виклик>
```

Ще раз: **для Expirenza обов’язковим є тільки `traceId`**.\
Передача/ланцюжок `spanId` та `parent-span-id` – опція, яка дозволить глибше аналізувати ланцюжок викликів, якщо інтегратор цього бажає.&#x20;

***

## 5. Навіщо це потрібно інтеграції

Підтримка `traceId` (мінімально) та `spanId` (опційно) дає інтеграції такі переваги:

1. **Швидкий пошук інцидентів**
   * Можна отримати `traceId` від Expirenza (наприклад, з технічного запиту) і швидко знайти всі пов’язані логи та виклики у своїй системі.
2. **Кореляція логів між системами**
   * Expirenza та інтеграції дивляться на один і той самий `traceId`, що спрощує спільну діагностику.
3. **Глибинний аналіз продуктивності** (якщо використовуєте `spanId`)
   * Можна будувати детальні діаграми: скільки часу зайняла обробка в інтеграції, скільки – у внутрішніх сервісах інтеграції, де “вузьке місце”.
4. **Сумісність із OpenTelemetry та APM-системами**
   * Якщо інтеграція вже використовує OpenTelemetry, `traceId`, `spanId` та `parent-span-id` можна напряму мапити на відповідні сутності (trace/span/parent span).

***

## 6. Діаграма проходження запиту (послідовність)

{% @mermaid/diagram content="sequenceDiagram
participant IS as Expirenza Internal Service
participant EC as Expirenza External Connector
participant INT as Integrator API

```
Note over IS,INT: traceId = T1 (незмінний протягом усього життєвого циклу)

IS->>EC: Запит на зовнішній виклик (traceId=T1, spanId=S1)
EC->>INT: WebSocket повідомлення (traceId=T1, spanId=S2)

Note over INT: Інтегратор зберігає traceId=T1,<br/>spanId=S2 як parent-span-id,<br/>генерує власний spanId S3 (опційно)

INT->>INT: Внутрішня обробка (traceId=T1, spanId=S3, parent-span-id=S2)
INT-->>EC: HTTP callback (traceId=T1, spanId=S3)
EC-->>IS: Результат обробки (traceId=T1, spanId=S4, parent-span-id=S3)" %}
```

{% hint style="info" %}
Якщо інтеграція не реалізує `spanId`/`parent-span-id`, ви все одно повинні зберігати і повертати **`traceId`** – тоді всі вузли будуть пов’язані хоча б на рівні трейсів.
{% endhint %}

***

## 7. Підсумок вимог

**Обов’язково для інтеграції:**

1. Прочитати `traceId` із WebSocket-повідомлення (`__headers__.traceId`).
2. Зберігати `traceId` в контексті обробки запиту.
3. Логувати `traceId` для всіх дій у межах одного запиту.
4. Передавати `traceId` у HTTP callback як заголовок `traceId`.

**Опційно (рекомендовано):**

1. Використовувати `spanId` із WebSocket-повідомлення як `parent-span-id`.
2. Генерувати власні `spanId` для операцій інтеграції.
3. Передавати `spanId` у HTTP callback.
4. Інтегрувати цю схему з OpenTelemetry / APM системами для розширеної візуалізації трейсів.


# Авторизація

## Встановлення WebSocket з'єднання

З'єднання від POS-системи до API Expirenza виконується за допомогою WebSocket.

{% hint style="danger" %}
Під час реалізації WebSocket **необхідно** налаштовувати **повторні спроби з'єднання** з сервером Expirenza **не частіше ніж раз на 15 секунд**.
{% endhint %}

<details>

<summary>Як реалізувати з'єднання правильно на боці інтеграції?</summary>

Так виглядає блок схема того, як сервер Expirenza опитує POS-систему для утримання зʼєднання:

![](/files/EoxaniHfuh78mWz4Rcfe)

1. **Expirenza** посилає **ping** у сокет раз в 15 секунд
2. Очікує наявність **pong** у наступні 1.5 хвилини&#x20;
3. Якщо **pong** не було отримано за 1.5 хвилини - Expirenza розриває з'єднання

POS-системи мають перевіряти (не частіше ніж раз у 15 секунд):

1. Якщо з'єднання немає — намагається під'єднатися,
2. Якщо з'єднання є — перевіряє, коли був останній pong від сервера на ping від інтеграції,
3. Якщо пройшло **більше** ніж 1,5 хвилини — значить, щось не так із з'єднанням, **розриває** його(останній коннект) і намагається під'єднатися ще раз,
4. Якщо з'єднання є і останній ping був **менш** **ніж** 1,5 хвилини тому, значить все добре — інтеграція відправляє pong
5. Якщо після перепідключення сервер одразу дисконнектить - то треба розірвати існуюче зʼєднання, і створити нове

</details>

{% hint style="warning" %}
**Headers**.\
Обов'язкова умова передавати наступні хідери, якщо не передати - авторизація не буде працювати.\
\
`cookie: system={{API}};`\
`Де {{API}} - назва вашої POS системи.`&#x20;

`__`\
`user-agent: Apache-HttpClient/5.2.3 (Java/17.0.7) (Приклад)`\
*`Значення для заголовку user-agent  - довільне - як правило - це назва технології що використовується для встановлення http зʼєднання`*
{% endhint %}

Запит на встановлення з'єднання відправляється на адресу з використанням Basic Auth.

Адреса запиту:

```http
wss://api.shaketopay.com.ua/restaurantEntryPoint
```

<details>

<summary>Приклад з'єднання  через websocket</summary>

{% code title="Java" overflow="wrap" lineNumbers="true" %}

```java
import javax.websocket.*;
import javax.websocket.ClientEndpointConfig.Builder;
import javax.websocket.ClientEndpointConfig.Configurator;
import javax.xml.bind.DatatypeConverter;

private final WebsocketEndpoint websocketEndpoint;
private final ClientEndpointConfig clientConfig;
private final URI uri;

    Builder configBuilder = Builder.create();
    String authHeaderValue = "Basic " + DatatypeConverter.printBase64Binary((user + ":" + password).getBytes());
    configBuilder.configurator(new Configurator() {
        @Override
        public void beforeRequest(Map<String, List<String>> headers) {
            headers.put("Authorization", Arrays.asList(authHeaderValue));
        }
    });
    clientConfig = configBuilder.build();
    this.uri = new URI(uri);
    this.websocketEndpoint = new WebsocketEndpoint(messageHandler, new        EventListenerI() {
        @Override
        public void notify(Object o) {
            connected = false;
        }
    });
)

void connect() throws IOException {
    WebSocketContainer container = ContainerProvider.getWebSocketContainer();
    container.connectToServer(websocketEndpoint, clientConfig, uri);
}

void sendMessage(String message) throws IOException {
    websocketEndpoint.session.getBasicRemote().sendText(message);
}
...
```

{% endcode %}

</details>

***

## Валідація запиту

На стороні Expirenza буде проведена перевірка справжності запиту після надсилання даних від ресторану.&#x20;

Для проходження перевірки на стороні ПЗ ресторану в заголовках кожного запиту повинні міститися параметри `signature`та `restoId`.

{% tabs %}
{% tab title="signature" %}

1. Тіло запиту необхідно підписати алгоритмом HmacSHA256.
2. Результат роботи алгоритму помістити у значення параметра.
   {% endtab %}

{% tab title="restoId" %}
Передати у параметр RESTO\_ID з файлу налаштувань [properties.txt](/api/integration/prepare)
{% endtab %}

{% tab title="header user-agent" %}
`user-agent: Apache-HttpClient/5.2.3 (Java/17.0.7) (Приклад)`\
*`Значення для заголовку user-agent  - довільне - як правило - це назва технології що використовується для встановлення http зʼєднання`*
{% endtab %}
{% endtabs %}

<details>

<summary>Приклад генерації підпису та додавання її в заголовок signature</summary>

{% code title="JAVA" %}

```java
String signValue = makeSignature(dataBytes);

ResponseEntity<String> bodyEntity = webClient.post()
.uri(urlPart).body(BodyInserters.fromValue(dataBytes))
.header("signature", signValue).retrieve()
.toEntity(String.class).block();

private String makeSignature(byte[] bytes) throws InvalidKeyException, NoSuchAlgorithmException {
    Mac hasher = Mac.getInstance("HmacSHA256");
    hasher.init(new SecretKeySpec(secretKey.getBytes(), "HmacSHA256"));
    byte[] hash = hasher.doFinal(bytes);
    return DatatypeConverter.printBase64Binary(hash);
}
```

{% endcode %}

Де secretKey - це SECRET\_KEY з файлу properties.txt

</details>

{% hint style="info" %}
Приклад підключення за допомогою [Postman](/api/postman).
{% endhint %}

***


# Дотримання сучасних безпекових протоколів

Цей розділ описує вимоги до протоколів шифрування TLS для інтеграції з Expirenza

## Підтримувані версії TLS на сервері

Сервер Expirenza підтримує такі версії протоколу TLS:

* **Підтримуються:**
  * TLS **1.2**
  * TLS **1.3** (рекомендовано)
* **Не підтримуються (з’єднання відхиляються):**
  * TLS **1.0**
  * TLS **1.1**

Підключення з використанням версій нижчих за TLS 1.2 є неможливим.

## Рекомендовані дії

Щоб уникнути помилок встановлення захищеного з’єднання та забезпечити коректну роботу інтеграції з Expirenza, рекомендується:

1. **Увімкнути та використовувати TLS 1.2 / 1.3**
   * Переконатися, що у середовищі виконання (ОС, платформа, мережеві бібліотеки, HTTP-клієнти тощо) **активовано підтримку TLS 1.2**.
   * За можливості **увімкнути та використовувати TLS 1.3**.
2. **Вимкнути TLS 1.0 та TLS 1.1**
   * Заборонити використання TLS 1.0 та TLS 1.1 на всіх компонентах, що встановлюють з’єднання з Expirenza (клієнтські застосунки, проксі, шлюзи, балансувальники тощо).
3. **Перевірити працездатність після змін**
   * Після оновлення налаштувань протоколів TLS повторно протестувати підключення до Expirenza та переконатися у відсутності помилки «Помилка при встановленні захищеного з’єднання».

### Можливі помилки

При спробі підключення до Expirenza  у разі використання застарілих версій TLS інтеграція може отримувати помилку:

* **«Помилка при встановленні захищеного з’єднання»**

Причина помилки: спроба встановити TLS-зʼєднання з версією протоколу, яка не підтримується сервером (TLS 1.0 або TLS 1.1).


# Операції між Expirenza і POS системою

{% hint style="info" %}
Повідомлення надсилаються у JSON форматі
{% endhint %}

{% hint style="warning" %}
1.Параметри які відзначені " <mark style="color:red;">\*</mark> " - позначають обов'язковість параметра.

2.Content type: application/json
{% endhint %}

## Елементи та типи даних повідомлень

<table><thead><tr><th width="150">Element</th><th width="109">Data Type</th><th width="137">Required</th><th>Description</th></tr></thead><tbody><tr><td>rID</td><td>String</td><td>✔️</td><td>Ідентифікатор запиту в системі Expirenza</td></tr><tr><td>operation</td><td>String</td><td>✔️</td><td>Ідентифікатор методу</td></tr><tr><td>tableNumber</td><td>String</td><td>❌</td><td>Номер столу, на якому виконати пошук рахунку</td></tr><tr><td>billId</td><td>String</td><td>❌</td><td>Ідентифікатор рахунку в ресторані</td></tr><tr><td>sum</td><td>Money</td><td>❌</td><td>Сума, яку сплачує клієнт ресторану</td></tr><tr><td>tips</td><td>Money</td><td>❌</td><td>Чайові офіціанту</td></tr></tbody></table>


# Отримання рахунку за номером стола

Для отримання рахунку, Expirenza надсилатиме наступне повідомлення:

<details>

<summary>getBill</summary>

```
❗️ Обов'язкові елементи запиту: rID,operation та tableNumber або billId.
```

```
❗️ Наразі інтеграція підтримує передачу параметру guests.dishes.dishId,
   у якому dishId порожній. 
 
❗️ Ми суворо рекомендуємо передавати dishId і не залишати його порожнім,так як
   варіант с порожнім dishId невдовзі стане застарілим, і якщо ви його
    не передавали у вас можуть виникнути проблеми з інтеграцією, та не буде 
     працювати оцінка блюд.
```

Переконайтесь, що ваша інтеграція підтримує всі можливі комбінації цих параметрів:&#x20;

Сценарії :&#x20;

1. Тільки  з `billId`:

Сценарій з `billId`  позначає що оплата буде здійснена по QR з пречеку.

```json
{
    "rID" : "2021-03-13 00:32:04.942046#UP57RxE",
    "operation" : "getBill",
    "billId": "079148b1-2824-11ed-8dbd-3c7c3fbcab3c"
}
```

2. Тільки з `tableNumber`:

Сценарій з `tableNumber` позначає що оплата буде здійснена по QR на столі.

```json
{
    "rID" : "2021-03-13 00:32:04.942046#UP57RxE",
    "operation" : "getBill",
    "tableNumber" : "12",
}
```

***

Q. Як ресторану повідомити Expirenza про нове замовлення, як передати згенерований `billId`  до Expirenza?

\
A. Наразі немає готового `callback` (він скоро буде) через який ресторан може повідомити Expirenza про нове замовлення.

Зараз Expirenza сама опитує ресторан і отримує від ресторану `billId.`

Приклад:&#x20;

Гість ресторану робить замовлення -> замовлення вносять у POS-систему&#x20;

-> гість ресторану поїв і сканує QR для оплати замовлення -> *Expirenza дізнається про `billId`  у момент сканування QR.*

*У випадку billId це QR на пречеку. У випадку* `tableNumber` QR на столі.

</details>

{% openapi src="/files/gJ9dvFaUybCfX8X5sznL" path="/callback/getBill" method="post" %}
[getBill03.05.2024\_updated.json](https://115752690-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUrrjxJkhEuwfb0dGwW06%2Fuploads%2FGARgS1CIGuX2TdGUtmF4%2FgetBill03.05.2024_updated.json?alt=media\&token=6098cbb3-4015-43a9-a7bd-0379d4c7aca6)
{% endopenapi %}

<details>

<summary><strong>Payload example: <code>/callback/getBill</code></strong></summary>

<pre class="language-json" data-title="JSON" data-line-numbers><code class="lang-json">{
  "errorCode": "BILL_NOT_FOUND",
  "errorMessage": "Not found bills by table number 7",
  "orders": [
    {
      "billId": "7A051331-1C99-4DD2-9543-1585A4E21DCA",
      "created": "yyyy.MM.dd HH:mm:ss",
      "discounts": {},
      "guests": [
        {
          "dishes": [
            {
              "category": "Кухня",
              "categoryId": "18afdzgu53a",
              "checkNumber": "string",
              "count": 1.3,
              "dishId": "string",
              "linkedTo": "string",
              "hidden": false,
              "name": "Шаурма царська",
              "orderNumber": 12365,
              "positionId": "string",
              "sum": 34.56,
             <a data-footnote-ref href="#user-content-fn-1"> "taxCategory": "налоги",</a>
              <a data-footnote-ref href="#user-content-fn-1">"taxCategoryId": "18afdzgu534"</a>,
              "type": "dish"
            }
          ],
          "name": "Гость 1"
        }
      ],
      "isBanquetOrder": false,
      "isDelivery": false,
      "orderNumber": 256,
      "pricingTime": "string",
      "rawSum": 0,
      "rootBillId": "string",
      "splitAvailable": true,
      "state": "string",
      "tableId": "qc7-sdv9",
      "totalSum": 123.35,
      "waiter": "string",
      "waiterId": "string",
      "billAmountForTips":123.12
    }
  ],
  "rID": "2021-04-01 09:39:06.021078#BpOI0gO",
  "state": "FAIL",
  "substate": "string",
  "tableNumber": 9
}
</code></pre>

</details>

<details>

<summary>Роз'яснення по <code>linkedTo</code></summary>

`positionId` - id позиції в чеку. Позиція = строчка в чеку.\
`linkedTo` - id Батьківської позиції в чеку.\
\**Якщо страва сама по собі є батьківською треба передавати `linkedTo: null`*

Наприклад, клієнт замовив:\
Біг Мак Меню

Що складається з:

1. Біг мак
2. Діпи:\
   \- Сирний соус
3. Апельсиновий Сік

В POS системі Біг Мак Меню - це комбо страва.\
Яка має 3 можливих складових:

1. Бургер - Біг Бак
2. Картопля на вибір Діпи/Картопля фрі (+ соус як модифікатор до картоплі).
3. Напій на вибір Кола/Спрайт/Апельсиновий сік.

Біг Мак - це батьківська страва - `linkedTo` = null\
`positionId` = AAA

\
Діпи це дочірня страва до Біг Маку, тому `linkedTo` = AAA - де ААА - id позиції батьківської страви\
`positionId` = BBB

\
Сирний соус - дочірня страва до діпів - `linkedTo` = BBB, `positionId` = CCC\
\
Апельсиновий сік - дочірня страва до Біг Маку - `linkedTo` = AAA,\
`positionId` = DDD

</details>

> Таблиця можливих статусів.&#x20;
>
> ❗❗ **Для стану FAIL наявність суб-статусу є обов'язковим, суб-статус також не має бути = null.**&#x20;
>
> Це потрібно для правильної комунікації із клієнтами ресторану.
>
> Приклад: Замовлення не було знайдено, але не передано суб-статус - ORDER\_NOT\_FOUND.\
> Клієнт бачить на боці Expirenza невідому помилку, замість помилки "Рахунок на столику не знайдено".

| state   | substate          | Description                                 |
| ------- | ----------------- | ------------------------------------------- |
| SUCCESS | -                 | Рахунок знайдено                            |
| FAIL    | TABLE\_NOT\_FOUND | Стіл переданий у пошук не існує в ресторані |
| FAIL    | ORDER\_NOT\_FOUND | Рахунок на столику не знайдено              |

<figure><img src="/files/5ntH0DQo8tvrc5mAjEVY" alt=""><figcaption><p>Приклад: НЕ правильна помилка, коли при status - Fail не був переданий substate.</p></figcaption></figure>

<figure><img src="/files/o9NSs4vYb3rHnAk4rNmD" alt=""><figcaption><p>Приклад: Правильна помилка, коли при status - Fail був переданий substate.</p></figcaption></figure>

***

## Застосування знижки

Застосувати знижку для замовлення можна використовуючи об'єкт `discounts` що знаходиться в структурі getBill.

`"discounts":{"list":[{"id": "","name":"","sum":0}}`\
\
Знижки через `discounts` працюють **тільки на відображення** у чеку, це означає що знижку інтеграція має вираховувати самостійно на своєму боці та передавати у поля `sum` та `totalSum`  суми страв вже з урахуванням знижки.

\
❗Сума кожної страви має враховувати знижки застосовані до чеку.

❗Сума знижки не має бути у від'ємних значеннях ( Приклад як **не** треба: `sum:"-350"`)

### Приклад використання знижки

До страви яка коштує 249 грн застосовується скидка 40 грн.\
Страва:

```
{
   "sum":249,
   "name":"Індичка у вершковому соусі з грибами, томатами кімчі",
   "count":1.0,
   "guest":"guest",
   "category":"Кухня",
   "category_id":"b4e30148-b13e-11ea-80e8-d8d9ff6efa94",
   "order_number":"000080526"
}
```

Знижка 40 грн:

```
"discounts":{
   "list":[
      {
         "id":"id",
         "name":"Індичка у вершковому соусі з грибами, томатами кімчі",
         "sum":40
      }
   ]
}
```

При застосуванні знижки до страви(страв), потрібно змінювати sum цієї страви(страв) і вираховувати totalSum відповідно до застосованих знижок.\
Тобто сума після застосування знижки має виглядати так:

<pre><code>}   
   <a data-footnote-ref href="#user-content-fn-2">"sum":209,</a>
   "name":"Індичка у вершковому соусі з грибами, томатами кімчі",
   "count":1.0,
   "guest":"guest",
   "category":"Кухня",
   "category_id":"b4e30148-b13e-11ea-80e8-d8d9ff6efa94",
   "order_number":"000080526"
}
</code></pre>

***

[^1]: Використовується якщо у ресторана тип розподілення коштів на податкові категорії

[^2]: Змінюється ціна. ( sum - discounts )


# Оплата рахунку і закриття замовлення

## Повідомлення для фіскалізації

<details>

<summary>payBill</summary>

{% code lineNumbers="true" %}

```json
{
    "rID" : "2021-03-13 00:32:04.942046#UP57RxE",
    "operation" : "payBill",
    "billId" : "5B100B39-CE42-4F3D-8770-807A28CA0500",
    "sum" : 129.20,
    "tipsInfo": {
       "amount":19.24,
       "recipient":"WAITER"
    },
    "fiscalData":[
      {
         "key":"ЕКВАЙЕР",
         "value":"Universal Bank"
      },
      {
         "key":"ТЕРМІНАЛ",
         "value":"XPZ10101010"
      },
      {
         "key":"КОМІСІЯ",
         "value":"N грн."
      },
      {
         "key":"ВИД ОПЕРАЦІЇ",
         "value":"Оплата"
      },
      {
         "key":"ЕПЗ",
         "value":"123456******12"
      },
      {
         "key":"ПС",
         "value":"МС|VISA"
      },
      {
         "key":"RRN",
         "value":"1234567890"
      },
      {
         "key":"КОД. АВТ",
         "value":"1234"
      },
      {
         "key":"ФОРМА ОПЛАТИ",
         "value":"БЕЗГОТІВКОВА"
      },
      {
         "key":"ЗАСОБ ОПЛАТИ",
         "value":"ПЕРЕКАЗ ЧЕРЕЗ QR-КОД"
      }
   ],
}
```

{% endcode %}

<pre><code>❗️ Обов'язкові елементи запиту: rID, operation, billId, sum. 
<strong>  fiscalData - Блок інформації щодо транзакції для друку на фіскальному чеку.
</strong></code></pre>

{% code overflow="wrap" %}

```
tipsInfo.amount - розмір чайових
tipsInfo.recipient - отримувач чайових
 WAITER - якщо отримувач офіціант - чайові на карту (особисту або загальну)
 RESTAURANT - якщо чайові зараховуються на рахунок ресторану, в такому випадку чайові треба додати в рахунок перед фіскалізацією
```

{% endcode %}

</details>

## Відповідь

Відповідь обробки операції необхідно надіслати в наступному вигляді:

{% openapi src="/files/BafGluElGwLDXt2IOqlf" path="/callback/payBill" method="post" %}
[payBill\_updated.json](https://115752690-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUrrjxJkhEuwfb0dGwW06%2Fuploads%2F08UPYIiglHvtUxOOLDJb%2FpayBill_updated.json?alt=media\&token=141661ab-0403-4070-aaed-f4b9eee27b4d)
{% endopenapi %}

<details>

<summary>Payload example:<code>/callback/payBill</code></summary>

{% code title="JSON" lineNumbers="true" %}

```json
{
  "billId": "string"
  "guests": [
    {
      "dishes": [
        {
          "category": "Кухня",
          "categoryId": "18afdzgu53a",
          "checkNumber": "string",
          "count": 1.3,
          "dishId": "string",
          "linkedTo": "string",
          "name": "Шаурма царська",
          "orderNumber": 12365,
          "positionId": "string",
          "sum": 34.56,
          "taxCategory": "налоги",
          "taxCategoryId": "18afdzgu534",
          "type": "modifier"
        }
      ],
      "name": "Гость 1"
    }
  ],
  "orderNumber": 235,
  "rID": "2021-04-01 09:39:06.021078#BpOI0gO",
  "stackTraceMessage": "string",
  "state": "SUCCESS",
  "substate": "string",
  "waiter": "Петро",
  "waiterId": "f14da21a-5be9-4736-9ece-420bd310bc8a"
}
```

{% endcode %}

</details>

Результатом закриття замовлення у POS-системі можуть бути 2 статуси - FAIL та SUCCESS. \
Для статусу FAIL існують суб-статуси, які дозволяють правильно комунікувати проблему співробітникам закладу.

{% hint style="danger" %}
**Важливим є реалізація усіх підстатусів**, тому як Expirenza має знати у якому суб-статусі знаходиться замовлення, а ресторан має знати що саме пішло не так.
{% endhint %}

Якщо наведені вище сценарії не покривають всіх потреб вашої інтеграції, будь ласка, зверніться до *аккаунт-менеджера* ресторану з детальним описом потреби вашої інтеграції.&#x20;

Ми розглянемо можливість додавання додаткового суб-статусу в Expirenza API.

## Підстатуси FAIL

### WRONG\_REQUEST\_SUM

Description:

&#x20;Сума, що прийшла у запиті для оплати, більша або менша від суми замовлення в POS-системі.&#x20;

&#x20;Така ситуація може виникнути, якщо замовлення було відредаговано у проміжку між  отриманням оплати від гостя та закриттям замовлення у POS-системі.

Обробка substate:

1. Система спише оплату з гостя та покаже повідомлення “Оплата успішна”;.
2. Система надішле персоналу повідомлення в бот з рекомендацією повернути замовлення у початковий стан (скасувати зміни), щоб розблокувати закриття замовлення, або повернути оплату гостю та попросити оплатити заново.
3. Система повторюватиме спроби закрити замовлення з певним інтервалом.

***

### CASHIERS\_SHIFT\_CLOSED

Description:

&#x20;Неможливо закрити замовлення через те, що в POS-системі закрита касова зміна.

Обробка substate:

1. Система спише оплату з гостя та покаже повідомлення “Оплата успішна”.
2. Система відправить персоналу повідомлення у бот з рекомендацією відкрити касову зміну, щоб розблокувати закриття замовлення у POS-системі.
3. Система повторюватиме спроби закрити замовлення з певним інтервалом.

***

### PRINTER\_ERROR

Description:

&#x20;Неможливо закрити замовлення через проблему з фіскальним принтером.

Обробка substate:

1. Система спише оплату з гостя та покаже повідомлення "Оплата успішна".
2. Система надішле персоналу повідомлення у бот з рекомендацією виправити проблему з фіскальним принтером, щоб розблокувати закриття замовлення у POS-системі.
3. Система повторюватиме спроби закрити замовлення з певним інтервалом.

### CLOSE\_ORDER\_BLOCKED

Description:

&#x20;Закриття замовлення заблоковано відкладеною подачею страв.&#x20;

&#x20;Наприклад:  У замовленні є нероздрукований “бігунок” на кухню або бар.

Обробка substate:

1. Система спише оплату з гостя та покаже повідомлення “Оплата успішна”.
2. Система надішле персоналу повідомлення в бот з рекомендацією видалити бігунки або передати на кухню нероздруковані “бігунки”, щоб розблокувати закриття замовлення у POS-системі.
3. Система повторюватиме спроби закрити замовлення з певним інтервалом.

***

### BILL\_IN\_USE

Description:

&#x20;Замовлення заблоковане іншим модулем POS-системи.&#x20;

&#x20;Наприклад:На даний час замовлення відкрито на касовій станції та редагується офіціантом.

Обробка substate:

1. Система спише оплату з гостя та покаже повідомлення "Оплата успішна".
2. Система відправить персоналу повідомлення у бот з рекомендацією вийти з режиму редагування замовелння на робочій станції, щоб розблокувати закриття замовлення у POS-системі.
3. Система повторюватиме спроби закрити замовлення з певним інтервалом.

***

### OTHER\_ERROR

Description:

&#x20;Інші помилки під час закриття замовлення.

Обробка суб-статусу:

1. Система спише оплату з гостя та покаже повідомлення “Оплата успішна”.
2. Система надішле персоналу повідомлення у бот з рекомендацією звернутися до служби підтримки постачальника POS-системи для закриття замовлення.
3. Система **не робитиме** повторних спроб закрити таке замовлення, а здійснить виплату ресторану за даними замовелння отриманими перед оплатою.


# Отримання списку персоналу

Офіціантів і курʼєрів. Необхідно для повідомлень і персоналізації чайових.

Для отримання списку персоналу закладу, Expirenza надсилатиме наступне повідомлення:

<details>

<summary>usersInfo</summary>

{% code lineNumbers="true" %}

```json
{
    "rID" : "2021-03-13 00:32:04.942046#UP57RxE",
    "operation" : "usersInfo"
}
```

{% endcode %}

```
❗️ Обов'язкові елементи запиту: rID, operation.
```

</details>

Відповідь обробки операції необхідно надіслати в наступному вигляді:

{% openapi src="/files/YLlUXmd5ydsaINBtRe11" path="/callback/usersInfo" method="post" %}
[json.json](https://115752690-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUrrjxJkhEuwfb0dGwW06%2Fuploads%2F4xObaL3YU3CMgHkDXSIz%2Fjson.json?alt=media\&token=3abafd3a-355b-4295-8234-2b581e574c68)
{% endopenapi %}

<details>

<summary><strong>Payload example: <code>/callback/usersInfo</code></strong></summary>

{% code title="JSON" overflow="wrap" %}

```json
{
  "rID": "2021-04-01 09:39:06.021078#BpOI0gO",
  "users": [
    {
      "cellPhone": "+380961112233",
      "id": "ab863-78",
      "name": "Петро",
      "roles":["Кухар універсал","Су-шеф кухар"]
    }
  ]
}
```

{% endcode %}

</details>

***

## **Окремо реалізовано апі для проактивного отримання списку користувачів.**

***Цей функціонал також рекомендовано до реалізації.*** \
***Цей варіант є більш реактивним за usersInfo.***\
**Expirenza** очікує отримання хука про оновлення одного юзера кожен раз, коли юзер зазнав змін, видалився або був створений.

З використанням апі проактивного отримання списку користувачі - інтеграція сама ініціює оновлення користувачів в системі Expirenza.

### Вебхук для оновлення <mark style="color:red;">одного</mark> юзера.

{% openapi src="/files/mrbSE80xbKxObBlEMtTR" path="//api.shaketopay.com.ua/callback/webhook" method="post" %}
[forceUsersInfo.json](https://115752690-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUrrjxJkhEuwfb0dGwW06%2Fuploads%2FOx935xd1hkB0tSmJF2Gz%2FforceUsersInfo.json?alt=media\&token=ffba5012-382e-49d3-9880-d806df813eac)
{% endopenapi %}

<details>

<summary>Payload example <code>/callback/webhook:</code></summary>

```json
{
  "webhookType":"USER_CANGED",
  "eventTime":"2024-07-28T19:29:17Z",
  "action": "UPDATED",
  "user":{
    "id":"someId",
    "cellPhone":"+380631111111",
    "name":"Cat Expirenza"
  }
}
```

</details>

***

### Вебхук для оновлення <mark style="color:red;">всіх</mark> юзерів.

Передбачає оновлення всіх користувачів у системі POS.

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

Рекомендації щодо використання:

1. При запуску POS-системи.
2. З інтервалом на добу.

{% openapi src="/files/GxxEbmjHb4ywa5S3BHHi" path="//api.shaketopay.com.ua/callback/webhook" method="post" %}
[forceUpdateAllUsers.json](https://115752690-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUrrjxJkhEuwfb0dGwW06%2Fuploads%2Fj94GNxQuXJQlDHw1ElN8%2FforceUpdateAllUsers.json?alt=media\&token=597a747b-c249-4514-bf21-f43dba9ae1c5)
{% endopenapi %}

<details>

<summary>Payload example <code>/callback/webhook:</code></summary>

```json
{
    "webhookType": "UPDATE_ALL_USERS",
    "eventTime": "2024-09-19T12:05:35.2537443Z",
    "users": [
        {
            "id": "993332e8-bfea-460d-99c3-9fcba5f944ca",
            "cellPhone": "+380931234568",
            "name": "Cat Expirenza"
        },
        {
            "id": "someId",
            "cellPhone": "+380931234567",
            "name": "Cat Mono"
        }
    ]
}
```

</details>


# Отримання категорій

Для отримання категорій, Expirenza надсилатиме наступне повідомлення:

<details>

<summary>categoriesInfo</summary>

{% code lineNumbers="true" %}

```json
{
    "rID" : "2021-03-13 00:32:04.942046#UP57RxE",
    "operation" : "categoriesInfo"
}
```

{% endcode %}

```
❗️ Обов'язкові елементи запиту: rID, operation.
```

</details>

Відповідь обробки операції необхідно надіслати в наступному вигляді:

{% openapi src="/files/k4R9oTFin8KVNXJtTuan" path="/callback/categoriesInfo" method="post" %}
[categoriesInfo.json](https://115752690-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUrrjxJkhEuwfb0dGwW06%2Fuploads%2FGTDCiotrTqWWqccwqTOl%2FcategoriesInfo.json?alt=media\&token=394bdb1b-6574-4d15-8c93-4b6500b3c333)
{% endopenapi %}

<details>

<summary><strong>Payload example: <code>/callback/categoriesInfo</code></strong></summary>

{% code title="JSON" lineNumbers="true" %}

```json
{
  "categories": [
    {
      "id": "7_7d-72gma",
      "name": "Кухня",
      "type": "product"
    }
  ],
  "rID": "2021-04-01 09:39:06.021078#BpOI0gO"
}
```

{% endcode %}

</details>


# Отримання інформації про столи ресторану

Для отримання інформації про столи ресторану, Expirenza надсилатиме наступне повідомлення:

<details>

<summary>tablesInfo</summary>

{% code lineNumbers="true" %}

```json
{
    "rID" : "2021-03-13 00:32:04.942046#UP57RxE",
    "operation" : "tablesInfo"
}
```

{% endcode %}

```
❗️ Обов'язкові елементи запиту: rID, operation.
```

</details>

Відповідь обробки операції необхідно надіслати в наступному вигляді:

{% openapi src="/files/2uVKvahIOrvha51NPqHg" path="/callback/tablesInfo" method="post" %}
[json.json](https://115752690-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUrrjxJkhEuwfb0dGwW06%2Fuploads%2FWy3Jzk3JSRjRHOY6jdGb%2Fjson.json?alt=media\&token=c13b0123-b888-41c5-91ae-de4338b17196)
{% endopenapi %}

<details>

<summary><strong>Payload example: <code>/callback/tablesInfo</code></strong></summary>

{% code title="JSON" lineNumbers="true" %}

```json
{
  "rID": "2021-04-01 09:39:06.021078#BpOI0gO",
  "tables": [
    {
      "hallplanId": "уцец-38ec",
      "id": "ajvx12-38ec",
      "name": "у камина",
      "number": 12
    }
  ]
}
```

{% endcode %}

</details>


# Отримання переліку залів у ресторані

### Отримання переліку залів у ресторані

<details>

<summary>hallplansInfo</summary>

{% code lineNumbers="true" %}

```json
{
    "rID" : "2021-03-13 00:32:04.942046#UP57RxE",
    "operation" : "hallplansInfo"
}
```

{% endcode %}

```
❗️ Обов'язкові елементи запиту: rID, operation.
```

</details>

Відповідь обробки операції необхідно надіслати в наступному вигляді:

{% openapi src="/files/iXNOdY0hW7PHvKJGfVq8" path="/callback/hallplansInfo" method="post" %}
[getBill.json](https://115752690-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUrrjxJkhEuwfb0dGwW06%2Fuploads%2F67hEVY5ORTYFsWrivj3B%2FgetBill.json?alt=media\&token=1f823187-57a1-419a-8120-85a737b8496e)
{% endopenapi %}

<details>

<summary>Payload example:/callback/hallplansInfo</summary>

```json
{
  "hallplans": [
    {
      "id": "ajvx12-38ec",
      "name": "зал 1"
    }
  ],
  "rID": "2021-04-01 09:39:06.021078#BpOI0gO"
}
```

</details>


# Отримання налаштувань для відображення QR на ПреЧек

Це функціонал, який дозволяє друкувати платіжний QR-код на ПреЧеку.

**Логіка інтеграції**

1. **Підключення до POS-системи:** Expirenza при встановленні з'єднання буде відправляти цю команду у WebSocket. Ми не очікуємо відповіді на цю команду, лише передаємо налаштування для пречеку.
2. **Сервер:** Сервер передає base URL, до якого треба додати `orderId` і передати сформований QR-код та текст "до" та "після" на принтер.
3. **Реалізація:** Передача QR на прінтер для друку - на стороні інтеграції.
4. Результат: Гості отримують пречек з платіжним QR-кодом і можуть оплатити конкретне замовлення за допомогою надрукованого QR-коду.

{% code lineNumbers="true" fullWidth="true" %}

```
{
   "operation":"setSettings",
   "rID":"2022-11-01 14:36:38.530139872#qEqdLCq",
   "settings":{
      "load_modifiers":"true"
   },
   "precheckQrUrl":"https://mbnk.biz/4DsvYW9LkA/orderId_{orderId}",
   "messageAfterQr":"Наведіть камеру смартфона або QR-сканер",
   "bonusUsage":false,
   "paymentAllowed":true,
   "bonusPaymentTypes":[],
   "printPrecheckQr":false,
   "messageBeforeQr":"Сплатити цей рахунок можна за QR-кодом",
   "printDeliveryPrecheckQr":false
}
```

{% endcode %}

* Опис налаштуваннь

`(`printPrecheckQr `=`` `<mark style="color:green;">`true`</mark>`/`<mark style="color:red;">`false`</mark>`);` -  “Друкувати платіжний QR-код на пречеку”  (Аби приходило true - запитайте менеджера чи тех.підтримку увімкнути цю опцію для вашого тестового ресторану)

`(`printDeliveryPrecheckQr `=`` `<mark style="color:green;">`true`</mark>`/`<mark style="color:red;">`false`</mark>`);` - “Друкувати платіжний QR-код на накладній доставки”&#x20;

Тексти для друку перед і після QR-коду:

* messageBeforeQr - Текст перед QR-кодом
* messageAfterQr - Текст після QR-коду

Шаблон посилання для створення QR-коду для оплати рахунку за ID

**precheckQrUrl**: Шаблон посилання для створення QR-коду.

* Формат: <mark style="color:orange;">`https://mbnk.biz/{restaurant-code}/orderId_`</mark><mark style="color:blue;">`{orderId}`</mark>
* `base URL`: <mark style="color:orange;">`https://mbnk.biz/{restaurant-code}/orderId_`</mark>
* <mark style="color:blue;">`{orderId}`</mark>: Ідентифікатор рахунку, який підставляється POS-системою.


# Замовлення в меню

Операція дозволяє зробити замовлення самостійно в меню (без виклику офіціанта, або з номера у готелі)

<figure><img src="/files/2czDQgIwaPTmjmlz6oYq" alt=""><figcaption><p>Створення замовлення</p></figcaption></figure>

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

{% hint style="warning" %}
Для відкриття доступності функціоналу обов'язковою є умова відправки відповідних даних у [versionInfo](/api/messages/othercallback):

`{`

`"feature": "ORDER_ON_TABLE",`

`"available": true,`

`"implemented": true`

`}`
{% endhint %}

## Створення та оплата замовлення в меню

> Схема роботи команди `createOrderOnTable`

1. Перевірка чи вже існує подібне замовлення, у разі якщо це замовлення на якомусь з етапів було відхилене, або чи вже існує декілька подібних замовлень (що є результатом розділення замовлення за місцями оплати).
2. Якщо замовлення ще **не існує ->** перевіряємо наявність блюд-> якщо блюд немає -> отримуємо <mark style="color:red;">помилку.</mark>
3. Якщо замовлення ще **не існує ->** перевіряємо наявність блюд-> якщо наявність блюд підтверджується -> <mark style="color:green;">створюємо</mark> замовлення.
4. Якщо замовлення створено або існувало(и) -> намагаємось роздрукувати нероздруковані бігунки[^1].
5. Якщо замовлення має статус "`New`" або "`Bill`" - намагаємось сплатити його.

{% hint style="warning" %}
Якщо замовлення мають id від rootOrder, що виник у результаті розділення після попередньої спроби оплати, то спроба оплатити замовлення буде проходити через нього.
{% endhint %}

Expirenza приймає наступні стани(state) рахунку:

* `NEW` - Замовлення створено, ПреЧек не роздруковано
* `BILL`- Замовлення створено, ПреЧек роздруковано
* `PAYED-Замовлення сплачене`

Операції `getBill` та `payBill` не використовуються

> Опис параметрів запиту `createOrderOnTable`

<details>

<summary>Приклад запиту команди <code>createOrderOnTable</code></summary>

```json
{
    "operation": "createOrderOnTable",
    "rID": "manual16",
      
    "externalId": "003",
    "originName": "expz",
    "tableId":"aaabfb9b-ba7f-076e-0183-59bcbe5a0068",
    "items":[
  
        {
            "id":"428dc245-9112-4709-b007-c6dc8c2744f3",
            "quantity": 1.0,
            "modifiers": [
                {
                    "id": "f9a40cf6-7f4e-4086-8872-d0c165e59040",
                    "groupId":"3a72b59e-d5e3-4a2e-b634-1bc1cbf7432e",
                    "quantity": 1
                }
            ]
        }
    ]
  },
  "fiscalData": [
    {
      "key": "ЕКВАЙЕР",
      "value": "Universal Bank"
    },
    {
      "key": "ТЕРМІНАЛ"
    },
    {
      "key": "КОМІСІЯ",
      "value": "0 грн."
    },
    {
      "key": "ВИД ОПЕРАЦІЇ",
      "value": "Оплата"
    },
    {
      "key": "ЕПЗ",
      "value": "53754141******56"
    },
    {
      "key": "ПС",
      "value": "MC"
    },
    {
      "key": "RRN",
      "value": "010025711364"
    },
    {
      "key": "КОД. АВТ",
      "value": "319431"
    }
  ]
}
```

</details>

<table data-full-width="false"><thead><tr><th width="148">Name</th><th width="93" align="center">Type</th><th width="99" align="center">Required</th><th>Description</th></tr></thead><tbody><tr><td>operation</td><td align="center">String</td><td align="center">✔️</td><td>Назва команди</td></tr><tr><td>rID</td><td align="center">String</td><td align="center">✔️</td><td>Ідентифікатор запиту</td></tr><tr><td>externalId</td><td align="center">String</td><td align="center">✔️</td><td>Ідентифікатор запиту із зовнішньої системи</td></tr><tr><td>originName</td><td align="center">String</td><td align="center">✔️</td><td>Ідентифікатор зовнішньої системи</td></tr><tr><td>tableId</td><td align="center">String</td><td align="center">✔️</td><td>Ідентифікатор столу</td></tr><tr><td>items</td><td align="center">[object]</td><td align="center">✔️</td><td>Блюда</td></tr><tr><td>id</td><td align="center">String</td><td align="center">❌</td><td>Ідентифікатор</td></tr><tr><td>quantity</td><td align="center">Integer</td><td align="center">❌</td><td>Кількість</td></tr><tr><td>modifiers</td><td align="center">[object]</td><td align="center">❌</td><td>Модифікатори</td></tr><tr><td>id</td><td align="center">String</td><td align="center">✔️</td><td>Ідентифікатор модифікатору</td></tr><tr><td>groupId</td><td align="center">String</td><td align="center">❌</td><td>Ідентифікатор групи модифікатору, якщо модифікатору має групу</td></tr><tr><td>quantity</td><td align="center">Integer</td><td align="center">✔️</td><td>Кількість модифікаторів</td></tr><tr><td>fiscalData</td><td align="center">[object]</td><td align="center">❌</td><td>Дані для фіксального чеку</td></tr><tr><td>key</td><td align="center">String</td><td align="center">✔️</td><td></td></tr><tr><td>value</td><td align="center">String</td><td align="center">✔️</td><td></td></tr></tbody></table>

> Опис параметрів відповіді `createOrderOnTable`

{% hint style="info" %}
Відповідь направляти на <https://api.shaketopay.com.ua/callback/createOrderOnTable>
{% endhint %}

<details>

<summary>Приклад відповіді команди  <code>createOrderOnTable</code></summary>

```json

    "rID": "manual119",
    "result": {
        "success": true,
        "stage": "PAYED",
        "rootOrder": {
            "orderId": "a162cb7f-4edd-46a7-9824-4c5dfde4326f",
            "orderNumber": 372,
            "resultSum": 1450.5,
            "orderStatus": "Deleted",
            "tableNumber": 372,
            "waiterId": "123",
            "waiter": "John Doe"
        },
        "ordersSummary": [
            {
                "orderId": "b79b3997-7491-4518-91e0-a04a89a28437",
                "orderNumber": 373,
                "resultSum": 1100.0,
                "orderStatus": "Closed",
                "closed": "2023.04.12 16:17:14",
                "tableNumber": 1,
                "waiterId": "123",
                "waiter": "John Doe"
            },
            {
                "orderId": "6cc87f61-c6d4-4b7f-8a52-229102b09748",
                "orderNumber": 374,
                "resultSum": 350.5,
                "orderStatus": "Closed",
                "closed": "2023.04.12 16:17:15",
                "tableNumber": 1,
                "waiterId": "123",
                "waiter": "John Doe"
            }
        ],
        "guests": [
            {
                "name": "Гiсть",
                "dishes": [
                    {
                        "categoryId": "04e705cf-0f9f-36cd-0183-a2be58c00094",
                        "category": "Не фискальный",
                        "name": "Пицца - Маргарита",
                        "count": 2.0,
                        "sum": 1100.0,
                        "orderNumber": 373,
                        "type": "dish",
                        "dishId": "428dc245-9112-4709-b007-c6dc8c2744f3"
                    },
                    {
                        "categoryId": "-1",
                        "category": "Блюдо без категории",
                        "name": "Петрушка",
                        "count": 2.0,
                        "sum": 0.0,
                        "orderNumber": 373,
                        "type": "modifier",
                        "dishId": "f9a40cf6-7f4e-4086-8872-d0c165e59040"
                    }
                ]
            },
            {
                "name": "Гiсть",
                "dishes": [
                    {
                        "categoryId": "04e705cf-0f9f-36cd-0183-a2be58c00093",
                        "category": "Фискальный",
                        "name": "Kopke",
                        "count": 1.0,
                        "sum": 350.5,
                        "orderNumber": 374,
                        "type": "dish",
                        "dishId": "50391936-2733-48a1-980c-5b7a3c9635f6"
                    }
                ]
            }
        ]
    }
}
```

</details>

<table><thead><tr><th width="154">Name</th><th width="94" align="center">Type</th><th width="102" align="center">Required</th><th>Description</th></tr></thead><tbody><tr><td>rID</td><td align="center">string</td><td align="center">✔️</td><td><p>Ідентифікатор </p><p>запиту</p></td></tr><tr><td>result</td><td align="center">object</td><td align="center">✔️</td><td>none</td></tr><tr><td>success</td><td align="center">boolean</td><td align="center">✔️</td><td>Ознака успіху</td></tr><tr><td>stage</td><td align="center">string</td><td align="center">✔️</td><td><p>Можуть бути стани:<br>STARTED,CHECKED,CREATED,</p><p>PRINTED,PAYED,UNKNOWN_ERROR</p></td></tr><tr><td>paySubstate</td><td align="center">string</td><td align="center">❌</td><td>Під-статус з процесу оплати</td></tr><tr><td>errorMessage</td><td align="center">string</td><td align="center">❌</td><td>Сповіщення про помилку</td></tr><tr><td>rootOrder</td><td align="center">object</td><td align="center">✔️</td><td>Інформація про початкове замовлення</td></tr><tr><td>orderId</td><td align="center">string</td><td align="center">✔️</td><td>Ід замовлення</td></tr><tr><td>orderNumber</td><td align="center">integer</td><td align="center">✔️</td><td>Номер</td></tr><tr><td>resultSum</td><td align="center">number</td><td align="center">✔️</td><td>Сума замовлення</td></tr><tr><td>orderStatus</td><td align="center">string</td><td align="center">✔️</td><td>Статус</td></tr><tr><td>tableNumber</td><td align="center">integer</td><td align="center">✔️</td><td>Номер столу</td></tr><tr><td>waiterId</td><td align="center">string</td><td align="center">✔️</td><td>Ід офіціанта</td></tr><tr><td>waiter</td><td align="center">string</td><td align="center">✔️</td><td>Ім'я офіціанта</td></tr><tr><td>ordersSummary</td><td align="center">[object]</td><td align="center">✔️</td><td>Інфо о замовленнях, отриманих у результаті оплати</td></tr><tr><td>orderId</td><td align="center">string</td><td align="center">✔️</td><td>ід</td></tr><tr><td>orderNumber</td><td align="center">integer</td><td align="center">✔️</td><td>Номер</td></tr><tr><td>resultSum</td><td align="center">integer</td><td align="center">✔️</td><td>Сума</td></tr><tr><td>orderStatus</td><td align="center">string</td><td align="center">✔️</td><td>Статус</td></tr><tr><td>closed</td><td align="center">string</td><td align="center">❌</td><td>Дата закриття</td></tr><tr><td>tableNumber</td><td align="center">integer</td><td align="center">✔️</td><td>Номер столу</td></tr><tr><td>waiterId</td><td align="center">string</td><td align="center">✔️</td><td>Ід офіціанта</td></tr><tr><td>waiter</td><td align="center">string</td><td align="center">✔️</td><td>Ім'я офіціанта</td></tr><tr><td>guests</td><td align="center">[object]</td><td align="center">✔️</td><td>Деталіровка</td></tr><tr><td>name</td><td align="center">string</td><td align="center">✔️</td><td>Ім'я гостя</td></tr><tr><td>dishes</td><td align="center">[object]</td><td align="center">✔️</td><td>Позиції замовлення</td></tr><tr><td>categoryId</td><td align="center">string</td><td align="center">✔️</td><td>Ід категорії</td></tr><tr><td>category</td><td align="center">string</td><td align="center">✔️</td><td>Категорія</td></tr><tr><td>name</td><td align="center">string</td><td align="center">✔️</td><td>Найменування  блюда</td></tr><tr><td>count</td><td align="center">integer</td><td align="center">✔️</td><td>Кількість</td></tr><tr><td>sum</td><td align="center">integer</td><td align="center">✔️</td><td>Сума</td></tr><tr><td>orderNumber</td><td align="center">integer</td><td align="center">✔️</td><td>Номер замовлення</td></tr><tr><td>type</td><td align="center">string</td><td align="center">✔️</td><td>Тип блюда</td></tr><tr><td>dishId</td><td align="center">string</td><td align="center">✔️</td><td>Код блюда</td></tr></tbody></table>

***

## Перевірка наявності блюд

Дана команда потрібна для попередньої перевірки наявності блюд у POS-системі, перед створенням інвойсу.&#x20;

{% hint style="info" %}
Приклад: Блюдо за якихось причин (як приклад:  у POS-ситемі блюдо знаходиться у stop-list) не доступне до замовлення, виключити ситуацію коли гість закладу оплачує замовлення, а ресторан не може приготувати дану страву.
{% endhint %}

> Логіка роботи команди checkProductsRestrictions

1. Якщо в позиції є modifiers, то визначаємо їх загальну кількість.
   1. Кількість = кількість модифікаторів у позиції \* кількість страв, до якого прив'язан `modifiers`
2. Перевіряємо доступність блюд для замовлення і записуємо недостатню кількість у `exceedQuantity`
3. Якщо exceedQuantity  = 0, то available = <mark style="color:green;">true.</mark>
4. Якщо exceedQuantity  > 0, то available = <mark style="color:red;">false.</mark>

> Опис команди - checkProductsRestrictions

<details>

<summary>Приклад запиту команди <code>checkProductsRestrictions</code></summary>

```json
{
    "operation": "checkProductsRestrictions",
    "rID": "manual16",
     
    "items":[
        {
            "id":"428dc245-9112-4709-b007-c6dc8c2744f3",
            "quantity": 1.0,
            "modifiers": [
                {
                    "id": "f9a40cf6-7f4e-4086-8872-d0c165e59040",
                    "quantity": 1
                }
            ]
        }
    ]
}
```

</details>

<table><thead><tr><th>Name</th><th>Type</th><th width="135" align="center">Required</th><th>Description</th></tr></thead><tbody><tr><td>rID</td><td>string</td><td align="center">✔️</td><td>Код запиту</td></tr><tr><td>items</td><td>[object]</td><td align="center">✔️</td><td>none</td></tr><tr><td>id</td><td>string</td><td align="center">✔️</td><td>Код блюда</td></tr><tr><td>quantity</td><td>integer</td><td align="center">✔️</td><td>Кількість</td></tr><tr><td>modifiers</td><td>[object]</td><td align="center">❌</td><td>Модифікатори </td></tr><tr><td>id</td><td>string</td><td align="center">✔️</td><td>Код блюда</td></tr><tr><td>quantity</td><td>integer</td><td align="center">✔️</td><td>Кількість</td></tr></tbody></table>

> Опис параметрів відповіді checkProductsRestrictions

{% hint style="info" %}
Відповідь направляти на <https://api.shaketopay.com.ua/callback/checkProductsRestrictions>
{% endhint %}

<details>

<summary>Приклад відповіді команди <code>checkProductsRestrictions</code></summary>

```json
{
    "rID": "manual16",
    "result": {
        "checkResult": "Allowed",
        "itemResults": [
            {
                "id": "428dc245-9112-4709-b007-c6dc8c2744f3",
                "name": "Пицца - Маргарита",
                "available": true,
                "exceedQuantity": 0.0
            },
            {
                "id": "f9a40cf6-7f4e-4086-8872-d0c165e59040",
                "name": "Петрушка",
                "available": true,
                "exceedQuantity": 0.0
            }
        ]
    }
}
```

</details>

<table><thead><tr><th>Name</th><th>Type</th><th width="137" align="center">Required</th><th>Description</th></tr></thead><tbody><tr><td>result</td><td>object</td><td align="center">✔️</td><td>none</td></tr><tr><td>rID</td><td>string</td><td align="center">✔️</td><td>Ідентификатор запиту</td></tr><tr><td>checkResult</td><td>string</td><td align="center">✔️</td><td>Результат перевірки . Можливі значення описано <a href="https://iiko.github.io/front.api.sdk/v7/html/T_Resto_Front_Api_Data_Orders_ProductsSellingPossibility.htm">тут.</a></td></tr><tr><td>itemResults</td><td>[object]</td><td align="center">✔️</td><td>none</td></tr><tr><td>available</td><td>boolean</td><td align="center">✔️</td><td>Ознака доступності</td></tr><tr><td>exceedQuantity</td><td>integer</td><td align="center">✔️</td><td>Недостатня кількість</td></tr><tr><td>id</td><td>string</td><td align="center">✔️</td><td>Код продукту (блюда або модифікатора)</td></tr><tr><td>name</td><td>string</td><td align="center">✔️</td><td>Найменування продукту</td></tr></tbody></table>

***

[^1]: *Бігунок* – замовлення, яке кухня отримує від офіціанта у вигляді роздрукованого на термопринтері чека.


# Розділення рахунку (Split Bill)

Для розділення рахунку необхідно відокремити окремий рахунок від оригінального замовлення з блюдами яки обрав гість для оплати.

## Процес розділення рахунку

Для індикації того що конкретний рахунок можна розділити, при передачі[ /callback/getBill](/api/messages/getbill#callback-getbill) параметр "`splitAvailable`" має містити значення <mark style="color:green;">`true`</mark>.\
Для коректної роботи сервісу при передачі[ /callback/getBill](/api/messages/getbill#callback-getbill) також має бути вказаний параметр `"positionId": "string"`

{% hint style="info" %}
**За замовчуванням** для ресторану ця функціональність вимкенна.&#x20;

Для її активації зверніться до аккаунт-менеджера що веде ресторан.
{% endhint %}

***

При розділенні рахунку, Expirenza надсилатиме наступне повідомлення:

<details>

<summary>splitOrder</summary>

```json
{
  
    "operation": "splitOrder",
    "rID": "manual16",
    "billId":"4afc3774-cc50-4e07-ad81-dd65f166244a",
    "controlSum":  1080.6,
    "positions": [
        {"id": "8e2ad560-938b-4972-ba60-8098aac99f8b", "quantity": 1},
        {"id": "c53e1948-7ffe-4dea-8e25-9e6773fa8768", "quantity": 1},
        {"id": "0e857f96-d53b-4649-bae0-0674c6d59496", "quantity": 1}
    ]
}
```

</details>

При створенні нового рахунку необхідно:

1. Перенести потрібні позиції
2. Скопіювати знижки (за наявності) в створене замовлення
3. Скопіювати деталі оригінального замовлення:
   * Номер столу
   * Офіціант
   * Тип замовлення

У відповідь в коллбек ми очікуємо 2 рахунки (orders): \
1\) "Parent" - нова версія рахунку після відокремлення страв\
2\) Дочірній об'єкт - те що обрав юзер при розділенні рахунку.

Відповідь обробки операції необхідно надіслати в наступному вигляді, відповідь аналогічна getBill:

{% openapi src="/files/FP4fnp4a478jKwiQabat" path="callback/splitOrder" method="post" %}
[splitOrder03.02.2024\_updated.json](https://115752690-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUrrjxJkhEuwfb0dGwW06%2Fuploads%2FZ188DbP7FKbdFUM7RcZK%2FsplitOrder03.02.2024_updated.json?alt=media\&token=2afa3e86-08f0-49fd-8387-0f80bd0065db)
{% endopenapi %}

<details>

<summary><strong>Payload example: <code>/callback/splitOrder</code></strong></summary>

{% code fullWidth="true" %}

```json
{
    "rID": "manual16",
    "state": "SUCCESS",
    "tableNumber": 1,
    "orders": [
        {
            "billId": "4afc3774-cc50-4e07-ad81-dd65f166244a",
            "orderNumber": 460,
            "totalSum": 720.4,
            "rawSum": 721.0,
            "discounts": {
                "list": [
                    {
                        "id": "4c1e2f7c-09b2-479e-90f9-5e4f67d2665d",
                        "name": "Знижка",
                        "sum": 0.6
                    }
                ]
            },
            "waiterId": "4f433631-2e15-4f05-8a70-e63eda55ce41",
            "waiter": "test",
            "guests": [
                {
                    "name": "Гость 1",
                    "dishes": [
                        {
                            "categoryId": "-1",
                            "category": "Блюдо без категорії",
                            "positionId": "aaa85a2d-8ea4-434a-a235-666bcc0c2d07",
                            "name": "Гриби",
                            "count": 2.0,
                            "sum": 0.0,
                            "orderNumber": 460,
                            "type": "dish",
                            "dishId": "f791662d-e104-4f24-a16a-643d392b7c51"
                        },
                        {
                            "categoryId": "-1",
                            "category": "Блюдо без категорії",
                            "positionId": "9319918b-3582-4de7-b678-4249be2acdcb",
                            "name": "Куриця",
                            "count": 3.0,
                            "sum": 0.0,
                            "orderNumber": 460,
                            "type": "dish",
                            "dishId": "5ea84688-bc1b-4cb1-a107-833f46cbf9cb"
                        },
                        {
                            "categoryId": "-1",
                            "category": "Блюдо без категорії",
                            "positionId": "d8bd2fd9-37ec-4017-9ba8-da686daf57cf",
                            "name": "*",
                            "count": 2.0,
                            "sum": 0.0,
                            "orderNumber": 460,
                            "type": "dish",
                            "dishId": "8edb5f44-969b-4a86-9a78-32c5a5dfba8f"
                        },
                        {
                            "categoryId": "-1",
                            "category": "Блюдо без категорії",
                            "positionId": "a1954115-dc8d-460a-8de5-e6973fe030d0",
                            "name": "Кукурудза",
                            "count": 2.0,
                            "sum": 19.4,
                            "orderNumber": 460,
                            "type": "dish",
                            "dishId": "cf56075a-c4a9-47a4-a279-2284e26afe0b"
                        },
                        {
                            "categoryId": "04e705cf-0f9f-36cd-0183-a2be58c00093",
                            "category": "Фіскальний",
                            "positionId": "d4d3e228-c093-4fc3-8101-d7f8fa8612be",
                            "name": "Kopke",
                            "count": 2.0,
                            "sum": 701.0,
                            "orderNumber": 460,
                            "type": "dish",
                            "dishId": "50391936-2733-48a1-980c-5b7a3c9635f6"
                        }
                    ]
                }
            ],
            "state": "New",
            "tableId": "aaabfb9b-ba7f-076e-0183-59bcbe5a0068",
            "isBanquetOrder": false,
            "isDelivery": false,
            "created": "2023.10.02 14:10:56",
            "bonusSum": 0.0
        },
        {
            "billId": "a11ecd3a-0fa3-4db1-88d6-975cf83da0fb",
            "orderNumber": 461,
            "totalSum": 360.2,
            "rawSum": 360.5,
            "discounts": {
                "list": [
                    {
                        "id": "4c1e2f7c-09b2-479e-90f9-5e4f67d2665d",
                        "name": "Знижка",
                        "sum": 0.3
                    }
                ]
            },
            "waiterId": "4f433631-2e15-4f05-8a70-e63eda55ce41",
            "waiter": "test",
            "guests": [
                {
                    "name": "Гiсть",
                    "dishes": [
                        {
                            "categoryId": "-1",
                            "category": "Блюдо без категорії",
                            "positionId": "8e2ad560-938b-4972-ba60-8098aac99f8b",
                            "name": "*",
                            "count": 1.0,
                            "sum": 0.0,
                            "orderNumber": 461,
                            "type": "dish",
                            "dishId": "8edb5f44-969b-4a86-9a78-32c5a5dfba8f"
                        },
                        {
                            "categoryId": "-1",
                            "category": "Блюдо без категорії",
                            "positionId": "c53e1948-7ffe-4dea-8e25-9e6773fa8768",
                            "name": "Кукурудза",
                            "count": 1.0,
                            "sum": 9.7,
                            "orderNumber": 461,
                            "type": "dish",
                            "dishId": "cf56075a-c4a9-47a4-a279-2284e26afe0b"
                        },
                        {
                            "categoryId": "04e705cf-0f9f-36cd-0183-a2be58c00093",
                            "category": "Фіскальний",
                            "positionId": "0e857f96-d53b-4649-bae0-0674c6d59496",
                            "name": "Kopke",
                            "count": 1.0,
                            "sum": 350.5,
                            "orderNumber": 461,
                            "type": "dish",
                            "dishId": "50391936-2733-48a1-980c-5b7a3c9635f6"
                        }
                    ]
                }
            ],
            "state": "New",
            "tableId": "aaabfb9b-ba7f-076e-0183-59bcbe5a0068",
            "isBanquetOrder": false,
            "isDelivery": false,
            "created": "2023.10.02 14:23:45",
            "bonusSum": 0.0
        }
    ]
}
```

{% endcode %}

</details>

<details>

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

Q. Як відпрацьовується ситуація, коли одну і ту ж позицію забрали різні гості?

A. Хто перший забрав позицію - той і оплачує. Решта гостей отримають помилку.

***

Q. Чи можна поділити блюдо по 0.5 на гостя? Приклад: Один салат розділити на двох.

A. На цей час це зробити не можливо

</details>


# Отримання стоп-листів

Сервіс для передачі страв, які знаходяться у stop-list POS-системи.

{% hint style="warning" %}
Наш backend завжди очікує на нові стоп лісти.\
При реалізції стоп-лістів:\
1\. Якщо стоп ліст змінився - відправляти **обов'язково**  не частіше ніж раз на 15 секунд.\
2\. Якщо змін не було - відправляти **обов'язково** раз на 15 хвилин.
{% endhint %}

{% openapi src="/files/LMMt9NnKD657YY5BF3er" path="/callback/webhook" method="post" %}
[stopList - Copy.json](https://115752690-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUrrjxJkhEuwfb0dGwW06%2Fuploads%2Fbw1SBFGzhTPDTaaMta3U%2FstopList%20-%20Copy.json?alt=media\&token=801d2093-dcfb-4fda-9d3e-8e169015dddc)
{% endopenapi %}

<details>

<summary>Payload example: /callback/webHook</summary>

```json
{
"webhookType":"STOP_LIST",
"items":[
  {"productId":"1004477","balance":0.000},
  {"productId":"1004629","balance":0.000}
 ]
}
```

</details>

***

{% hint style="danger" %}
Виклик **/callback/stopList** вважається **Deprecated** і буде видалений в майбутньому
{% endhint %}

<details>

<summary>Payload example: /callback/stopList</summary>

```
{
  "items": [
    {
      "balance": 0,
      "productId": "dcd53ddb-8104-4e48-8cc0-5df1088c6113"
    }
  ],
  "rID": "2021-04-01 09:39:06.021078#BpOI0gO"
}
```

</details>


# Повідомлення у POS-систему

Expirenza може відправляти повідомлення у POS-систему для відображення їх у інтерфейсі.

Для отримання повідомлень дотстатньо реалізувати команду "operation":"showMessage"

Команда відправляється з серверу, коли отримаєте команду -> можно відображати у себе в інтерфейсі.

<table><thead><tr><th width="123">Name</th><th width="99">Value</th><th>Description</th></tr></thead><tbody><tr><td>rId</td><td>string</td><td>Ідентифікатор запиту</td></tr><tr><td>message</td><td>string</td><td>Повідомлення яке треба показати в POS-системі</td></tr><tr><td>warning</td><td>booleon</td><td></td></tr><tr><td>billId</td><td>string</td><td>id рахунку (може бути null якщо повідмолення не стосується конкретного рахунку)</td></tr><tr><td>operation</td><td>string</td><td>Команда, яка означає що прийшло повідомлення від Expirenza</td></tr></tbody></table>

{% code title="Приклад повідомлення" %}

```json
{
   "rID":"aa61d473a08e41a9b52a5a66fb959999",
   "message":"УВАГА! Адміністратор Адмінаістратор повернув оплату рахунків [32070] гостю. Будь ласка, переконайтесь, що ці рахунки позначені неоплаченими у вашій системі обліку.",
   "warning":false,
   "billId":"8327brrr-201f-1f11-1f11-8b7d239d4949",
   "operation":"showMessage"
}
```

{% endcode %}


# Кешування рахунків

Кешування рахунків пидвищує швидкодію в отриманні рахунку для гостя. Expirenza віддає рахунок з "власного кеша", замість того щоб робити запити до POS.

Процес виглядає так:

{% hint style="info" %}

1. POS система раз в 5 секунд відправляє інформацію з замовленнями що зараз відкриті в POS на cервер Expirenza:&#x20;

&#x20;       Короткий перелік всіх замовлень

&#x20;       Повна інфо про замовлення що змінились з моменту останнього оновлення

2. Сервер може запитати  у ПОС детальне інфо про будь яке з замовлень у будь який момент.&#x20;

&#x20;       Пос система має відправити їх повне інфо з наступним вебхуком [ORDERS\_CACHE](https://app.gitbook.com/o/wbtQQV2rcEmzhjC4NRPf/s/UrrjxJkhEuwfb0dGwW06/~/changes/221/api/messages/keshuvannya-rakhunkiv#api.shaketopay.com.ua-callback-webhook)

3. Про закриті замовлення ПОС система сповіщає сервер [окермим вебхуком](https://app.gitbook.com/o/wbtQQV2rcEmzhjC4NRPf/s/UrrjxJkhEuwfb0dGwW06/~/changes/221/api/messages/keshuvannya-rakhunkiv#api.shaketopay.com.ua-callback-webhook-1)
   {% endhint %}

***

{% hint style="warning" %}
Раз на 5 секунд необхідно відправляти інформацію про всі замовлення в стані New (нове) або Bill (надруковано пречек). \
Якщо сервер не отримує вебхук протягом 15 секунд - вважає замовлення неактуальними.\
Віддавати треба замовлення що є на столі, так і пусті замовлення, а також ті що змінились з моменту останнього оновлення.
{% endhint %}

{% hint style="warning" %}
Потребує реалізації `linkedTo` та `positionId`  у [getBill](https://docs.expirenza.com/api/messages/pages/Y1Db8UFuSpso50MKt5FW#/rozyasnennya-po-linkedto). \
Після необхідно додати в [versionInfo](/api/messages/othercallback) в `implementedFeature` відповідний об'єкт реалізованого функціоналу - BILL\_V2 та ORDERS\_CACHE.
{% endhint %}

{% openapi src="/files/LAcPeGgn7QToMOvgdKYJ" path="//api.shaketopay.com.ua/callback/webhook" method="post" %}
[ordersCache03.02.24\_updated.json](https://115752690-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUrrjxJkhEuwfb0dGwW06%2Fuploads%2FL6QOcFQucS6aYWdC0JyK%2FordersCache03.02.24_updated.json?alt=media\&token=920ad709-6eb4-4736-85aa-ec19656850d8)
{% endopenapi %}

<details>

<summary>Payload example <code>/callback/webhook</code></summary>

```json
{
    "webhookType": "ORDERS_CACHE",
    "eventTime":"timestamp UTC"
    "actualOrders": [
        {
            "orderId": "079D89A0-5BEF-4BCC-A279-2566D5FBAEAA",
            "revision": 2
        },
        {
            "orderId": "A9D1D59E-DBE5-423F-82C8-95C14FEA97BD",
            "revision": 2
        }
    ],
    "changedOrders": [
        {
            "orderInfo": {
                "billId": "A9D1D59E-DBE5-423F-82C8-95C14FEA97BD",
                "orderNumber": "11.3",
                "totalSum": 77.40, //загальна сумма до сплати
                "rawSum": 86.00, // сумма до сплати без урахування знижки
                "paidSum": 0, //сплачена сумма
                "discountSum": 8.60, // сумма знижки
                "waiter": "TEST",
                "waiterId": "1000004",
                "billAmountForTips": 123.35,
                "discounts": {
                    "list": [
                        {
                            "id": "1002291",
                            "name": "Скидка 10% на чек",
                            "sum": 8.60,
                            //нижче будь які інші поля з інформацією про знижку
                            "code": 6
                        }
                    ]
                },
                "guests": [
                    {
                        "name": "Гість 1",
                        "id": "8436f6ff-6665-44de-a863-8be3352cb7d2", //ід гостя
                        "additionalInfo": {
                            "system": "syrve",
                            "comment": "some guest comment"
                        },
                        "dishes": [
                            {
                                "positionId": "4",
                                "name": "Combo salatov",
                                "count": 1.000,
                                "sum": 0.00,
                                "categoryId": -1,
                                "category": "Блюдо без категории",
                                "orderNumber": "11.3",
                                "type": "combo",
                                "dishId": "1002281",
                                "rawSum": 0.00,
                                "price": 86.00 //ціна за 1
                            },
                
                                        {
                                "positionId": "7",
                                "name": "Томатный холодный суп",
                                "count": 1.000, //загальна кількість дочірніх страв з урахуванням кількості батьківської страви
                                "positionCount": 1.000, //кількість дочірніх страв в рамках 1 позиції (null для тих у кого linkedTo - null)
                                "sum": 27.00,
                                "categoryId": -1,
                                "category": "Блюдо без категории",
                                "orderNumber": "11.3",
                                "type": "dish", //dish/modifier/combo
                                "dishId": "1002099",
                                "rawSum": 30.00, //сумма дочірніх страв без урахування знижок та з урахуванням кількості батьківських страв 
                                "positionRawSum": 30.00, //сума дочірніх страв без урахування знижок для 1 батьківської страви
                                "linkedTo": "4", //positionId страви до якої цю страву
                                "price": 30.00 //результуюча ціна за 1
                            },
                            {
                                "positionId": "13",
                                "name": "Salat iz anacond",
                                "count": 1.000000,
                                "positionCount": 1.000,
                                "sum": 50.40,
                                "categoryId": -1,
                                "category": "Блюдо без категории",
                                "orderNumber": "11.3",
                                "type": "dish",
                                "dishId": "1001946",
                                "rawSum": 56.00000,
                                "positionRawSum": 56.00,
                                "linkedTo": "4",
                                "price": 56.00
                            },
                            {
                                "positionId": "16",
                                "name": "Персиковый",
                                "count": 1.000000,
                                "positionCount": 1.000,
                                "sum": 0.00,
                                "categoryId": -1,
                                "category": "Блюдо без категории",
                                "orderNumber": "11.3",
                                "type": "modifier",
                                "dishId": "1001759",
                                "rawSum": 0.00,
                                "positionRawSum": 0,
                                "linkedTo": "13",
                                "price": 12.00,
                                "additionalInfo": {
                                    "system": "syrve",
                                    "comment": "string",
                                    "status": "added",
                                    "productGroupExternalId": "for modifiers only"//ид группы модификаторов
                                }
                            }
                        ]
                    }
                ],
                "state": "New",//New/Bill/Closed/Deleted
                "isDelivery": false,
                "splitAvailable": true,
                "version": 2, //version = revision 
                "payments": [
                    {
                        "sum": 0,
                        "paymentTypeName": "string",
                        "paymentTypeKind": "Card",//Card/Cash і тд
                        "additionalInfo": {
                            "system": "syrve",
                            "isPrepay": true,
                            "isExternal": true,
                            "status": "new",
                            "externalId": "string",
                            "typeId": "string"
                        }
                    }
                ],
                "orderType": "Common", // Common - обычные/DeliveryByClient - самовывоз/DeliveryByCourier
                "additionalInfo": {
                    "system": "posName",
                    "tablesDetails": [
                        {
                            "externalId": "string",
                            "name": "string",
                            "fullName": "string",
                            "number": 21,
                            "seatingCapacity": 0,
                            "description": "string",
                            "isActive": true
                        }
                    ],
                    "waiterDetails": {
                        "externalId": "string",
                        "name": "string",
                        "phone": "string",
                        "pinCode": "string"
                    }
                },
                "tableId": "1000051",
                "created": "2024.09.30 13:47:57",
                "banquetOrder": false
            },
            "tables": [ //столи на яких розміщено замовлення
                11
            ]
        }
    ]
}
```

</details>

<details>

<summary>Роз'яснення і деталі.</summary>

Вебхук має 2 додаткових поля:

\
”`eventTime`” - дата формування івенту в UTC таймзоні\
"*`actualOrders`* " - поточні активні замовлення в системі\
"`orderId`" - id замовлення\
"`revision`" - **long** версія замовлення, інкрементальне значення, дає зрозуміти системі поточну “версію замовлення”. Значення має збільшуватись при кожній зміні замовлення. Обмежень на крок або значення немає. Якщо в ПОС відсутне поняття версії, то можна віддавати у якості значення дату останньої зміни замовлення в мілісекундах\
\
"*`changedOrders`" -* Список замовлень що змінились з моменту останньої відправки вебхука\
"`orderInfo`" - оновленний стан про замовлення

</details>

***

## Команда `ordersCacheUpdate`

Команда надсилається з сервера Expirenza в вебсокет, сервер надсилає перелік замовлень по яким треба обов'язково передати розгорнуту інформацію в при наступному виклику /calback/webhook (Той що `ORDERS_CACHE`).

Відповідати на команду не потрібно.

Команда використовується для синхронізації з інтеграцією у випадку якщо сервер не отримав один або декілька вебхуків і ревізія замовлень які присилає інтеграція відрізняється від тих що є на сервері, сервер “просить” надіслати замовлення по яким є втрачені зміни ще раз.

Сервер надсилатиме повідомлення в такому форматі:&#x20;

```json
{
    "operation":"ordersCacheUpdate",
    "rID":"7e70fb9f257e459d8fc8dd609b7d23fc",
    "orders":["14392","14386","14396","14400"]
}
```

***

## Вебхук фінального статусу замовлення

Структура самого замовлення не відрізняється від `ORDERS_CACHE`, відрізняється лише назва деяких полів.

Необхідно відправляти при отриманні фінального статуса по рахунку (Closed/Deleted)\
Якщо сервер не відповів 200, необхідно повторити відправку через деякий час \~1-5 хвилин.

{% openapi src="/files/J1rkfQU77Jm2RwQ2jC2m" path="//api.shaketopay.com.ua/callback/webhook" method="post" %}
[bill closed.json](https://115752690-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUrrjxJkhEuwfb0dGwW06%2Fuploads%2F8RBfieOH06GDiCw87D1i%2Fbill%20closed.json?alt=media\&token=afef6213-faf1-4454-9795-32194e635e0d)
{% endopenapi %}

<details>

<summary>Payload example <code>/callback/webhook</code></summary>

```json
{
    "webhookType": "BILL_CLOSED",
    "eventTime": "2024-09-30T15:29:04.9036828Z",
    "orderId": "492fa768-2fb0-4b30-9f5a-db9c17db3fff",
    "tableNumber": 1,
    "closeTime": "2024.09.30 18:28:59",
    "openTime": "2024.09.30 18:27:46",
    "orderNumber": 133264,
    "resultSum": 140.00,
    "orderStatus": "Closed",
    "totalSum": 140.00,
    "waiterId": "0ab41df0-f4ae-4fbe-959f-ecaba7c85c85",
    "waiter": "Максимейко Наталія",
    "discounts": {
        "list": [
            {
                "id": "1002291",
                "name": "Скидка 10% на чек",
                "sum": 8.60,
                //нижче будь які інші поля з інформацією про знижку
                "code": 6
            }
        ]
    },
    "guests": [
        {
            "name": "Гість 0",
            "id": "91ed5c34-85b2-4c54-a001-0f9e040d0004",
            "dishes": [
                {
                    "taxCategoryId": null,
                    "taxCategory": null,
                    "positionId": "127aaa1a-7fce-4ddc-95af-7af102eecc08",
                    "name": "Макаронс ",
                    "count": 1.0,
                    "sum": 70.00,
                    "price": 70.00,
                    "categoryId": "2e2e28fc-bbfd-ee15-018f-9687de9ed540",
                    "category": "Десерти Кебчук",
                    "orderNumber": 133264,
                    "type": "dish",
                    "dishId": "68591915-9a42-4fe8-84fa-a10a9fbbd6a2",
                    "linkedTo": null,
                    "rawSum": 70.00,
                    "additionalInfo": {
                        "system": "syrve",
                        "course": 1,
                        "comment": null,
                        "status": "Served",
                        "productGroupExternalId": null
                    }
                },
                {
                    "taxCategoryId": null,
                    "taxCategory": null,
                    "positionId": "5a9d658b-df19-4d38-96b1-41862d51db1d",
                    "name": "Лате",
                    "count": 1.0,
                    "sum": 10.00,
                    "price": 10.00,
                    "categoryId": "2e2e28fc-bbfd-ee15-018f-9687de9ed18d",
                    "category": "Бар ",
                    "orderNumber": 133264,
                    "type": "dish",
                    "dishId": "99295f7e-255d-46cf-ba76-2c340e1ba990",
                    "linkedTo": null,
                    "rawSum": 10.00,
                    "additionalInfo": {
                        "system": "syrve",
                        "course": 1,
                        "comment": null,
                        "status": "Served",
                        "productGroupExternalId": null
                    }
                },
                {
                    "taxCategoryId": null,
                    "taxCategory": null,
                    "positionId": "b059c0bb-e500-4c81-920c-62a83bfb7abc",
                    "name": "- Молоко",
                    "count": 1.0,
                    "sum": 50.00,
                    "price": 50.0000,
                    "categoryId": "2e2e28fc-bbfd-ee15-018f-9687de9ed18d",
                    "category": "Бар ",
                    "orderNumber": 133264,
                    "type": "modifier",
                    "dishId": "6b98a6de-f14f-4d9d-99a4-4feacc99bbec",
                    "linkedTo": "5a9d658b-df19-4d38-96b1-41862d51db1d",
                    "rawSum": 50.00,
                    "additionalInfo": {
                        "system": "syrve",
                        "course": null,
                        "comment": null,
                        "status": null,
                        "productGroupExternalId": "7d81b3a9-5339-4a10-be56-8f1a034ebe57"
                    }
                },
                {
                    "taxCategoryId": "42fe1bf4-fcd8-4f0b-9261-ee2952a2dd68",
                    "taxCategory": "Без НДС (0%)",
                    "positionId": "1bc7fafd-2bc3-401f-a8bc-2917aced1987",
                    "name": "- з собою 350 К",
                    "count": 1.0,
                    "sum": 0.00,
                    "price": 0.0000,
                    "categoryId": "-1",
                    "category": "Блюдо без категории",
                    "orderNumber": 133264,
                    "type": "modifier",
                    "dishId": "8e657ffc-0343-4429-a7cd-6f1463a919ce",
                    "linkedTo": "5a9d658b-df19-4d38-96b1-41862d51db1d",
                    "rawSum": 0.00,
                    "additionalInfo": {
                        "system": "syrve",
                        "course": null,
                        "comment": null,
                        "status": null,
                        "productGroupExternalId": "8fae65e1-27da-4d51-9f4a-e5fe47391e8b"
                    }
                },
                {
                    "taxCategoryId": null,
                    "taxCategory": null,
                    "positionId": "eccd76a0-1148-4d8c-b442-5b367cea38c0",
                    "name": "Солона карамель 25г ",
                    "count": 1.0,
                    "sum": 10.00,
                    "price": 10.00,
                    "categoryId": "2e2e28fc-bbfd-ee15-018f-9687de9ed18d",
                    "category": "Бар ",
                    "orderNumber": 133264,
                    "type": "dish",
                    "dishId": "ee7f8427-65e5-4ba3-aeb0-a9979e5f8552",
                    "linkedTo": null,
                    "rawSum": 10.00,
                    "additionalInfo": {
                        "system": "syrve",
                        "course": 1,
                        "comment": null,
                        "status": "Served",
                        "productGroupExternalId": null
                    }
                }
            ]
        }
    ],
    "isBanquetOrder": false,
    "isDelivery": false,
    "bonusSum": 0.0,
    "splitAvailable": false,
    "rewardAvailable": true,
    "billTime": "2024.09.30 18:28:59",
    "paidSum": 140.00,
    "discountSum": 0.0,
    "tableId": "e6ad6ef3-bbdb-41c4-8fd3-dd0691142074",
    "pricingTime": null,
    "version": 1865768,
    "payments": [
        {
            "paymentTypeName": "Готівка",
            "sum": 140.00,
            "paymentTypeKind": "Cash",
            "additionalInfo": {
                "system": "syrve",
                "externalId": "5b28a833-ba81-41d9-83a2-2cef3189d882",
                "status": "Processed",
                "typeId": "09322f46-578a-d210-add7-eec222a08871",
                "isPrepay": false,
                "isExternal": false
            }
        }
    ],
    "additionalInfo": {
        "system": "syrve",
        "tablesDetails": [
            {
                "externalId": "e6ad6ef3-bbdb-41c4-8fd3-dd0691142074",
                "name": "",
                "fullName": null,
                "number": 1,
                "seatingCapacity": 0,
                "description": null,
                "isActive": true
            }
        ],
        "waiterDetails": [
            {
                "externalId": "0ab41df0-f4ae-4fbe-959f-ecaba7c85c85",
                "name": "Максимейко Наталія",
                "phone": "+380997716858",
                "pinCode": "АК00-00043"
            }
        ]
    },
    "orderType": "Common"
}
```

</details>


# Результати інших повідомлень від POS системи

{% openapi src="/files/0jPdlguIBEiVFdbik6HT" path="//api.shaketopay.com.ua/callback/versionInfo" method="post" %}
[versionInfoNew2.json](https://115752690-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUrrjxJkhEuwfb0dGwW06%2Fuploads%2Fc2aGRcn0OTYOKa6BEZdr%2FversionInfoNew2.json?alt=media\&token=becb0d5f-b59d-4d7c-adc8-80644b982f70)
{% endopenapi %}

<details>

<summary>Payload example /callback/versionInfo:</summary>

```json
{
    "eventTime": "2024-10-06T23:01:01.453026800Z",
    "partnerId": "17f71563-bcd5-4194-b973-a2183739b32c",
    "rID": "bfe786d3ec61467ab7a17d747e7341d9",
    "updateInfo": [],
    "pluginVersion": 201,
    "additionalInfo": { // Сюди можна додати будь яку інформацію яку інтеграція вважає важливою до відправки.Приклад:
            "info": "Коннект до ресторану о 09:12"
    },
    "restaurantVersion": "7.7.0.212",
    "implementedFeatures": [
      {
        "feature": "BILL_V_2",
        "available": true, //Oзнака що цей функціонал налаштований (якщо це необхідно). Якщо функціонал доступний без додаткових налаштувань - передавати true
        "implemented": true //Oзнака що це функціонал реалізовано в поточній версії плагіну
      },
      {
        "feature": "STOP_LIST",
        "available": true,
        "implemented": true
      },
      {
        "feature": "ORDERS_CACHE",
        "available": true,
        "implemented": true
      },
      {
        "info": {
          "orderTypeCode": 1
        },
        "feature": "ORDER_ON_TABLE",
        "available": true,
        "implemented": true
      }
    ],
    "restaurantLicenseDateEnd": "2024.12.31"
  }


/*
 * implementedFeatures - показує реалізовані фічі в поточній версії плагіну
 * availableFeatures - показує фічі які готові до використання на поточний момнет
 *BILL_V_2, - тут ми маємо на увазі - відображення модифікаторів в чеку
 *STOP_LIST, - педача стоп лістів
 *ORDERS_CACHE - кешування рахунків
 *ORDER_ON_TABLE - замовлення за столом
 * Наприклад:
 * Функціонал замовлення за столом в ПО Rkeeper доступний з 130 версії плагіну,
 * але для того що б він працював корректно, необхідне його налаштування на кассовому сервері.
 * Об'єкт
 *  feature - ORDER_ON_TABLE
 *  implemented - true
 *  available - false
 *  info - {
 *      cashierSet:true,
 *      paymentTypeSet:false
 *  }
 *  повідомляє нам що замовлення за столом реалізовано в поточній версії плагіну, але не налаштовано тип оплати
 *  В поле info можна передати будь яку інформацію, в форматі Json.
 *  Якщо фунціонал не потребує додаткових налаштувань - передати available = implemented
 
```

</details>

***

{% openapi src="/files/2EglGLLqylx378Wjwcps" path="/callback/menuInfo" method="post" %}
[MenuInfo.json](https://115752690-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUrrjxJkhEuwfb0dGwW06%2Fuploads%2FD0qBHwcuzqbvCGNmoXf8%2FMenuInfo.json?alt=media\&token=1cf5982c-7cef-44ee-8dd4-db80ca3cca9e)
{% endopenapi %}

<details>

<summary>Payload example:/callback/menuInfo</summary>

{% code title="JSON" lineNumbers="true" fullWidth="false" %}

```json
{
   "dishes":[
      {
         "category":"string",
         "categoryId":"string",
         "description":"Фірмове блюдо",
         "groupId":"c6456aba-2f4e-410c-b2fe-03ae28896b98",
         "groupModifiers":[
            {
               "childModifiers":[
                  {
                     "defaultAmount":1,
                     "id":"d7f7b5cb-2675-4273-bd70-77ad6ec7977d",
                     "maxAmount":2,
                     "minAmount":1,
                     "required":false
                  }
               ],
               "childModifiersHaveMinMaxRestrictions":true,
               "defaultAmount":1,
               "free":true,
               "freeAmount":3,
               "id":"d7f7b5cb-2675-4273-bd70-77ad6ec7977d",
               "maxAmount":2,
               "minAmount":1,
               "required":false
            }
         ],
         "id":"9b4f3e6c-71b5-479f-88d5-61c6739c939a",
         "isActive":true,
         "menuSections":[
            "string"
         ],
         "modifierSchemeId":"string",
         "modifiers":[
            {
               "defaultAmount":1,
               "freeAmount":3,
               "id":"d7f7b5cb-2675-4273-bd70-77ad6ec7977d",
               "maxAmount":2,
               "minAmount":1,
               "required":false
            }
         ],
         "name":"Піца Гавайська",
         "price":5.1573,
         "scale":{
            "defaultSize":{
               "id":"string",
               "kitchenName":"string",
               "menuIndex":0,
               "name":"string"
            },
            "id":"string",
            "name":"string"
         },
         "taxCategory":"string",
         "taxCategoryId":"string",
         "type":"Dish",
         "unit":"кг.",
         "vendorCode":"string"
      }
   ],
   "groupModifiers":[
      {
         "id":"string",
         "name":"string"
      }
   ],
   "groups":[
      {
         "id":"c6456aba-2f4e-410c-b2fe-03ae28896b98",
         "menuIndex":3,
         "name":"Інші  страви",
         "parentId":"132d2699-a6ec-44fc-8ef7-8dd943990817"
      }
   ],
   "modifiers":[
      {
         "category":"string",
         "categoryId":"string",
         "description":"к нашему фирменному блюду",
         "groupId":"202f056a-6a35-46b4-8952-3508af724764",
         "id":"f14da21a-5be9-4736-9ece-420bd310bc8a",
         "isActive":true,
         "name":"Ветчина",
         "price":20.3629,
         "scale":{
            "defaultSize":{
               "id":"string",
               "kitchenName":"string",
               "menuIndex":0,
               "name":"string"
            },
            "id":"string",
            "name":"string"
         },
         "taxCategory":"string",
         "taxCategoryId":"string",
         "unit":"кг.",
         "vendorCode":"string"
      }
   ]
}
```

{% endcode %}

</details>

***


# Підключення за допомогою Postman

Перед початком підключення рекомендуємо ознайомитись з:

* [Документацією Postman](https://learning.postman.com/labs/postman-api-client/websocket-client/websocket-client-overview/) щодо використання WebSocket.

Для підключення через WebSocket використовується адреса:

```http
wss://api.shaketopay.com.ua/restaurantEntryPoint
```

***

## Авторизація

Передати у header параметр `Authorization` згенерований наступним чином:

"`Basic X`" - у якому `Х` це [`RESTO_ID:SECRET_KEY`](/api/integration/prepare) закодоване у base64.

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

{% hint style="success" %}
При вдалому підключенні має відобразитись 2 повідомлення у консоль Postman.
{% endhint %}

***

## Приклад запиту - отримання столів

> Перед обробкою запиту переконайтесь,що в Postman встановлено з'єднання по WebSocket.

Зайдіть в [Expirenza admin-panel](https://admin.expirenza.com) у вкладку "Столи та QR-коди "

Консоль Postman має відобразити наступне:

```json
{
    "rID": "2022-11-18 13:18:51.694125371#Lm4R2EQ",
    "operation": "tablesInfo"
}
```

**У окремій вкладці** Postman необхідно викликати [/callback/tablesInfo](/api/messages/tableinfo) упродовж 80 секунд.

На момент виклику [/callback/tablesInfo ](/api/messages/tableinfo)для форматування заголовку `signature` необхідно використати **Pre-request Script.**

<details>

<summary>Pre-request Script:/callback/tablesInfo</summary>

{% code title="JavaScript" lineNumbers="true" %}

```javascript
var key = "SECRET_KEY";
var body = request.data;
console.log("body ==>" + body);
var hash = CryptoJS.HmacSHA256(body, key);
console.log("hash: " + hash);
var result = hash.toString(CryptoJS.enc.Base64);
console.log("sign result: " + result);
pm.environment.set("signature", result);
```

{% endcode %}

</details>

<figure><img src="/files/yavVVkUAdh5mes7M4nrI" alt=""><figcaption><p>Pre-request Script</p></figcaption></figure>

У Body внести:

{% code title="JSON" lineNumbers="true" %}

```json
{
    "rID": "2022-11-18 13:20:58.329551967#IRuFbD3",
    "tables": [
        {
            "id": "xxx",
            "name": "у камина",
            "number": 12,
            "hallplanId": "Зала 1",
        }
    ]
}
```

{% endcode %}

`rID` - отримати з останнього повідомлення з типом надійшовшого `rID` [**у першій вкладці** Postman.](/api/postman#avtorizaciya)

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

Додати 2 заголовки у Headers:

* `restoId` - що є [RESTO\_ID](/api/integration/prepare).
* `signature` - що сформований у [Pre-request Script](/api/postman#pre-request-script-callback-tablesinfo).

<figure><img src="/files/EtMpAb4jx6hWUgbUUyoI" alt=""><figcaption><p>Headers</p></figcaption></figure>

***

## Завершення підключення за допомогою Postman

Якщо усі кроки були виконані коректно - в [Expirenza admin-panel](https://admin.expirenza.com) мають з'явитись столи зі сформованого раніше у Postman запиту.

<figure><img src="/files/S2ZadnsQ3lWPRBb4ML9H" alt=""><figcaption><p>Успішно передані столи</p></figcaption></figure>

***


# Поширені питання (FAQ)

## Q. Чому не підтягуються офіціанти у розділ "Платежі та чайові" ?  <a href="#waiters-not-display" id="waiters-not-display"></a>

A. Перевірте дані які відправляєте, а саме параметр "`cellPhone`" - він є обов'язковим.&#x20;

* Якщо передавати пустий параметр - офіціанти не будуть відображатись.
* Також `cellPhone` має бути валідним ( не вигаданим )
* Номер телефону потрібен для того, щоб офіціант міг підключити карту для чайових.     Тому для реальних офіціантів потрібний реальний номер телефону. ( Для тестових також )

***

## Q. Чому не відображаються категорії у розділі "Банківські рахунки" ? <a href="#categories-not-display" id="categories-not-display"></a>

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

A. Перевірте який "`type`" ви передаєте через [ /callback/categoriesInfo](/api/messages/categoriesinfo). `type` - має бути **виключно** `product`.

***

## Q. Які таймінги оновлення столів у адмінці Expirenza? <a href="#update-timings" id="update-timings"></a>

A. Столи оновлюються раз на добу за наявності підключення або при вході в адмін-панель Expirenza. Найменування столу оновлюється при першому попаданні столу у систему Expirenza.

***

## Q. Який порядок запитів до API? Коли саме потрібно зі сторони інтеграцій викликати яке API? <a href="#callback-orders" id="callback-orders"></a>

A. Інтеграції нічого не викликають. Expirenza викликає POS-систему, POS-система відповідає на запит

***

## Q. Як часто потрібно відповідати на запити від Expirenza? <a href="#how-oftern-respond" id="how-oftern-respond"></a>

Q. " Наприклад, про зали та столи, якщо вони вже були передані, та змін там немає\не плануються зміни "

A. Відповідати потрібно завжди.

***

## Q. Чи підтримує сокет - підключення відразу до кількох кас в одному ресторані? <a href="#socket-several-connections" id="socket-several-connections"></a>

A. Існують обмеження, 1 підключення для 1 ресторану. Синхронізація між кількома касами має регулюватись на боці POS-системи.

***

## Q. Якщо рахунок гостя розділений на 2 банківські рахунки (ФОП,ТОВ) - то банківські транзакції (RRN та інше) також дві або одна? <a href="#fop-tov-check" id="fop-tov-check"></a>

Приклад: Замовлення: Коктейль, Бургер. Оплата Коктейлю по бару, який на ФОП. Бургер по кухні - яка на ТОВ.

A. Для гостя закладу оплата проходить як одна транзакція, вже потім на стороні банка кошти розподіляються на окремі рахунки.

***

## Q. При формуванні signature отримуємо помилку "`SIGNATURE_NOT_VALID`" <a href="#signature" id="signature"></a>

A. Причин помилки може бути декілька:

1. Неправильне формування singature.
2. Неправильний ключ.
3. Неправильний ID ресторану.

[Про формування signature.](/api/auth)

***

## Q. Як викликати команду [`menuInfo`](/api/messages/othercallback#callback-menuinfo)? <a href="#menuinfo-call" id="menuinfo-call"></a>

A. Команда надсилається в POS, коли ініціюється з адмінки Expirenza рестораном завантаження меню з POS-системи.

<figure><img src="/files/Uxy6hHCRlbDU3f7jQz25" alt=""><figcaption><p>Цей блок знаходиться у розділі Редактор меню</p></figcaption></figure>

***

## Q. Як працює повернення коштів за замовлення? <a href="#cancell-bill" id="cancell-bill"></a>

A. Адміністратор ресторану через[ телеграм-бота](https://docs.expirenza.com/api/pages/Lk0fb0zAc2L8rbkdLXVg#5.-spovishennya) може повертати оплату по кнопці.

У відповідь Expirenza також буде надсилати до [POS-системи повідомлення](/api/messages/povidomlennya-u-pos-sistemu) про скасування.\
За замовчуванням ввімкнено автоповернення коштів, яке на тестових ресторанах не можна відключати.

Приклад повідомлення про скасування, яке Expirenza буде відправляти у POS:<br>

{% code title="Expirenza -> POS" %}

```json
{
   "rID":"aa61d473a08e41a9b52a5a66fb959999",
   "message":"УВАГА! Адміністратор Адмінаістратор повернув оплату рахунків [32070] гостю. Будь ласка, переконайтесь, що ці рахунки позначені неоплаченими у вашій системі обліку.",
   "warning":false,
   "billId":"8327brrr-201f-1f11-1f11-8b7d239d4949",
   "operation":"showMessage"
}
```

{% endcode %}

<figure><img src="/files/dsOVfD5777ScUJzFEkte" alt=""><figcaption><p>Повідомлення у телеграм-боті</p></figcaption></figure>

***

## Q.Чи має бути переданий стіл у замовленнях з ПреЧеком?

A. Так, має бути переданий tableNumber, це обов'язковий параметр у [/callback/getBill](/api/messages/getbill).

Q. У кав'ярні немає столів, що робити?&#x20;

A. Має бути переданий стіл, зі списку тих столів що передається нам у відповідь на команду [tablesInfo](/api/messages/tableinfo).

&#x20;     У прикладі з кав'ярнею можна передати стіл "для галочки" прик. номер 1, id 1.

***

## Q. Чому не підтягується номенклатура з POS системи?&#x20;

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

A. У 90% випадків присутня страва або модифікатор з однаковими ID. Перевірте що **всі id - унікальні як на стравах так і модифікторах.**


# Webhook отримання оновлень по Боксам

> **Призначення:** цей вебхук повідомляє про будь-яку зміну стану Бокса в Expirenza (створення, викуп, повернення до доступності, редагування рестораном).

***

### 1. Опис

* Подія надсилається, коли:
  * створено новий Бокс (з’явився у продажу);
  * усі порції викуплено (`availableQuantity = 0`);
  * Бокс знову став доступним (після відмови клієнта);
  * змінено назву, опис, ціну, time-slot тощо.

> Expirenza залишає за собою право призупинити або вимкнути вебхук для будь-якого інтегратора без попередження.

***

### 2. Як підписатися

1. Заповніть форму:
   * **Номер телефону** — для швидкого контакту.
   * **E-mail** — для технічних сповіщень.
   * **URL** — endpoint, що прийматиме `POST`.
2. Посилання на форму [тут](https://example.com).
3. Після модерації ми активуємо надсилання подій на вказаний URL.
4. Expirenza залишає за собою право призупинити або вимкнути вебхук для будь-якого інтегратора без попередження.

***

### 3. Специфікація та приклад

{% openapi-webhook spec="box-updates-webhook-2" name="BoxUpdated" method="post" %}
[box-updates-webhook-2](https://4401d86825a13bf607936cc3a9f3897a.r2.cloudflarestorage.com/gitbook-x-prod-openapi/raw/97ee805bdffc95edc133e571d77762ba532fe11f64040af3ffa3dad91d141508.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256\&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD\&X-Amz-Credential=dce48141f43c0191a2ad043a6888781c%2F20260825%2Fauto%2Fs3%2Faws4_request\&X-Amz-Date=20260825T011204Z\&X-Amz-Expires=172800\&X-Amz-Signature=2d5a2cc0243d74ba4bf13406c0823188036bb5cfc17250294de0dee935198900\&X-Amz-SignedHeaders=host\&x-amz-checksum-mode=ENABLED\&x-id=GetObject)
{% endopenapi-webhook %}

> Заголовки `Accept`, `Content-Type: application/json` та `Content-Length` додаються автоматично і тут не дублюються.

***

### 4. Очікувана відповідь клієнта

| HTTP код | Коли надсилати          |
| -------- | ----------------------- |
| **200**  | Подія успішно оброблена |

Будь-який інший код (4xx/5xx) трактуватиметься як помилка, і подію буде надіслано повторно з експоненційною затримкою.

***

### 5. Застереження щодо змін

Expirenza може додавати **нові необов’язкові поля** або розширювати словники без попереднього повідомлення.\
Переконайтеся, що парсер ігнорує невідомі атрибути, щоб інтеграція залишалася стійкою.

***

### 6. Зміни версій

| Дата           | Версія | Опис             |
| -------------- | ------ | ---------------- |
| **2025-05-07** | 1.0.0  | Початкова версія |