Фичи плагина для iiko: межплагинное взаимодействие

Межплагинное взаимодействие

Версия контракта API: 1.1.0
Начиная с версии плагина MCRM 3.5.1

Интеграция с лояльностью MCRM через External Operations iikoFront.

Опция доступна после настройки плагина MCRM.

СОСТАВ ПАКЕТА

MCRM.Iiko.ExternalOps.Contracts.dll	Контракты DTO для вашего плагина (.NET Standard 2.0, без зависимости от Resto.Front.Api)
README-ExternalOps-API.md	Полное описание API: операции, DTO, ошибки, пример кода
MCRM.ExternalOps.Tester-bin.zip	Готовый тестовый плагин (кнопки меню) — для ручной проверки на кассе
MCRM.ExternalOps.Tester-source.zip	Исходник тестера — образец вызовов CallExternalOperation

Скачать все файлы архивом

ЧТО УМЕЕТ API

In-process вызовы из вашего плагина в плагин MCRM через iiko External Operations — без прямого REST к MCRM Cash API.

Сервис: MCRM.Loyalty
ModuleId MCRM: 21016318

#	Операция	Суть
1	GetCapabilities	Версия API, список операций, флаги
2	FindGuest	Поиск гостя (карта / телефон / QR)
3	AuthorizeGuestInOrder	Чекин в заказ (silent, без UI/SMS)
4	DetachGuestFromOrder	Отвязка гостя
5	GetGuestStateInOrder	Баланс, max spend
6	GetPaymentLimits	Лимиты оплаты бонусами
7	SpendBonus	Списание бонусов
8	PayOrder	Фиксация лояльности в MCRM (/cash/order)

Важно перед стартом

PayOrder не закрывает заказ в iikoFront.

Он только отправляет транзакцию лояльности в MCRM и ставит флаг MCRM_Paid.
Оплату/закрытие/фискализацию заказа в Front делаете или вы или официант.

Типичный флоу:

FindGuest → AuthorizeGuestInOrder → GetPaymentLimits / GetGuestStateInOrder → SpendBonus (опц.) → PayOrder(NoSpend=1) → ваше закрытие заказа в Front.

TransactionId — всегда Guid.NewGuid().ToString() на каждый SpendBonus / PayOrder.

Не смешивать: SpendBonus + PayOrder(NoSpend=0) на одном заказе → двойное списание.
Правильно: SpendBonus + PayOrder(NoSpend=1) или только PayOrder(NoSpend=0).

Суммы — в рублях (decimal), не в копейках.

Все операции silent: без диалогов MCRM и без SMS.

УСТАНОВКА НА ТЕСТОВУЮ КАССУ

Установить / обновить плагин MCRM из MCRM_Plugin от версии 3.5.1.zip (как обычно для Front-плагинов).
В MCRM_Plugin_Config.xml убедиться, что External Operations включены (по умолчанию да):

xml <EnableExternalOperations>true</EnableExternalOperations>

Перезапустить iikoFront

В логе MCRM должна быть строка вида:

[EO] 8 external operations registered under service 'MCRM.Loyalty'

(Опционально) Положить MCRM.ExternalOps.Tester-bin.zip рядом с плагинами Front — проверить кнопки «MCRM EO: …» в меню плагинов.

В ваш плагин: ссылка на MCRM.Iiko.ExternalOps.Contracts.dll + вызовы как в README / sample.

Минимальный чеклист приёмки

◻︎GetCapabilities → Success, ContractVersion 1.1.0, 8 операций

◻︎FindGuest по тестовой карте/телефону

◻︎AuthorizeGuestInOrder в открытом заказе (гость появился в заказе, без попапов)

◻︎GetGuestStateInOrder / GetPaymentLimits — баланс и лимиты

◻︎SpendBonus + PayOrder(NoSpend=1) или PayOrder(NoSpend=0)

◻︎После PayOrder — ваше закрытие заказа в Front; в MCRM транзакция одна (без дубля)

◻︎Если MCRM выключен — корректная ошибка / ExternalOperationCallingException, ваш плагин не падает

Фичи плагина:
• Сертификаты
• Заметки о госте
• Предоплата
• iikoWaiter
• Дополнения плагина
• Надбавки и сервисный сбор
• Параметры конфига