Создание заказа с лояльностью

Введение

В этой статье рассматривается сценарий применения бонусов и скидок системы лояльности к заказу на сайте ресторана.

Основы взаимодействия сайта ресторана с r_k Delivery описаны в статьях Возможности API.

Базовый сценарий создания заказа с бонусами лояльности:

Получение предрасчета заказа
Создание заказа
Заказ передается на кассу вручную или автоматически
К заказу применяется лояльность на кассе.

Предварительные настройки

Настройте заведение в r_k Delivery
Настройте интеграцию с r_k Loyalty
Настройте подключение по API для бэкенда сайта или бэкенда приложения ресторана
Подключите на сайте авторизацию гостей по номеру телефона.

Авторизация гостей по номеру телефона необходима для связи с базой гостей в r_k Delivery и r_k Loyalty, а также для идентификации пользователя на сайте: так вы сможете контролировать, чтобы гость использовал именно свои бонусы, а не чужие.

Метод предрасчета

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

Запрос:

HTTP POST /orders/api/v1/orders/delivery

JSON

Пример запроса:

HTTP POST https://delivery.ucs.ru/orders/api/v1/orders/delivery

JSON

Пример данных тела запроса:

{
   "dishList":[
      {
         "id":"b5a5e2e8-958e-765c-2822-d5cf7c60df7d",
         "name":"Салат Мимоза",
         "price":200,
         "discount":0,
         "schemeId":"",
         "description":"",
         "imageUrls":[
            
         ],
         "measure":{
            "value":0,
            "unit":""
         },
         "isContainInStopList":[
            
         ],
         "quantity":1,
         "ingredients":[
            
         ],
         "isListStoped":false
      }
   ],
   "address":null,
   "expectedAt":"2022-06-16T09:41:08.278+03:00",
   "soonest":true,
   "useLoyalty":true,
   "restaurantId":"18f550d8-7fbe-45fa-8c83-35f531380f65",
   "phone":"71111111111",
   "expeditionType":"pickup",
   "useLoyaltyBonusPayments":false,
   "orderId":"",
   "manualDiscounts":[
   ],
   "loyaltyPromo":[
      "PROMOCODE1"
   ],
   "hideLoader":true
}

JSON

Параметр	Тип параметра	Описание
dishList	array	состав заказа
-id	string	id блюда(формат GUID) из представления меню Delivery, которое используется для синхронизации с кассой
-name	string	наименование блюда
-price	double разделителем всегда будет точка - "."	цена блюда
-discount	double	скидка
-measure		мера
--value	double	размер порции
--unit	string	единица измерения: кг, литр, шт. Значение не словарное
-quantity	double разделителем всегда будет точка - "."	количество блюд
-ingredients	array	ингредиенты
--id	string	id ингредиента (формат GUID) из представления меню Delivery, которое используется для синхронизации с кассой
--name	string	наименование ингредиента
--price	double разделителем всегда будет точка - "."	цена ингредиента
--quantity	double разделителем всегда будет точка - "."	количество ингредиента
--ingredients	array	модификаторы
---id	string	id модификатора (формат GUID) из представления меню Delivery, которое используется для синхронизации с кассой
---name	string	наименование модификатора
---price	double разделителем всегда будет точка - "."	цена модификатора
---quantity	double разделителем всегда будет точка - "."	количество модификатора
-isListStoped	string	находится ли в стоп-листе
address		адрес доставки В случае самовывоза принимает значение null. Пример параметров при указании адреса читайте в статье Создание заказа
expectedAt	DateTime	время к которому ожидается заказ
soonest	bool	привезти заказа как можно скорее Если принимает значение true, то значение параметра expectedAt можно не отправлять: система рассчитает его автоматически. Если принимает значение false, то параметр expectedAt — обязателен
useLoyalty	bool	использование лояльности в заказу Принимает значение true – если лояльность используется. Принимает значение false – если не используется.
restaurantId	string	id ресторана
phone	string	номер телефона гостя
expeditionType	string	тип доставки
useLoyaltyBonusPayments	string	списание бонусов лояльности
orderId	string	id заказа
manualDiscounts		ручные скидки В случае применения лояльности параметр не используется. О применении ручных скидок читайте статье Создание заказа с кассовой скидкой.
loyaltyPromo	string array	Список промокодов для применения

Параметры, отвечающие за лояльность:

