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
api
api

Привязка гостя (Чекин)

Content-Type	application/json
Method	POST
URI	/orders/{id}/checkin
Версия плагина iikoWaiter5	7.7.1+

Parameters

Parametes	Type	Description
id (path)	UUID	Id заказа.
Body	CheckinRequest	Тело запроса

Payload

Code Block

language	json

{
    "Value": "149725735",
    "WaiterPin": "12345"
}

Responses

StatusCode	Content	Description
204 (No Content)	-	БРД гость был привязан к заказу плагином внешней системы. Дополнительная информация не требуется.
200 (OK)	CheckinResponse	Используется для любых успешных и неуспешных ответов без привязки гостя БРД с сообщением дополнительной информации официанту в всплывающем окне.

Response sample

Code Block

language	json

{
    "WaiterMessage": "LoyaltySystem error!"
}

DTO

CheckinRequest
Anchor
checkinRequest
checkinRequest

Property	Type	Description
Value	String	Отсканированное или введённое вручную значение идентификатора гостя.
WaiterPin	String	ПИН-код текущего официанта.

CheckinResponse
Anchor
checkinResponse
checkinResponse

Property

Type

Description

WaiterMessage

String

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

Наверх

Отвязка гостя

Content-Type	application/json
Method	DELETE
URI	/orders/{id}/checkin
Версия плагина iikoWaiter5	7.7.1+

Parameters

Parametes	Type	Description
id (path)	UUID	Id заказа.
Body	UncheckinRequest	Тело запроса

Payload

Code Block

language	json

{
    "WaiterPin": "12345"
}

Responses

StatusCode	Content	Description
204 (No Content)	-	Приложение отобразит стандартное сообщение об успешной операции.
200 (OK)	UncheckinResponse	Используется для отображения кастомного сообщения официанту. Например: о неудачной попытке отвязать гостя от заказа.

Response sample

Code Block

language	json

{
    "WaiterMessage": "Guest couldn't be unbinded!"
}

DTO

UncheckinRequest
Anchor
uncheckinRequest
uncheckinRequest

Property	Type	Description
WaiterPin	String	ПИН-код текущего официанта.

UncheckinResponse
Anchor
uncheckinResponse
uncheckinResponse

Property

Type

Description

WaiterMessage

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)	LoyaltyResponse	Передача информации о подарочных блюдах и кошельках гостя.

Response sample

Code Block

language	json

{
    "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
loyaltyResponse
loyaltyResponse

Property

Type

Description

ProductSKUs

Array<String>

Артикул блюд, которые будут отображены официанту на странице чекина. Используется для отображения подарков и т.п. Официант может кликнуть на блюдо, добавив его к заказу.

UserWallets

Array<ClientWallet>

Список кошельков гостя для отображения официанту.

WaiterMessage

String

Note
Используется исключительно для отображения сообщения о неуспешном выполнении операции.

ClientWallet
Anchor
wallet
wallet

Property

Type

Description

Id

UUID

Идентификатор кошелька.

Name

String

Название кошелька.

Balance

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)	PaymentLimitsResponse

Response sample

Code Block

language	json

{
    "BonusSum": "50.7",
    "DepositSum": "137.89"
}

DTO

PaymentLimitsResponse
Anchor
paymentLimits
paymentLimits

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)

Code Block
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)	-	Сообщает о доступности сервера.

Наверх

Page Comparison

Versions Compared

Old Version 58

New Version 59

Key

Требования интеграции к разработчикам

API Anchorapiapi

Привязка гостя (Чекин)

Parameters

Payload

Responses

Response sample

DTO

CheckinRequest AnchorcheckinRequestcheckinRequest

CheckinResponse AnchorcheckinResponsecheckinResponse

Отвязка гостя

Parameters

Payload

Responses

Response sample

DTO

UncheckinRequest AnchoruncheckinRequestuncheckinRequest

UncheckinResponse AnchoruncheckinResponseuncheckinResponse

Получение лояльности

Parameters

Responses

Response sample

DTO

LoyaltyResponse AnchorloyaltyResponseloyaltyResponse

ClientWallet Anchorwalletwallet

Получение лимитов оплат бонусами и депозитом

Parameters

Response

Response sample

DTO

PaymentLimitsResponse AnchorpaymentLimitspaymentLimits

Доступ к сохранённым PaymentItems в ExternalData

DTO

PaymentItem

PaymentType

PaymentTypeKind (enum)

Проверка доступности сервера

Response

API
Anchor
api
api

CheckinRequest
Anchor
checkinRequest
checkinRequest

CheckinResponse
Anchor
checkinResponse
checkinResponse

UncheckinRequest
Anchor
uncheckinRequest
uncheckinRequest

UncheckinResponse
Anchor
uncheckinResponse
uncheckinResponse

LoyaltyResponse
Anchor
loyaltyResponse
loyaltyResponse

ClientWallet
Anchor
wallet
wallet

PaymentLimitsResponse
Anchor
paymentLimits
paymentLimits