Creating an order with paid delivery

Introduction

This article explores a scenario for creating an order with paid delivery on a restaurant website.

The basics of interaction between a restaurant website and r_k Delivery are described in the articles API Capabilities.

Basic scenario for creating an order with paid delivery:

Get an order estimate to display delivery costs before creating an order
Creating an order.

Presets

Before creating an order:

Set up your establishment in r_k Delivery
Set up an API connection for your website backend or restaurant app backend.

Pre-calculation method

Use the order pre-calculation method to get delivery cost estimates when a guest places an order.

The method should be used after completing or changing order details that affect delivery costs, such as:

Order amount
Delivery address
Restaurant.

If the delivery method is self-pickup, then there is no need to calculate the cost of delivery, and therefore, there is no need to use the pre-calculation method.

Request:

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

CODE

Example request:

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

CODE

Example of request body data:

{
   "dishList":[
      {
         "id":"b5a5e2e8-958e-765c-2822-d5cf7c60df7d",
         "name":"Mimosa Salad",
         "price":200,
         "discount":0,
         "schemeId":"",
         "description":"",
         "imageUrls":[
            
         ],
         "measure":{
            "value":0,
            "unit":""
         },
         "isContainInStopList":[
            
         ],
         "quantity":1,
         "ingredients":[
            
         ],
         "isListStoped":false
      }
   ],
   "address": {
       "postcode": "109443",
       "cityId": "73439fb3-c0c4-42ca-a269-64f031a6a33b",
       "street": "Yunykh Lenintsev",
       "comment": " the house is to the right of the school",
       "lat": "55.700897",
       "lon": "37.773808",
       "cityName": "Moscow",
       "entrance": "1",
       "houseNumber": "85",
       "apartmentNumber": "6",
       "subway": "Kuzminki",
       "fullAddress": "109443, Moscow, Yunykh Lenintsev st., 85 sec. 2, app. 6"
    },
   "expectedAt":"2022-06-16T09:41:08.278+03:00",
   "soonest":true,
   "useLoyalty":false,
   "restaurantId":"18f550d8-7fbe-45fa-8c83-35f531380f65",
   "phone":"71111111111",
   "expeditionType":"delivery",
   "useLoyaltyBonusPayments":false
}

CODE

Parameter	Parameter type	Description
dishList	array	order contents
-id	string	dish id (GUID format) from the Delivery menu view, which is used to synchronize with the cash register
-name	string	name of the dish
-price	double the separator will always be a period - "."	price of the dish
-discount	double	discount
-measure		measure
--value	double	serving size
--unit	string	unit of measurement: kg, liter, pcs. The meaning is not a dictionary one.
-quantity	double the separator will always be a period - "."	number of dishes
-ingredients	array	ingredients
--id	string	ingredient id (GUID format) from the Delivery menu view, which is used to sync with the cash register
--name	string	name of ingredient
--price	double the separator will always be a period - "."	ingredient price
--quantity	double the separator will always be a period - "."	quantity of ingredient
--ingredients	array	modifiers
---id	string	modifier id (GUID format) from the Delivery menu view, which is used for synchronization with the checkout
---name	string	modifier name
---price	double the separator will always be a period - "."	modifier price
---quantity	double the separator will always be a period - "."	modifier amount
-isListStoped	string	is it in the out-of-stock list
address		delivery address In case of self-pickup, it takes the value null. For an example of parameters when specifying an address, see the article Creating an order
expectedAt	DateTime	time by which the order is expected
soonest	bool	deliver the order as soon as possible If it takes the value true, then the expectedAt parameter value does not need to be sent: the system will calculate it automatically. If it takes the value false, then the expectedAt parameter is mandatory.
useLoyalty	bool	using loyalty in order Returns true if loyalty is used. Returns false if not used.
restaurantId	string	restaurant id
phone	string	guest phone number
expeditionType	string	delivery type pickup - self-pickup delivery - delivery
useLoyaltyBonusPayments	string	write-off of loyalty bonuses. If not used - false
orderId	string	order id, if the calculation is made for an existing order for the purpose of editing it

Displaying the cost of delivery to the guest on the site

If the delivery is paid, then its cost is calculated based on the zone conditions. The conditions of paid delivery are configured in the r_k Delivery administrative panel. For more information, see the article Delivery zones.

Example of a response from the pre-calculation method:

