External Loyalty (интеграция по http)

iikoWaiter позволяет работать с базой зарегистрированных гостей и пользоваться механиками лояльности и внутренних платежей при использовании на предприятии системы отличной от iikoCard5.

Работа с внешней лояльностью может быть реализована для сценариев:

  • чекина

  • чекина и чекаута(пречек и оплата)

Внешняя лояльность может поддерживать механики:

  • персональные скидки

  • подарочные блюда

  • бонусы

  • депозиты

  • подарочные сертификаты

Порядок действий пользователя аналогичен при использовании iikoCard 5.

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

Есть урезанный вариант взаимодействия с ответом Waiter Message на привязку гостя.

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

В случае использования интеграции лояльности на базе внешних плагинов ответственность iikoWaiter ограничивается передачей данных отсканированного значения во внешний плагин. В случае использования чекаута ответственность расширяется записью в ExternalData корректных данных о добавляемых в заказ платежах.

Все ошибки или проблемы относительно работы с лояльностью лежат на поставщике технических решений внешней системы лояльности и решаются и устраняются этими поставщиками.



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

Для интеграции с внешними системами лояльности в плагине iikoWaiter5 реализован ряд публичных методов для обмена данными с сервисами таких систем. В процессе взаимодействия плагин iikoWaiter выступает активной стороной и инициирует запросы.

Для взаимодействия используются:

  • набор публичных методов

  • данные, сохраненные в ExternalData

Поддерживают по http универсальные методы взаимодействия с плагином вейтера:

  • Привязка гостя к заказу

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

  • Запрос доступных механик лояльности по заказу

  • Проверка работоспособности внешнего сервиса лояльности (пинг)

 

Возвращаемые от внешней системы данные о лояльности: остатки на персональных счетах (кошельках) гостя, специальные предложения и т.д. Не являются обязательными для работы интеграции.

 

Привязка гостя к заказу iiko должна быть реализована через привязку гостя БРД методами фронтового АПИ.

Вариант с привязкой гостя БРД требует от сервиса внешней лояльности обязательной реализации собственного фронтового плагина, который будет выполнять следующие операции:

  • получение данных о госте по токену или номеру карты от сервиса

  • поиск гостя в базе БРД

  • добавление нового гостя в базу БРД в случае его отсутствия там

  • привязку гостя БРД к заказу

  • отвязку гостя БРД от заказа

  • Расчет доступной суммы для оплаты бонусами и депозитом

  • Платежный процессор с собственными типами оплаты (только для варианта с чекаутом?)

 

Для потребностей настройки внешнему плагину необходимо залогировать собственные типы оплат, обрабатываемые встроенным платежным процессором, в виде имени ТО и значение GUID для ТО.

Пример:

1 2 3 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

Content-Type

application/json

Method

POST

URI

/orders/{id}/checkin

Версия плагина iikoWaiter5

7.7.1+

Parameters

Parametes

Type

Description

Parametes

Type

Description

id (path)

UUID

Id заказа.

Body

CheckinRequest

Тело запроса

Payload
1 2 3 4 { "Value": "149725735", "WaiterPin": "12345" }

Responses

StatusCode

Content

Description

StatusCode

Content

Description

204 (No Content)

-

БРД гость был привязан к заказу плагином внешней системы. Дополнительная информация не требуется.

200 (OK)

CheckinResponse

Используется для любых успешных и неуспешных ответов без привязки гостя БРД с сообщением дополнительной информации официанту в всплывающем окне.

Response sample
1 2 3 { "WaiterMessage": "LoyaltySystem error!" }

DTO

CheckinRequest

Property

Type

Description

Property

Type

Description

Value

String

Отсканированное или введённое вручную значение идентификатора гостя.

WaiterPin

String

ПИН-код текущего официанта.

CheckinResponse

Property

Type

Description

Property

Type

Description

WaiterMessage

<required>

String

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

 


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

Content-Type

application/json

Content-Type

application/json

Method

DELETE

URI

/orders/{id}/checkin

