External Loyalty (REST API)

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

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

  • чекина

  • чекина, чекаута и оплаты

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

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

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

  • бонусы

  • депозиты

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

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

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

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

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

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

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

 

Сервисам лояльности, реализовавшим интеграцию с Waiter, мы предлагаем разместить информацию об этом на данном портале. Для этого просим предоставить следующую информацию:

  1. Ссылка на сайт сервиса

  2. Ссылку на инструкцию пользователя (описание работы сервиса в интеграции с Waiter)

  3. Ссылку на дистрибутив (или на форму для запроса на установочный пакет)

  4. Ссылку на инструкцию по установке и настройке (руководство администратора)

  5. Контакты службы поддержки для конечных клиентов и сервисных партнеров iiko

Рекомендательно

  1. Ссылки на маркетинговые материалы по описанию кейса интеграции


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

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

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

  • Http REST API

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

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

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

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

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

 

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

 

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

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

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

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

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

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

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

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

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

 

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

Пример:

ExternalLoyaltySystemName payment types: Bonuses (ExternalLoyaltySystemName) - (0668e655-15a0-4b5e-ab3c-c7f7003cb8cc). Deposit (ExternalLoyaltySystemName) - (d645d632-cd95-4d49-9974-06911a9cd314).

Для поддержки интеграции стороннему серверу системы лояльности необходимо реализовать у себя нижеперечисленные методы REST API. Рекомендуем ASP.NET использовать в качестве Web Server.


API

Content-Type

application/json

Method

POST

Path

orders/{id}/checkin

Parameters

Parameters

Type

Description

Parameters

Type

Description

id (path)

UUID

Id заказа

Body

CheckinRequest

Тело запроса

Payload

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

Responses

Status Code

Content

Description

Status Code

Content

Description

204 No Content

-

БРД гость был привязан к заказу через

IOperationService.AddClientToOrder()

200 OK

CheckinResponse

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

Response sample
{ "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

Path

orders/{id}/checkin

Parameters

Parameters

Type

Description

Parameters

Type

Description

id (path)

UUID

Id заказа

Body

UncheckinRequest

Тело запроса

Payload

Responses

Status Code

Content

Description

Status Code

Content

Description

204 No Content

-

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

200 OK

UncheckinResponse

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

Response sample

DTO

UncheckinRequest

Property

Type

Description

Property

Type

Description

WaiterPin

String

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

UncheckinResponse

Property

Type

Description

Property

Type

Description

WaiterMessage

<required>

String

Сообщение, которое будет отображено официанту во всплывающем диалоговом окне.

Request

Method

GET

Path

orders/{id}/loyalty

Parameters

Parameters

Type

Description

Parameters

Type

Description

id (path)

UUID

Id заказа

Request sample

plugin_host - хост, на котором развернуто API плагина внешней системы лояльности

order_id - Id заказа

Response

Status Code

Content-Type

Description

Status Code

Content-Type

Description

204 No Content

-

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

200 OK

application/json

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

200 OK

multipart/form-data (спецификация)

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

Response sample

DTO

LoyaltyResponse

Property

Type

Description

Property

Type

Description

Suggestions

List<string>

Текстовые подсказки.

ProductSKUs

List<String>

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

UserWallets

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

Path

orders/{id}/paymentLimits

Parameters

Parameters

Type

Description

Parameters

Type

Description

id (path)

UUID

Id заказа

Response

Status Code

Content

Description

Status Code

Content

Description

200 OK

PaymentLimitsResponse

 

Response sample

DTO

PaymentLimitsResponse

Property

Type

Description

Property

Type

Description

BonusSum

decimal

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

DepositSum

decimal

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

Content-Type

application/json

Content-Type

application/json

Method

GET

Path

ping

Response

Status Code

Content

Description

Status Code

Content

Description

204 No Content

-

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