{
   "result":{
      "amount":{
         "totalAmount":200.0,
         "orderAmount":100.00,
         "deliveryAmount":100.0,
         "discountDeliveryAmount":0.0,
         "minOrderAmountFreeDelivery":600.0,
         "needForFree":600.0,
         "dishList":[
            {
               "id":"c4f7e375-0791-88c3-75cf-a8727744bf79",
               "name":"Crab salad",
               "price":100.0,
               "measure":{
                  "value":0.0,
                  "unit":"",
                  "calcByWeight":false,
                  "weight":0.0,
                  "priceMode":"",
                  "qntDecDigits":0,
                  "changeQntOnce":null,
                  "joinMode":""
               },
               "quantity":1.0,
               "ingredients":[
                  
               ],
               "discount":0.0,
               "comment":""
            }
         ]
      },
      "times":{
         "deliveryTime":360
      }
   }
}

CODE

Parameter	Parameter type	Description
result	compound object	Result object with response parameters
-amount	compound object	Object with order amounts
--deliveryAmount	double the separator will always be a period - "."	Estimated delivery cost
--orderAmount	double the separator will always be a period - "."	Order amount excluding delivery costs
--totalAmount	double the separator will always be a period - "."	Order amount including delivery costs

Displaying free delivery cost to guest on website

Free delivery conditions are configured in the r_k Delivery administrative panel. For more information, see the Delivery Zones article.

Example of a pre-calculation method response if delivery is free:

{
   "result":{
      "amount":{
         "totalAmount":100.0,
         "orderAmount":100.00,
         "deliveryAmount":0.0,
         "discountDeliveryAmount":0.0,
         "minOrderAmountFreeDelivery":50.0,
         "needForFree":0.0,
         "dishList":[
            {
               "id":"c4f7e375-0791-88c3-75cf-a8727744bf79",
               "name":"Crab salad",
               "price":100.0,
               "measure":{
                  "value":0.0,
                  "unit":"",
                  "calcByWeight":false,
                  "weight":0.0,
                  "priceMode":"",
                  "qntDecDigits":0,
                  "changeQntOnce":null,
                  "joinMode":""
               },
               "quantity":1.0,
               "ingredients":[
                  
               ],
               "discount":0.0,
               "comment":""
            }
         ]
      },
      "times":{
         "deliveryTime":360
      }
   }
}

CODE

Creating an order

After the delivery cost is displayed, the guest confirmed the order. Now you need to create the order using the Create order request.

Example request:

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

Content-Type: application/json

CODE

Request body example:

{
   "comment":"",
   "persons":1,
   "expeditionType":"delivery",
   "paymentTypeId":"card",
   "soonest":true,
   "dishList":[
      {
         "id":"c4f7e375-0791-88c3-75cf-a8727744bf79",
         "categoryId":"",
         "name":"Crab salad",
         "price":100,
         "discount":0,
         "measure":{
            "value":0,
            "unit":"",
            "weight":0,
            "calcByWeight":false,
            "qntDecDigits":0,
            "joinMode":"",
            "priceMode":""
         },
         "isContainInStopList":[
            
         ],
         "quantity":1,
         "ingredients":[
            
         ],
         "comment":""
      }
   ],
   "changeFrom":null,
   "guest":{
      "firstName":"1",
      "lastName":"",
      "phone":"71111111111",
      "email":null
   },
   "address":{
      "id":"437bc228-5d0b-47df-91af-d21c899a0474",
      "postcode":"",
      "street":"Kremlin Cadets Alley",
      "comment":"The intercom does not work",
      "lat":55.678555,
      "lon":37.783842,
      "cityName":"Moscow",
      "apartmentNumber":"1",
      "houseNumber":"11",
      "entrance":"1",
      "intercom":"1",
      "fullAddress":"Kremlin Cadets Alley, 11",
      "subway":"",
      "floor":1,
      "building":""
   },
   "restaurantId":"18f550d8-7fbe-45fa-8c83-35f531380f65"
}

CODE

For more information about the request and its parameters, see the article Creating an order.

Please note: when creating an order, you do not need to additionally specify the delivery cost in the request itself, it will be added automatically.

Example answer:

{
   "result":{
      "orderId":"67598"
   }
}

CODE

where orderId is the order number.

If, when placing an order on the website, the following parameters have changed:

The order amount. For example, the composition of the dishes has changed
Delivery address
The restaurant to which the order is planned to be sent

To display the current delivery amount, you should reuse the /delivery pre-calculation method.