iikoWaiter позволяет работать с базой зарегистрированных гостей и пользоваться механиками лояльности и внутренних платежей при использовании на предприятии системы отличной от iikoCard5.
Работа с внешней лояльностью может быть реализована для сценариев:
чекина
чекина и чекаута(пречек и оплата)
Внешняя лояльность может поддерживать механики:
персональные скидки
подарочные блюда
бонусы
депозиты
подарочные сертификаты
Порядок действий пользователя аналогичен при использовании iikoCard 5.
Сканируемая информация может содержать не только токен или номер карты, но и какие-то расширенные сведения, за парсинг и обработку которых отвечает фронтовый плагин интегрируемой системы. Это позволяет использовать, например, динамические токены карт.
Есть урезанный вариант взаимодействия с ответом Waiter Message на привязку гостя.
Данная интеграция реализуется в виде фронтового плагина для сервиса лояльности с определенными требованиями к разработке, описанными ниже.
В случае использования интеграции лояльности на базе внешних плагинов ответственность iikoWaiter ограничивается передачей данных отсканированного значения во внешний плагин. В случае использования чекаута ответственность расширяется записью в ExternalData корректных данных о добавляемых в заказ платежах.
Все ошибки или проблемы относительно работы с лояльностью лежат на поставщике технических решений внешней системы лояльности и решаются и устраняются этими поставщиками.
Требования интеграции к разработчикам
Для интеграции с внешними системами лояльности в плагине iikoWaiter5 реализован ряд публичных методов для обмена данными с сервисами таких систем. В процессе взаимодействия плагин iikoWaiter выступает активной стороной и инициирует запросы.
Для взаимодействия используются:
набор публичных методов
данные, сохраненные в ExternalData
Поддерживают по http универсальные методы взаимодействия с плагином вейтера:
Привязка гостя к заказу
Отвязка гостя от заказа
Запрос доступных механик лояльности по заказу
Проверка работоспособности внешнего сервиса лояльности (пинг)
Возвращаемые от внешней системы данные о лояльности: остатки на персональных счетах (кошельках) гостя, специальные предложения и т.д. Не являются обязательными для работы интеграции.
Привязка гостя к заказу iiko должна быть реализована через привязку гостя БРД методами фронтового АПИ.
Вариант с привязкой гостя БРД требует от сервиса внешней лояльности обязательной реализации собственного фронтового плагина, который будет выполнять следующие операции:
получение данных о госте по токену или номеру карты от сервиса
поиск гостя в базе БРД
добавление нового гостя в базу БРД в случае его отсутствия там
привязку гостя БРД к заказу
отвязку гостя БРД от заказа
Расчет доступной суммы для оплаты бонусами и депозитом
Платежный процессор с собственными типами оплаты (только для варианта с чекаутом?)
Для потребностей настройки внешнему плагину необходимо залогировать собственные типы оплат, обрабатываемые встроенным платежным процессором, в виде имени ТО и значение GUID для ТО.
Пример:
ExternalLoyaltySystemName payment types: Bonuses (ExternalLoyaltySystemName) - (0668e655-15a0-4b5e-ab3c-c7f7003cb8cc). Deposit (ExternalLoyaltySystemName) - (d645d632-cd95-4d49-9974-06911a9cd314).
Для поддержки интеграции стороннему серверу системы лояльности необходимо реализовать у себя нижеперечисленные методы REST API. http можно реализовывать через nancy.
API
Привязка гостя (Чекин)
Content-Type | application/json |
---|---|
Method | POST |
URI | /orders/{id}/checkin |
Версия плагина iikoWaiter5 | 7.7.1+ |
Parameters
Parametes | Type | Description |
---|---|---|
id (path) | UUID | Id заказа. |
Body | Тело запроса |
Payload
{ "Value": "149725735", "WaiterPin": "12345" }
Responses
StatusCode | Content | Description |
---|---|---|
204 (No Content) | - | БРД гость был привязан к заказу плагином внешней системы. Дополнительная информация не требуется. |
200 (OK) | Используется для любых успешных и неуспешных ответов без привязки гостя БРД с сообщением дополнительной информации официанту в всплывающем окне. |
Response sample
{ "WaiterMessage": "LoyaltySystem error!" }
DTO
CheckinRequest
Property | Type | Description |
---|---|---|
Value | String | Отсканированное или введённое вручную значение идентификатора гостя. |
WaiterPin | String | ПИН-код текущего официанта. |
CheckinResponse
Property | Type | Description |
---|---|---|
WaiterMessage <required> | String | Сообщение, которое будет отображено официанту. Используется в случае необходимости сообщения какой-либо информации официанту во всплывающем окне. |
Отвязка гостя
Content-Type | application/json |
---|---|
Method | DELETE |
URI | /orders/{id}/checkin |
Версия плагина iikoWaiter5 | 7.7.1+ |
Parameters
Parametes | Type | Description |
---|---|---|
id (path) | UUID | Id заказа. |
Body | Тело запроса |
Payload
{ "WaiterPin": "12345" }
Responses
StatusCode | Content | Description |
---|---|---|
204 (No Content) | - | Приложение отобразит стандартное сообщение об успешной операции. |
200 (OK) | Используется для отображения кастомного сообщения официанту. Например: о неудачной попытке отвязать гостя от заказа. |
Response sample
{ "WaiterMessage": "Guest couldn't be unbinded!" }
DTO
UncheckinRequest
Property | Type | Description |
---|---|---|
WaiterPin | String | ПИН-код текущего официанта. |
UncheckinResponse
Property | Type | Description |
---|---|---|
WaiterMessage <required> | String | Сообщение, которое будет отображено официанту. Используется в случае необходимости сообщения какой-либо информации официанту во всплывающем окне. |
Получение лояльности
Content-Type | application/json |
---|---|
Method | GET |
URI | /orders/{id}/loyalty |
Версия плагина iikoWaiter5 | 7.7.0+ |
Parameters
Parametes | Type | Description |
---|---|---|
id (path) | UUID | Id заказа. |
Responses
StatusCode | Content | Description |
---|---|---|
204 (No Content) | - | Данных по лояльности нет |
200 (OK) | Передача информации о подарочных блюдах и кошельках гостя. |
Response sample
{ "ProductSKUs": [ "11015", "11068", "10549" ], "UserWallets": [ { "Id": "f87b4e69-2f01-46e7-9577-0b1b1534e121", "Name": "Rewards", "Balance": 142.15 }, { "Id": "5837a0b7-d509-4245-9062-1bf56f0db807", "Name": "Deposit", "Balance": 1000.57 } ] }
DTO
LoyaltyResponse
Property | Type | Description |
---|---|---|
ProductSKUs | Array<String> | Артикул блюд, которые будут отображены официанту на странице чекина. Используется для отображения подарков и т.п. Официант может кликнуть на блюдо, добавив его к заказу. |
UserWallets | Array<ClientWallet> | Список кошельков гостя для отображения официанту. |
WaiterMessage | String | Используется исключительно для отображения сообщения о неуспешном выполнении операции. |
ClientWallet
Property | Type | Description |
---|---|---|
Id <required> | UUID | Идентификатор кошелька. |
Name <required> | String | Название кошелька. |
Balance <required> | Decimal | Баланс кошелька. |
Получение лимитов оплат бонусами и депозитом
Content-Type | application/json |
---|---|
Method | GET |
URI | /orders/{id}/paymentLimits |
Версия плагина iikoWaiter5 | 7.8.3+ |
Parameters
Parametes | Type | Description |
---|---|---|
id (path) | UUID | Id заказа. |
Response
StatusCode | Content | Description |
---|---|---|
200 (OK) |
Response sample
{ "BonusSum": "50.7", "DepositSum": "137.89" }
DTO
PaymentLimitsResponse
Property | Type | Description |
---|---|---|
BonusSum | decimal | Доступная сумма для оплаты бонусами по заказу. |
DepositSum | decimal | Доступная сумма для оплаты депозитом по заказу. |
Доступ к сохранённым PaymentItems в ExternalData
Content-Type | application/json |
---|---|
ExternalData key | iikowaiter5.paymentItems |
API Method | PluginContext.Operations.TryGetOrderExternalDataByKey(orderId, Key) |
Версия плагина iikoWaiter5 | 7.8.3+ |
DTO
Property | Type | Description |
---|---|---|
ClientId | Guid | Id зачекиненного клиента, при котором сохранялись paymentItems. |
PaymentItems | List<PaymentItem> | Список всех добавленных к заказу PaymentItems. |
PaymentItem
Property | Type | Description |
---|---|---|
PaymentType | PaymentType | Тип платёжной системы. |
Sum | decimal | Сумма платежа. |
PaymentType
Property | Type | Description |
---|---|---|
Id | Guid | Id платежной системы |
Kind | PaymentTypeKind (enum) | |
Name | string | Имя платёжной системы. |
PaymentTypeKind (enum)
Unknown = 0, Cash = 1, BankCard = 2, IikoCard5Bonus = 3, IikoCard5Deposit = 4, ExternalLoyaltyBonus = 5, ExternalLoyaltyDeposit = 6
Проверка доступности сервера
Content-Type | application/json |
---|---|
Method | GET |
URI | /ping |
Версия плагина iikoWaiter5 | 7.7.0+ |
Response
StatusCode | Content | Description |
---|---|---|
204 (No Content) | - | Сообщает о доступности сервера. |