useLoyalty — указывает, собирается ли гость использовать программу лояльности
useLoyaltyBonusPayments — указывает, собирается ли гость использовать бонусы лояльности
phone — номер телефона гостя. Это главный параметр, отвечающий за связь заказа с программой лояльности, так как r_k Loyalty идентифицирует гостя по номеру телефона.

Накопление или списание бонусов

Пример ответа метода предрасчета, если происходит накопление или списание бонусов по программе лояльности:

{
   "result":{
      "amount":{
         "totalAmount":100.00,
         "orderAmount":200.00,
         "deliveryAmount":0.0,
         "discountDeliveryAmount":null,
         "minOrderAmountFreeDelivery":0.0,
         "needForFree":0.0,
         "dishList":[
            {
               "id":"b5a5e2e8-958e-765c-2822-d5cf7c60df7d",
               "name":"Салат Мимоза",
               "price":200.0,
               "measure":{
                  "value":0.0,
                  "unit":""
               },
               "quantity":1.0,
               "ingredients":[
                  
               ],
               "discount":0.0
            }
         ],
         "loyaltyAmount":{
            "totalAmount":100.00,
            "loyaltyDiscountAmount":100.0,
            "bonuses":{
               "guestBalance":1230.58,
               "rankName":"Платиновый\t",
               "maxBonusesForPayment":100.0,
               "accrualWithPayment":5.0,
               "accrualWithoutPayment":10.0
            },
            "loyaltyPrograms":[
               
            ],
            "fingerPrint":"eyJQYXR0ZXJuIjowLCJPcmRlckhhc2giOjE3NzY2NDAzNzYsIkRpc2NvdW50U3VtIjowLjB9",
            "useRkLoyalty":true,
            "useLoyaltyBonusPayments":true
         },
         "discounts":{
            "useRk7Discounts":false,
            "total":100.0,
            "discount":0.0,
            "discountList":[
               
            ]
         }
      },
      "times":{
         "deliveryTime":360
      }
   }
}

JSON

где:

loyaltyAmount — блок, содержащий данные о лояльности
- totalAmount — общая сумма заказа
- loyaltyDiscountAmount — общая сумма скидки на заказ, включая бонусы, если они будут списаны
- bonuses — блок, отвечающий за данные о бонусах гостя
  - guestBalance — текущий баланс бонусов гостя
  - rankName — текущий ранг гостя.
  - maxBonusesForPayment — максимальное количество бонусов, доступных к списанию у данного гостя
  - accrualWithPayment — сколько бонусов будет накоплено, если будет списание бонусов в данном заказе
  - accrualWithoutPayment — сколько бонусов будет накоплено, если не будет списания бонусов в данном заказе.

Скидка по программе лояльности

Пример ответа метода предрасчета, если может быть применена скидка по программе лояльности:

{
   "result":{
      "amount":{
         "totalAmount":1260.00,
         "orderAmount":1400.00,
         "deliveryAmount":0.0,
         "discountDeliveryAmount":null,
         "minOrderAmountFreeDelivery":0.0,
         "needForFree":0.0,
         "dishList":[
            {
               "id":"b5a5e2e8-958e-765c-2822-d5cf7c60df7d",
               "name":"Салат Мимоза",
               "price":200.0,
               "measure":{
                  "value":0.0,
                  "unit":""
               },
               "quantity":7.0,
               "ingredients":[
                  
               ],
               "discount":0.0
            }
         ],
         "loyaltyAmount":{
            "totalAmount":1260.00,
            "loyaltyDiscountAmount":140.0,
            "bonuses":{
               "guestBalance":1230.58,
               "rankName":"Платиновый\t",
               "maxBonusesForPayment":0.0,
               "accrualWithPayment":0.0,
               "accrualWithoutPayment":0.0
            },
            "loyaltyPrograms":[
               {
                  "programName":"Базовая акция скидка на чек 10% за чек от 1000р",
                  "programNotification":[
                     "Вы получили скидку 10% по акции \"Базовая акция скидка на чек 10% за чек от 1000р\"."
                  ]
               }
            ],
            "fingerPrint":"eyJQYXR0ZXJuIjowLCJPcmRlckhhc2giOi0zNDA5MTI4NTMsIkRpc2NvdW50U3VtIjoxNDAuMDB9",
            "useRkLoyalty":true,
            "useLoyaltyBonusPayments":true
         },
         "discounts":{
            "useRk7Discounts":false,
            "total":1260.0,
            "discount":0.0,
            "discountList":[
               
            ]
         }
      },
      "times":{
         "deliveryTime":360
      }
   }
}

