Delivety API
Here in Delivety, we are trying to keep things as simple as we can. So the Delivety API is.
In this guide, you’ll find comprehensive information on how to use Delivety API to begin sending the orders from your existing website or app to your Delivety web application.
We would like to help you start working with Delivety API as quickly as possible, so if you have any questions, we are here to help you.
Introduction
The Delivety API is a RESTful web service for developers to send order data from their existing website or app to Delivety webhook URL.
Delivety webhook URL
To interact with Delivety API, you will need to sign up for a Delivety account. Once you have created an account with us, open the Domain section of your Delivety Admin Dashboard, then select the domain that you would like to have your website or app integrated with (or create a new domain, if you don’t have one yet). Next, select “Receive orders from the existing website”. The dedicated webhook URL will show up. Now it’s time to make your website or app send the orders data to that webhook URL.
Using webhooks
Your website or app has to send HTTPS callback to the Delivety webhook URL each time the customer places the order on your website or app. If it is successfully received, then Delivety responds with 2xxHTTP and the order will immediately appear in the Operator Dashboard. Kindly note that there are requirements in order for the HTTPS callback to be successfully processed..
Always Use HTTPS
Calls made over plain HTTP will fail. API requests missing mandatory parameters will also fail.
Throttling
You may not perform more than 10 requests per second across all of your company's webhook URLs. If you exceed the 10 requests per second threshold, then you will first receive a 426 error. Failure to slow down your request rate may result in a temporary ban
Security
You are responsible for the secure usage of the webhook URLs we provide to you. Should you compromise one, you can regenerate the new one for the appropriate domain in the Domain section of your Delivety Admin Dashboard. Do not forget that, beginning from that moment, you will have to send the POST request to the new webhook URL that you’ve created.
Data Types and Formats
With very few exceptions, numbers are numbers, and not strings. The API strictly adheres to the most natural representation of the underlying data, and null is always returned for optional properties that have not yet been assigned a value.
Geographic coordinates are formatted as [ longitude, latitude ], as per the GeoJSON standard.
Timestamps are consumed and produced in Unix epoch time format, with millisecond precision.
Phone numbers will always be returned in E.164 format; however, they may be provided in E.164 or a localized format that is valid based on your company's country configuration. If you wish to provide numbers from countries other than your company's, then you must use E.164 only. We strongly recommend the use of libraries like libphonenumber for managing phone number validation and formatting.
How to Send Data
Post Request
Send the data as a POST request with a body containing the following parameters:
| Parameter | Description |
|---|---|
| phone | Customer’s phone number, only numeric symbols accepted. Serves as a customer id. |
| id | Order ID according to your website or app system of order identification. |
| first_name | Customer’s first name. You can include their last name here, as well (optional). |
| Customer’s email (optional). | |
| address | Customer’s address (optional). |
| comment | Customer’s note or comment (optional). |
| delivery_date | The date when the order has to be delivered. This is the optional parameter. The order will get the TODAY delivery date if the parameter is missing. |
| delivery_time | The time when the order has to be delivered. This is the optional parameter. The order will get the ASAP delivery time if the parameter is missing. |
| product | Ordered products (array, see below) |
| payment | Payment data (optional array, see below). The order will get the UNPAID status if the array is missing. |
| promotion | Promotion data (optional array, see below) |
Product Array
The product array must contain the following parameters:
| Parameter | Description |
|---|---|
| api_id | The dish ID according to your website’s or app’s system of dish identification. You must set the same API IDs as the product IDs for every single dish in your Delivety Menu Builder |
| count | The quantity of the dishes of the particular api_id |
| price | The price of the dish of the particular api_id |
Payment Array
The payment array must contain the following parameters:
| Parameter | Description |
|---|---|
| type | The payment method used for this order. The value must contain:
“1” if the order paid is with cash, or “2” if the order paid is with card, or “3” if the order paid is with card-on-delivery |
| status | The status of the card payment used for this order. The value must contain:
“-1” if the payment is reimbursed “0” if the payment has been canceled “1” if the payment has not yet been processed “2” if the payment has been processed successfully |
| sum | The sum of all items’ prices in the order. In most cases, this is the total amount of the order before deducting any discounts and/or payment processing fees (reciver_commission). |
| amount | The total amount paid (or to be paid) for the order. In most cases, the amount equals the sum minus discount and payment processor commission (reciver_commission) |
| public_key | The optional parameter for the card payments to identify the account number to process the payment to. This parameter is used if you have more than one bank account and/or use multiple payment processors and prefer to distinguish them in Delivety. |
| reciver_commission | The payment processor commission, if any. |
Promotion Array
The promotion array must contain the following parameters:
| Parameter | Description |
|---|---|
| discount | The optional parameter that contains the total amount of discount in the order. |
| discount_percent | The optional parameter that contains the percentage of discount in the order. |
| discount_code | The optional parameter that contains the alphanumeric coupon code applied to the order. |
| involved_dishes | The optional array that contains dishes involved in the promotion. |
| resulted_dishes | The optional array that contains dishes that are the result of the promotion. |
Resulted Dishes Array
The resulted_dishes array must contain the following optional parameters:
| Parameter | Description |
|---|---|
| api_id | The id of the dish which is the result of the promotion. You must not send this dish in the product array |
| count | The quantity of the dishes of the particular api_id |
| modification | The price modification of the dish which is the result of the promotion |
Post Request
The example of the PHP code of successful POST request shown below illustrates the order, with the two dishes ordered (api_id = 139, api_id = 385) with a 10% discount and one received for free, in the result of reducing the price:
$url = 'https://delivety.com/hooks/catch/sdf34asdv1';
$incoming_order = [
"access_token" => "ACCESS_TOKEN_HERE",
"phone" => '123680000000',
"id" => 123456,
"first_name" => 'John Dowe',
"email" => '[email protected]',
"address" => '123, Sunset blvd',
"comment" => 'no sesame please',
"delvery_date" => '2021-12-31',
"delvery_time" => '18:45:00',
"products" => [
[
"api_id" => 139,
"count" => 1,
"price" => 15
],
[
"api_id" => 385,
"count" => 1,
"price" => 18
],
],
"payment" => [
"type" => 2,
"status" => 2,
"sum" => 33,
"amount" => 28.95,
"receiver_commision" => 1.05
],
"promotion" => [
"discount_percent" => 10,
"involved _dishes" => [
[
"api_id" => 139,
"count" => 1
],
[
"api_id" => 385,
"count" => 1
]
],
"resulted _dishes" => [
[
"api_id" => 598,
"count" => 1,
"modification" => -12
]
]
]
];
$data = sendRequest($url, 'post', $incoming_order);