# Интеграция с ресторанной системой iiko

#### Общее описание

Интеграция позволяет пользователю за терминалом ресторанной системы осуществить закрытие заказа используя номер комнаты/апартамента гостя, что упрощает процедуру переноса задолженности.

#### Требования

- Минимальная версия iiko 8.7.6 так как плагин использует Front API V8
- Наличие лицензии api payment (21016318)
- Запуск iikoFront от администратора
- При раскатке на точку с несколькими официантскими станциями/ведомыми терминалами плагин устанавливается на все терминалы.

#### Настройка плагина

Необходимо скачать плагин (плагин предоставлется службой технической поддержки по предварительному запросу через электронную почту <support@ecvi.ru>), разблокировать файлы и разархивировать  
папку с плагином в папку с плагинами iikoFront, располагающуюся по пути   
C:\\Program Files\\iiko\\iikoRMS\\Front.Net\\Plugins

Лог плагина plugin-Get.Front.Ecvi.log хранится по пути:

C:\\Users\\User\\AppData\\Roaming\\iiko\\CashServer\\Logs.

<details id="bkmrk-%D0%9F%D0%B0%D1%80%D0%B0%D0%BC%D0%B5%D1%82%D1%80%D1%8B-%D0%BA%D0%BE%D0%BD%D1%84%D0%B8%D0%B3%D1%83%D1%80%D0%B0%D1%86"><summary>Параметры конфигурационного файла Get.Front.Ecvi.dll.config (хранится по пути C:\\Program Files\\iiko\\iikoRMS\\Front.Net\\Plugins\\Get.Front.Ecvi):</summary>

"BaseUrl" - Адрес сервиса, куда направляются запросы (без слеша на конце);  
"HotelToken" - токен отеля на сервере ECVI;  
"EnableSearchByGuestCard" - параметр, отвечающий за возможность поиска гостя по номеру карты. При указании в поле значения "True", в меню выбора способа чекина гостя будут выведены две кнопки для поиска гостя по номеру комнаты и по номеру карты.  
"IncreaseProductName" - наименование надбавки, которая отправляется в ECVI

<details><summary>Пример отправки в api IncreaseProductName = "Надбавка"</summary>

```
{
   "OrderID": "35950",
   "DepartCode": "RS",
   "InvoiceDate": "2024-10-14 15:06:56",
   "ServiceDate": "2024-10-14 15:06:56",
   "Count": "1",
   "Discount": 0,
   "Amount": 44.00,
   "Price": 44.00,
   "AmountWithoutDiscount": 44.00,
   "Comments": "1",
   "NDS": "0",
   "NdsAmount": "0",
   "Items": [
    {
       "Name": "Сахар10",
       "Amount": 1,
       "Price": 10.00,
       "DiscountPrice": 0,
       "Total": 10.00,
       "Tax": null,
       "Comment": null
    },
    {
       "Name": "Сахар15",
       "Amount": 2,
       "Price": 15.00,
       "DiscountPrice": 0,
       "Total": 30.00,
       "Tax": null,
       "Comment": null
    },
    {
       "Name": "Надбавка",
       "Amount": 1,
       "Price": 4.00,
       "DiscountPrice": 0,
       "Total": 4.00,
       "Tax": null,
       "Comment": null
    }
  ]
}
```

</details></details>Пример:

&lt;userSettings&gt;  
 &lt;Get.Front.Ecvi.Properties.Settings&gt;  
 &lt;setting name="BaseUrl" serializeAs="String"&gt;  
 &lt;value&gt;https://demo2.ecvi.ru/iikoapi&lt;/value&gt;  
 &lt;/setting&gt;  
 &lt;setting name="HotelToken" serializeAs="String"&gt;  
 &lt;value&gt;k6K5Acz1Ib-vxT5j0-FaEZWwoqicyLpn&lt;/value&gt;  
 &lt;/setting&gt;  
 &lt;setting name="EnableSearchByGuestCard" serializeAs="String"&gt;  
 &lt;value&gt;True&lt;/value&gt;  
 &lt;/setting&gt;  
 &lt;setting name="IncreaseProductName" serializeAs="String"&gt;  
 &lt;value&gt;Надбавка&lt;/value&gt;  
 &lt;/setting&gt;  
 &lt;/Get.Front.Ecvi.Properties.Settings&gt;  
 &lt;/userSettings&gt;

#### Создание типа оплаты ECVI

После настройки конфигурационного файла плагина необходимо запустить iikoF ront с правами администратора для регистрации плагином нового типа оплаты. После запуска iikoF ront необходимо авторизоваться в iik oOffice и создать новый тип оплаты, который будет использоваться для списания в заказах.