Версия плагина iikoWaiter5

7.7.1+

Parameters

Parametes

Type

Description

Parametes

Type

Description

id (path)

UUID

Id заказа.

Body

UncheckinRequest

Тело запроса

Payload
1 2 3 { "WaiterPin": "12345" }

Responses

StatusCode

Content

Description

StatusCode

Content

Description

204 (No Content)

-

Приложение отобразит стандартное сообщение об успешной операции.

200 (OK)

UncheckinResponse

Используется для отображения кастомного сообщения официанту. Например: о неудачной попытке отвязать гостя от заказа.

Response sample
1 2 3 { "WaiterMessage": "Guest couldn't be unbinded!" }

DTO

UncheckinRequest

Property

Type

Description

Property

Type

Description

WaiterPin

String

ПИН-код текущего официанта.

UncheckinResponse

Property

Type

Description

Property

Type

Description

WaiterMessage

<required>

String

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

 


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

Content-Type

application/json

Content-Type

application/json

Method

GET

URI

/orders/{id}/loyalty

Версия плагина iikoWaiter5

7.7.0+

Parameters

Parametes

Type

Description

Parametes

Type

Description

id (path)

UUID

Id заказа.

Responses

StatusCode

Content

Description

StatusCode

Content

Description

204 (No Content)

-

Данных по лояльности нет

200 (OK)

LoyaltyResponse

Передача информации о подарочных блюдах и кошельках гостя.

Response sample
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 { "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

Property

Type

Description

ProductSKUs

Array<String>

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

UserWallets

Array<ClientWallet>

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

WaiterMessage

String

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

ClientWallet

Property

Type

Description

Property

Type

Description

Id

<required>

UUID

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

Name

<required>

String

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

Balance

<required>

Decimal

Баланс кошелька.

 


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

Content-Type

application/json

Content-Type

application/json

Method

GET

URI

/orders/{id}/paymentLimits

Версия плагина iikoWaiter5

7.8.3+

Parameters

Parametes

Type

Description

Parametes

Type

Description

id (path)

UUID

Id заказа.

Response

StatusCode

Content

Description

StatusCode

Content

Description

200 (OK)

PaymentLimitsResponse

 

Response sample
1 2 3 4 { "BonusSum": "50.7", "DepositSum": "137.89" }

DTO

PaymentLimitsResponse

Property

Type

Description

Property

Type

Description

BonusSum

decimal

Доступная сумма для оплаты бонусами по заказу.

DepositSum

decimal

Доступная сумма для оплаты депозитом по заказу.

 


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

Content-Type

application/json

Content-Type

application/json

ExternalData key

iikowaiter5.paymentItems

API Method

PluginContext.Operations.TryGetOrderExternalDataByKey(orderId, Key)

Версия плагина iikoWaiter5

7.8.3+

 

DTO

Property

Type

Description

Property

Type

Description

ClientId

Guid

Id зачекиненного клиента, при котором сохранялись paymentItems.

PaymentItems

List<PaymentItem>

Список всех добавленных к заказу PaymentItems.

 

PaymentItem

Property

Type

Description

Property

Type

Description

PaymentType

PaymentType

Тип платёжной системы.

Sum

decimal

Сумма платежа.

 

PaymentType

Property

Type

Description

Property

Type

Description

Id

Guid

Id платежной системы

Kind

PaymentTypeKind (enum)

 

Name

string

Имя платёжной системы.

 

PaymentTypeKind (enum)
1 2 3 4 5 6 7 Unknown = 0, Cash = 1, BankCard = 2, IikoCard5Bonus = 3, IikoCard5Deposit = 4, ExternalLoyaltyBonus = 5, ExternalLoyaltyDeposit = 6

 


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

Content-Type

application/json

Content-Type

application/json

Method

GET

URI

/ping

Версия плагина iikoWaiter5

7.7.0+

Response

StatusCode

Content

Description

StatusCode

Content

Description

204 (No Content)

-

Сообщает о доступности сервера.