JSON

где:

loyaltyAmount — блок, содержащий данные о лояльности
- totalAmount — общая сумма заказа
- loyaltyDiscountAmount — общая сумма скидки на заказ, включая бонусы, если они будут списаны
- loyaltyPrograms[] — блок данных о сработанной акции
  - programName — название акции
  - programNotification[] — сообщение о скидке, которое задается в административной панели r_k Loyalty.

Скидка по промокоду

Пример ответа метода предрасчета, если может быть применена скидка по промокоду лояльности:

{
   "result":{
      "amount":{
         "totalAmount":1300.00,
         "orderAmount":1400.00,
         "deliveryAmount":0.0,
         "discountDeliveryAmount":null,
         "minOrderAmountFreeDelivery":0.0,
         "needForFree":0.0,
         "dishList":[
            {
               "id":"b5a5e2e8-958e-765c-2822-d5cf7c60df7d",
               "name":"Салат Мимоза",
               "price":200.0,
               "measure":{
                  "value":0.0,
                  "unit":""
               },
               "quantity":7.0,
               "ingredients":[
                  
               ],
               "discount":0.0
            }
         ],
         "loyaltyAmount":{
            "totalAmount":1300.00,
            "loyaltyDiscountAmount":100.0,
            "bonuses":{
               "guestBalance":1230.58,
               "rankName":"Платиновый\t",
               "maxBonusesForPayment":0.0,
               "accrualWithPayment":0.0,
               "accrualWithoutPayment":0.0
            },
            "loyaltyPrograms":[
               {
                  "programName":"Cкидка по промокоду PROMOCODE1",
                  "programNotification":[
                     "Вы получили скидку 100 р. по промокоду PROMOCODE1."
                  ]
               }
            ],
            "loyaltyPromo": [ "PROMOCODE1" ]
            "fingerPrint":"eyJQYXR0ZXJuIjowLCJPcmRlckhhc2giOi0zNDA5MTI4NTMsIkRpc2NvdW50U3VtIjoxNDAuMDB9",
            "useRkLoyalty":true,
            "useLoyaltyBonusPayments":true
         },
         "discounts":{
            "useRk7Discounts":false,
            "total":1300.0,
            "discount":0.0,
            "discountList":[
               
            ]
         }
      },
      "times":{
         "deliveryTime":360
      }
   }
}

JSON

где:

loyaltyAmount — блок, содержащий данные о лояльности
- totalAmount — общая сумма заказа
- loyaltyDiscountAmount — общая сумма скидки на заказ, включая бонусы, если они будут списаны
- loyaltyPrograms[] — блок данных о сработанной акции
  - programName — название акции
  - programNotification[] — сообщение о скидке, которое задается в административной панели r_k Loyalty.

Создание заказа

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

Пример запроса:

POST https://delivery.ucs.ru/orders/api/v1/orders

Content-Type: application/json

JSON

Пример данных тела запроса:

{
   "comment":"",
   "restaurantId":"18f550d8-7fbe-45fa-8c83-35f531380f65",
   "persons":1,
   "expeditionType":"pickup",
   "paymentTypeId":"cash",
   "courierId":"",
   "soonest":true,
   "expectedAt":"2022-06-16T10:07:08.278+03:00",
   "dishList":[
      {
         "id":"b5a5e2e8-958e-765c-2822-d5cf7c60df7d",
         "name":"Салат Мимоза",
         "price":200,
         "discount":0,
         "measure":{
            "value":0,
            "unit":""
         },
         "isContainInStopList":[
            
         ],
         "quantity":7,
         "ingredients":[
            
         ]
      },
      {
         "id":"b5a5e2e8-958e-765c-2822-d5cf7c60df7d",
         "name":"Салат Мимоза",
         "price":200,
         "discount":0,
         "measure":{
            "value":0,
            "unit":""
         },
         "isContainInStopList":[
            
         ],
         "quantity":1,
         "ingredients":[
            
         ]
      }
   ],
   "changeFrom":null,
   "guest":{
      "firstName":"Денис",
      "lastName":"",
      "phone":"71111111111",
      "email":null
   },
   "loyaltyCalculation":{
      "loyaltyDiscountAmount":160,
      "totalAmount":1440,
      "loyaltyPrograms":[
         {
            "programName":"Базовая акция скидка на чек 10% за чек от 1000р",
            "programNotification":[
               "Вы получили скидку 10% по акции \"Базовая акция скидка на чек 10% за чек от 1000р\"."
            ]
         }
      ],
      "bonuses":{
         "guestBalance":1230.58,
         "rankName":"Платиновый\t",
         "maxBonusesForPayment":0,
         "accrualWithPayment":0,
         "accrualWithoutPayment":0
      },
      "fingerPrint":"eyJQYXR0ZXJuIjowLCJPcmRlckhhc2giOjI1NzQ0ODc3OSwiRGlzY291bnRTdW0iOjE2MC4wMH0=",
      "useRkLoyalty":true,
      "useLoyaltyBonusPayments":true
   },
   "discounts":{
      "discount":0,
      "total":1440,
      "discountList":[
         
      ],
      "useRk7Discounts":false
   },
   "discountDeliveryAmount":null
}

