iikoWaiter позволяет работать с базой зарегистрированных гостей и пользоваться механиками лояльности и внутренних платежей при использовании на предприятии системы отличной от iikoCard5.
Работа с внешней лояльностью может быть реализована для сценариев:
чекина
чекина и чекаута(пречек и оплата)
Внешняя лояльность может поддерживать механики:
персональные скидки
подарочные блюда
бонусы
депозиты
подарочные сертификаты
Порядок действий пользователя аналогичен при использовании iikoCard 5.
Сканируемая информация может содержать не только токен или номер карты, но и какие-то расширенные сведения, за парсинг и обработку которых отвечает фронтовый плагин интегрируемой системы. Это позволяет использовать, например, динамические токены карт.
Есть урезанный вариант взаимодействия с ответом Waiter Message на привязку гостя.
Info |
---|
Данная интеграция реализуется в виде фронтового плагина для сервиса лояльности с определенными требованиями к разработке, описанными ниже. |
В случае использования интеграции лояльности на базе внешних плагинов ответственность iikoWaiter ограничивается передачей данных отсканированного значения во внешний плагин. В случае использования чекаута ответственность расширяется записью в ExternalData корректных данных о добавляемых в заказ платежах.
Note |
---|
Все ошибки или проблемы относительно работы с лояльностью лежат на поставщике технических решений внешней системы лояльности и решаются и устраняются этими поставщиками. |
Требования интеграции к разработчикам
Для интеграции с внешними системами лояльности в плагине iikoWaiter5 реализован ряд публичных методов для обмена данными с сервисами таких систем. В процессе взаимодействия плагин iikoWaiter выступает активной стороной и инициирует запросы.
Для взаимодействия используются:
набор публичных методов
данные, сохраненные в ExternalData
Поддерживают по http универсальные методы взаимодействия с плагином вейтера:
Привязка гостя к заказу
Отвязка гостя от заказа
Запрос доступных механик лояльности по заказу
Проверка работоспособности внешнего сервиса лояльности (пинг)
Возвращаемые от внешней системы данные о лояльности: остатки на персональных счетах (кошельках) гостя, специальные предложения и т.д. Не являются обязательными для работы интеграции.
Привязка гостя к заказу iiko должна быть реализована через привязку гостя БРД методами фронтового АПИ.
Вариант с привязкой гостя БРД требует от сервиса внешней лояльности обязательной реализации собственного фронтового плагина, который будет выполнять следующие операции:
получение данных о госте по токену или номеру карты от сервиса
поиск гостя в базе БРД
добавление нового гостя в базу БРД в случае его отсутствия там
привязку гостя БРД к заказу
отвязку гостя БРД от заказа
Расчет доступной суммы для оплаты бонусами и депозитом
Платежный процессор с собственными типами оплаты (только для варианта с чекаутом?)
Для потребностей настройки внешнему плагину необходимо залогировать собственные типы оплат, обрабатываемые встроенным платежным процессором, в виде имени ТО и значение GUID для ТО.
Пример:
Code Block |
---|
ExternalLoyaltySystemName payment types: Bonuses (ExternalLoyaltySystemName) - (0668e655-15a0-4b5e-ab3c-c7f7003cb8cc). Deposit (ExternalLoyaltySystemName) - (d645d632-cd95-4d49-9974-06911a9cd314). |
Для поддержки интеграции стороннему серверу системы лояльности необходимо реализовать у себя нижеперечисленные методы REST API. http можно реализовывать через nancy.
API
Anchor | ||||
---|---|---|---|---|
|
Привязка гостя (Чекин)
Content-Type | application/json |
---|---|
Method | POST |
URI | /orders/{id}/checkin |
Версия плагина iikoWaiter5 | 7.7.1+ |
Parameters
Parametes | Type | Description |
---|---|---|
id (path) | UUID | Id заказа. |
Body | Тело запроса |
Payload
Code Block | ||
---|---|---|
| ||
{ "Value": "149725735", "WaiterPin": "12345" } |
Responses
StatusCode | Content | Description |
---|---|---|
204 (No Content) | - | БРД гость был привязан к заказу плагином внешней системы. Дополнительная информация не требуется. |
200 (OK) | Используется для любых успешных и неуспешных ответов без привязки гостя БРД с сообщением дополнительной информации официанту в всплывающем окне. |
Response sample
Code Block | ||
---|---|---|
| ||
{ "WaiterMessage": "LoyaltySystem error!" } |
DTO
CheckinRequest
Anchor | ||||
---|---|---|---|---|
|
Property | Type | Description |
---|---|---|
Value | String | Отсканированное или введённое вручную значение идентификатора гостя. |
WaiterPin | String | ПИН-код текущего официанта. |
CheckinResponse
Anchor | ||||
---|---|---|---|---|
|
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
Code Block | ||
---|---|---|
| ||
{ "WaiterPin": "12345" } |
Responses
StatusCode | Content | Description |
---|---|---|
204 (No Content) | - | Приложение отобразит стандартное сообщение об успешной операции. |
200 (OK) | Используется для отображения кастомного сообщения официанту. Например: о неудачной попытке отвязать гостя от заказа. |
Response sample
Code Block | ||
---|---|---|
| ||
{ "WaiterMessage": "Guest couldn't be unbinded!" } |
DTO
UncheckinRequest
Anchor | ||||
---|---|---|---|---|
|
Property | Type | Description |
---|---|---|
WaiterPin | String | ПИН-код текущего официанта. |
UncheckinResponse
Anchor | ||||
---|---|---|---|---|
|
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
Code Block | ||
---|---|---|
| ||
{ "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
Anchor | ||||
---|---|---|---|---|
|
Property | Type | Description | ||
---|---|---|---|---|
ProductSKUs | Array<String> | Артикул блюд, которые будут отображены официанту на странице чекина. Используется для отображения подарков и т.п. Официант может кликнуть на блюдо, добавив его к заказу. | ||
UserWallets | Array<ClientWallet> | Список кошельков гостя для отображения официанту. | ||
WaiterMessage | String |
|
ClientWallet
Anchor | ||||
---|---|---|---|---|
|
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
Code Block | ||
---|---|---|
| ||
{ "BonusSum": "50.7", "DepositSum": "137.89" } |
DTO
PaymentLimitsResponse
Anchor | ||||
---|---|---|---|---|
|
Property | Type | Description |
---|---|---|
BonusSum | decimal | Доступная сумма для оплаты бонусами по заказу. |
DepositSum | decimal | Доступная сумма для оплаты депозитом по заказу. |
Доступ к сохранённым PaymentItems в ExternalData
Content-Type
application/json
ExternalData key
. |
API Method
PluginContext.Operations.TryGetOrderExternalDataByKey(orderId, Key)
Версия плагина iikoWaiter5
7.8.3+
DTO
Property
Type
Description
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)
Проверка доступности сервера
Content-Type | application/json |
---|---|
Method | GET |
URI | /ping |
Версия плагина iikoWaiter5 | 7.7.0+ |
Response
StatusCode | Content | Description |
---|---|---|
204 (No Content) | - | Сообщает о доступности сервера. |