Настройка типа оплаты (обязательные поля выделены желтым):

[![image.png](https://help.ecvi.ru/uploads/images/gallery/2024-11/scaled-1680-/8HOimage.png)](https://help.ecvi.ru/uploads/images/gallery/2024-11/8HOimage.png)

#### Шаблон пречека

<div data-inlined-content="{"items":[{"type":"text","content":"В шаблоне пречека должны присутствовать строки:","length":47,"format":{"dashed":false,"overline":false,"color":"","customs":{}}}],"length":47}" id="bkmrk-%D0%92-%D1%88%D0%B0%D0%B1%D0%BB%D0%BE%D0%BD%D0%B5-%D0%BF%D1%80%D0%B5%D1%87%D0%B5%D0%BA%D0%B0-%D0%B4%D0%BE"><div data-inlined-content="{"items":[{"type":"text","content":"В шаблоне пречека должны присутствовать строки:","length":47,"format":{"dashed":false,"overline":false,"color":"","customs":{}}}],"length":47}"><div data-inlined-content="{"items":[{"type":"text","content":"В шаблоне пречека должны присутствовать строки:","length":47,"format":{"dashed":false,"overline":false,"color":"","customs":{}}}],"length":47}">В шаблоне пречека должны присутствовать строки:</div><div data-inlined-content="{"items":[{"type":"text","content":"В шаблоне пречека должны присутствовать строки:","length":47,"format":{"dashed":false,"overline":false,"color":"","customs":{}}}],"length":47}">&lt;center&gt;&lt;split&gt;&lt;whitespace-preserve&gt;@Model.CommonInfo.CafeSetup.BillFooter&lt;/whitespace-preserve&gt;&lt;/split&gt;&lt;/center&gt;</div><div data-inlined-content="{"items":[{"type":"text","content":"В шаблоне пречека должны присутствовать строки:","length":47,"format":{"dashed":false,"overline":false,"color":"","customs":{}}}],"length":47}">Если используется стандартный шаблон, эти строки присутствуют по умолчанию. В случае с кастомным шаблоном необходимо вручную добавить их в блок Footer, пример:</div><div data-inlined-content="{"items":[{"type":"text","content":"В шаблоне пречека должны присутствовать строки:","length":47,"format":{"dashed":false,"overline":false,"color":"","customs":{}}}],"length":47}">  
</div></div></div>```
@* Footer (begin) *@
<center>
  <split>
    <whitespace-preserve>@Model.CommonInfo.CafeSetup.BillFooter</whitespace-preserve>
  </split>
</center>
@* Footer (end) *@
```

#### Функциональное описание

##### Функциональная схема реализации

[![image.png](https://help.ecvi.ru/uploads/images/gallery/2024-11/scaled-1680-/5xOimage.png)](https://help.ecvi.ru/uploads/images/gallery/2024-11/5xOimage.png)

##### Функциональное описание реализации

Плагин стартует вместе с запуском IIKOFront. При успешном старте плагина на iikoFront отобразится сообщение "Плагин успешно запущен".

<details id="bkmrk-%D0%A1%D0%BE%D0%BE%D0%B1%D1%89%D0%B5%D0%BD%D0%B8%D0%B5-%D0%BF%D1%80%D0%B8-%D1%83%D1%81%D0%BF%D0%B5%D1%88%D0%BD"><summary>Сообщение при успешном запуске плагина</summary>

[![image.png](https://help.ecvi.ru/uploads/images/gallery/2024-11/scaled-1680-/3Idimage.png)](https://help.ecvi.ru/uploads/images/gallery/2024-11/3Idimage.png)

</details>В случае ошибки настроек плагина, будет выведено соответствующее уведомление.

<details id="bkmrk-%D0%A1%D0%BE%D0%BE%D0%B1%D1%89%D0%B5%D0%BD%D0%B8%D0%B5-%D0%BF%D1%80%D0%B8-%D0%BD%D0%B5%D1%83%D1%81%D0%BF%D0%B5"><summary>Сообщение при неуспешном запуске плагина</summary>

[![image.png](https://help.ecvi.ru/uploads/images/gallery/2024-11/scaled-1680-/Yyvimage.png)](https://help.ecvi.ru/uploads/images/gallery/2024-11/Yyvimage.png)

</details>Для добавления гостя в заказ необходимо воспользоваться функциональной кнопкой на экране редактирования заказа:

[![image.png](https://help.ecvi.ru/uploads/images/gallery/2024-11/scaled-1680-/LWdimage.png)](https://help.ecvi.ru/uploads/images/gallery/2024-11/LWdimage.png)

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

[![image.png](https://help.ecvi.ru/uploads/images/gallery/2024-11/scaled-1680-/0V7image.png)](https://help.ecvi.ru/uploads/images/gallery/2024-11/0V7image.png)

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

[![image.png](https://help.ecvi.ru/uploads/images/gallery/2024-11/scaled-1680-/3E4image.png)](https://help.ecvi.ru/uploads/images/gallery/2024-11/3E4image.png)

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

[![image.png](https://help.ecvi.ru/uploads/images/gallery/2024-11/scaled-1680-/E1Limage.png)](https://help.ecvi.ru/uploads/images/gallery/2024-11/E1Limage.png)

При выборе поиска по номеру карты открывается окно ввода или сканирования карты гостя. Сканирование карты возможно только с помощью картридера.

[![image.png](https://help.ecvi.ru/uploads/images/gallery/2024-11/scaled-1680-/qwHimage.png)](https://help.ecvi.ru/uploads/images/gallery/2024-11/qwHimage.png)

Результат поиска гостя будет выведен кассиру в виде сообщения:

<details id="bkmrk-%D0%93%D0%BE%D1%81%D1%82%D1%8C-%D0%BD%D0%B5-%D0%BD%D0%B0%D0%B9%D0%B4%D0%B5%D0%BD"><summary>Гость не найден</summary>

[![image.png](https://help.ecvi.ru/uploads/images/gallery/2024-11/scaled-1680-/dCqimage.png)](https://help.ecvi.ru/uploads/images/gallery/2024-11/dCqimage.png)

</details><details id="bkmrk-%D0%93%D0%BE%D1%81%D1%82%D1%8C-%D0%B4%D0%BE%D0%B1%D0%B0%D0%B2%D0%BB%D0%B5%D0%BD-%D0%B2-%D0%B7%D0%B0%D0%BA"><summary>Гость добавлен в заказ и у него положительный баланс</summary>

[![image.png](https://help.ecvi.ru/uploads/images/gallery/2024-11/scaled-1680-/ZiDimage.png)](https://help.ecvi.ru/uploads/images/gallery/2024-11/ZiDimage.png)

</details><details id="bkmrk-%D0%93%D0%BE%D1%81%D1%82%D1%8C-%D0%B4%D0%BE%D0%B1%D0%B0%D0%B2%D0%BB%D0%B5%D0%BD%2C-%D0%BD%D0%BE-%D1%83"><summary>Гость добавлен, но у него отрицательный баланс</summary>

[![image.png](https://help.ecvi.ru/uploads/images/gallery/2024-11/scaled-1680-/St4image.png)](https://help.ecvi.ru/uploads/images/gallery/2024-11/St4image.png)

</details><details id="bkmrk-%D0%9E%D1%82%D1%81%D1%83%D1%82%D1%81%D1%82%D0%B2%D1%83%D0%B5%D1%82-%D0%B8%D0%BD%D1%82%D0%B5%D1%80%D0%BD%D0%B5%D1%82"><summary>Отсутствует интернет-соединение или сервер не отвечает</summary>

[![image.png](https://help.ecvi.ru/uploads/images/gallery/2024-11/scaled-1680-/oMaimage.png)](https://help.ecvi.ru/uploads/images/gallery/2024-11/oMaimage.png)

</details>Закрытие заказа в системе IIKO происходит нативными механиками работы с IIKOFront в блоке кассы.   
При переходе в блок кассы заказ проверяется на наличие в нем гостя Ecvi, а далее - на доступность закрытия заказа с помощью баланса гостя. В случае, если баланс гостя позволяет полностью покрыть итоговую сумму заказа, в заказ автоматически будет добавлен платеж на полную сумму заказа с тем типом, который был зарегистрирован при настройке плагина.

[![image.png](https://help.ecvi.ru/uploads/images/gallery/2024-11/scaled-1680-/mCsimage.png)](https://help.ecvi.ru/uploads/images/gallery/2024-11/mCsimage.png)

Если баланс гостя отрицателен или суммы недостаточно для оплаты, кассир будет уведомлен об этом сообщением:

[![image.png](https://help.ecvi.ru/uploads/images/gallery/2024-11/scaled-1680-/KTeimage.png)](https://help.ecvi.ru/uploads/images/gallery/2024-11/KTeimage.png)

При закрытии заказа с типом оплаты, добавленным плагином, в сервер Ecvi будет отправлен запрос, содержащий основные данные по заказу.

<details id="bkmrk-%D0%9C%D0%BE%D0%B4%D0%B5%D0%BB%D1%8C-%D0%B7%D0%B0%D0%BF%D1%80%D0%BE%D1%81%D0%B0%3A-%7B%C2%A0%22o"><summary>Модель запроса:</summary>

{  
 "OrderID": "35954", - OrderID, полученный при чекине гостя  
 "DepartCode": "Демо", - Название группы, в которой зарегистрирован  
терминал, из iikoOffice  
 "InvoiceDate": "2024-09-12 14:15:30", - дата и время закрытия заказа  
 "ServiceDate": "2024-09-12 14:15:30", - дата и время закрытия заказа  
 "Count": "1", - всегда "1"  
 "Discount": 0.5, - доля суммы скидки по каждому блюду в заказе к общей  
сумме заказа. Если в заказе результирующей является надбавка, в поле  
передается "0".  
 "Amount": 12.00, - итоговая сумма заказа. Если в заказе результирующей  
является надбавка, в поле передается итоговая сумма заказа.  
 "Price": 12.00, - - итоговая сумма заказа. Если в заказе  
результирующей является надбавка, в поле передается итоговая сумма  
заказа.  
 "AmountWithoutDiscount": 24.00, - сумма заказа без учета скидок. Если  
в заказе результирующей является надбавка, в поле передается итоговая  
сумма заказа.  
 "Comments": "1", - всегда "1"  
 "NDS": "0", - всегда "0"  
 "NdsAmount": "0", - всегда "0"  
 "Items": \[  
 {  
 "Name": "Блюдо 1", - название блюда из iikoOffice  
 "Amount": 1, - количество позиции в заказе(может быть нецелым  
числом)  
 "Price": 42.0000, - цена блюда из iikо Если в заказе  
результирующей является надбавка, в поле передается итоговая цена за  
единицу позиции с учетом надбавки.  
 "DiscountPrice": 30.0000, - сумма скидки на позицию(с учетом  
количества) Если в заказе результирующей является надбавка, в поле  
передается "0".  
 "Total": 12.00, - итоговая сумма по позиции  
 "Tax": {  
 "Name": "20%", - наименование налоговой ставки из iikoOffice  
 "Percent": "20", - процент налоговой ставки из iikoOffice  
 "Calculated": "False" - признак рассчетности  
 },  
 "Comment": null - комментарий к позиции  
 }  
\]  
}

</details><p class="callout info">Если, после перехода в блок кассы, удалить тип оплаты Ecvi и закрыть заказ, запрос не будет отправлен. При изменении суммы добавленного плагином платежа и последующей попытке закрытия заказа, кассиру будет выведено сообщение о минимальной сумме оплаты типом Ecvi.</p>

[![image.png](https://help.ecvi.ru/uploads/images/gallery/2024-11/scaled-1680-/RFqimage.png)](https://help.ecvi.ru/uploads/images/gallery/2024-11/RFqimage.png)

<p class="callout warning">Работа с блюдами со схемой модификаторов и услугами с тарификацией не поддерживается  
При передаче надбавки ее сумма формируется относительно результирующей суммы надбавок в заказе  
</p>

<div data-inlined-content="{"items":[{"type":"text","content":"При передаче надбавки ее сумма формируется относительно результирующей суммы надбавок в заказе.","length":95,"format":{"dashed":false,"overline":false,"color":"","customs":{}}}],"length":95}" id="bkmrk--9">  
</div><div data-inlined-content="{"items":[{"type":"text","content":"Если в заказе есть гость Ecvi, при печати пречека на нем будет выведена информация о госте: номер комнаты, имя гостя и место для подписи. Печать информации о госте не зависит от баланса гостя.","length":192,"format":{"dashed":false,"overline":false,"color":"","customs":{}}}],"length":192}" id="bkmrk-%D0%95%D1%81%D0%BB%D0%B8-%D0%B2-%D0%B7%D0%B0%D0%BA%D0%B0%D0%B7%D0%B5-%D0%B5%D1%81%D1%82%D1%8C-%D0%B3"><div data-inlined-content="{"items":[{"type":"text","content":"Если в заказе есть гость Ecvi, при печати пречека на нем будет выведена информация о госте: номер комнаты, имя гостя и место для подписи. Печать информации о госте не зависит от баланса гостя.","length":192,"format":{"dashed":false,"overline":false,"color":"","customs":{}}}],"length":192}">Если в заказе есть гость Ecvi, при печати пречека на нем будет выведена информация о госте: номер комнаты, имя гостя и место для подписи. Печать информации о госте не зависит от баланса гостя.</div></div>[![image.png](https://help.ecvi.ru/uploads/images/gallery/2025-03/scaled-1680-/image.png)](https://help.ecvi.ru/uploads/images/gallery/2025-03/image.png)