JSON

где

loyaltyCalculation — блок данных, полученных в методе предрасчета заказа в блоке loyaltyAmount.

Подробнее о запросе и параметрах читайте в статье Создание заказа.

Пример ответа:

{
   "result":{
      "orderId":"123"
   }
}

JSON

где orderId — это номер заказа.

Редактирование заказа

Чтобы отредактировать заказ после его создания, необходимо сбросить предварительный расчет заказа. Если этого не сделать, то могут возникнуть проблемы с заморозкой бонусов гостя. Для сброса предрасчета используйте метод:

HTTP POST https://delivery.ucs.ru/orders/api/v1/orders/{orderId}/resetLoyalty

JSON

где orderId — это номер заказа, который был получен в ответе на метод создания заказа. Например, 123, как в ответе выше.

Тело запроса — пустое.

Далее сделайте запрос предрасчета с номером заказа. Пример запроса:

HTTP POST https://delivery.ucs.ru/orders/api/v1/orders/delivery
{
   "dishList":[
      {
         "id":"66a506b9-ce54-26f6-c582-dc884f7d02f3",
         "name":"Чизбургер",
         "price":100,
         "discount":0,
         "schemeId":"",
         "description":"",
         "imageUrls":[
            
         ],
         "measure":{
            "value":0,
            "unit":""
         },
         "isContainInStopList":[
            
         ],
         "quantity":1,
         "ingredients":[
            
         ]
      }
   ],
   "address":null,
   "expectedAt":"2022-06-16T10:14:58.502+03:00",
   "useLoyalty":true,
   "restaurantId":"18f550d8-7fbe-45fa-8c83-35f531380f65",
   "phone":"72222222222",
   "expeditionType":"pickup",
   "useLoyaltyBonusPayments":false,
   "orderId":"128763",
   "manualDiscounts":[
      
   ],
   "hideLoader":true
}

JSON

Только после повторного запроса предрасчета можно приступать к редактированию заказа. Пример метода запроса редактирования заказа:

HTTP PATCH https://delivery.ucs.ru/orders/api/v1/orders/{orderId}

JSON

Пример тела запроса:

{
   "paymentTypeId":"cash",
   "dishList":[
      {
         "id":"66a506b9-ce54-26f6-c582-dc884f7d02f3",
         "name":"Чизбургер",
         "price":100,
         "discount":0,
         "measure":{
            "value":0,
            "unit":""
         },
         "isContainInStopList":[
            
         ],
         "quantity":1,
         "ingredients":[
            
         ]
      }
   ],
   "loyaltyCalculation":{
      "loyaltyDiscountAmount":0,
      "totalAmount":100,
      "loyaltyPrograms":[
         
      ],
      "bonuses":{
         "guestBalance":3.21,
         "rankName":"Бронзовый",
         "maxBonusesForPayment":3.21,
         "accrualWithPayment":1.94,
         "accrualWithoutPayment":2
      },
      "fingerPrint":"eyJQYXR0ZXJuIjowLCJPcmRlckhhc2giOi0xODU2ODkwNDM2LCJEaXNjb3VudFN1bSI6MC4wfQ==",
      "useRkLoyalty":true,
      "useLoyaltyBonusPayments":false
   }
}

JSON

где

loyaltyCalculation — блок данных, полученных в последнем методе предрасчета заказа в блоке loyaltyAmount.

Подробнее о запросе и параметрах читайте в статье Изменение заказа.