API Delivety
Здесь, в Delivety, мы стараемся сделать все как можно проще. И API Delivety именно таким и есть, простым в использовании.
В этом руководстве вы найдете исчерпывающую информацию о том, как использовать API Delivety, чтобы начать отправлять заказы с вашего существующего сайта или приложения в ваше веб-приложение Delivety.
Мы хотели бы помочь вам начать работу с API Delivety как можно скорее, поэтому, если у вас есть какие-либо вопросы, мы будем рады вам помочь.
Вступление
API Delivery — это веб-сервис REST, позволяющий разработчикам отправлять данные о заказах с существующего сайта или приложения на URL-адрес вебхука Delivety.
URL-адреса вебхуков Delivety
Чтобы взаимодействовать с API Delivety, необходимо зарегистрировать учетную запись Delivety. После того, как вы создали аккаунт, откройте раздел «Домен» на Админ Панели Delivety, а затем выберите домен, с которым вы хотите интегрировать свой сайт или приложение (или создайте новый домен, если у вас его нет). Далее выберите «Получать заказы из существующего сайта». Появится специальный URL-адрес веб-хука. Теперь необходимо, чтобы ваш сайт или приложение отправили данные о заказе на этот URL-адрес веб-хука.
Использование вебхуков
Ваш сайт или приложение должно отправлять обратный вызов HTTPS на URL-адрес веб-хука Delivety каждый раз, когда клиент размещает заказ на вашем сайте или в приложении. Если он успешно получен, Delivety отвечает кодом HTTP 2xx и заказ немедленно появится в Интерфейсе Оператора. Обратите внимание, что для успешной обработки обратного вызова HTTPS существуют требования.
Всегда используйте HTTPS
Вызовы, сделанные по простому HTTP, не будут осуществлены. Также запросы API без обязательных параметров не будут выполнены.
Троттлинг
Вы не можете выполнять более 10 запросов в секунду для всех URL-адресов вебхука вашей компании. Если вы превысите порог 10 запросов в секунду, то сначала вы получите ошибку 426. Если вы не снизите скорость запросов, это может привести к временному бану.
Безопасность
Вы несете ответственность за безопасное использование URL-адресов вебхука, которые мы предоставляем. Если вы скомпрометируете один, вы можете повторно создать новый для соответствующего домена в разделе Домен на Админ Панели Delivety. Не забывайте, что, начиная с этого момента, вам нужно будет отправить POST-запрос на новый URL-адрес вебхука, который вы создали.
Типы данных и форматы
За очень небольшими исключениями, числа являются числами, а не строчками. API строго придерживается наиболее естественного представления базовых данных, и null всегда возвращается для необязательных параметров, которым еще не было назначено значение.
Географические координаты отформатированы как [ longitude, latitude ], согласно стандарту GeoJSON.
Временные метки используются и создаются в формате времени Unix Epoch с точностью до миллисекунды.
Телефонные номера всегда возвращаются в формате E.164; однако они могут предоставляться как в формате E.164, так и в локализованном формате, допустимом в зависимости от страны в конфигурации вашей компании. Если вы хотите предоставить номера из стран, которые отличаются от вашей компании, вам следует использовать только E.164. Рекомендуется использовать такие библиотеки, как libphonenumber, для управления проверкой и форматированием телефонных номеров.
Как отправлять данные
Post-запрос
Отправьте данные как POST-запрос с телом, содержащим следующие параметры:
| Параметр | Описание |
|---|---|
| phone | Номер телефона клиента, принимаются только цифровые символы. Служит как ID клиента. |
| id | ID заказа в соответствии с системой идентификации заказа на вашем сайте или приложении. |
| first_name | Имя клиента. Вы также можете указать и фамилию (необязательно). |
| Электронный адрес клиента (необязательно). | |
| address | Адрес клиента (необязательно). |
| comment | Примечание или комментарий клиента (необязательно). |
| delivery_date | Дата, когда заказ должен быть доставлен. Это необязательный параметр. Заказ получит статус доставки СЕГОДНЯ, если параметр отсутствует. |
| delivery_time | Время, когда заказ должен быть доставлен. Это необязательный параметр. Заказ получит статус доставки Как можно скорее, если параметр отсутствует. |
| product | Заказанные товары (массив, см. ниже) |
| payment | Платежные данные (дополнительный массив, см. ниже). Заказ получит статус Неоплачено, если массив отсутствует. |
| promotion | Данные о рекламе (дополнительный массив, см. ниже) |
Массив Product
Maccив Product должен содержать следующие параметры:
| Параметр | Описание |
|---|---|
| api_id | ID блюда в соответствии с системой идентификации блюда вашего сайта или приложения. Вы должны установить те же API ID, что и ID продуктов для каждого отдельного блюда в Конструкторе меню Delivety |
| count | Количество блюд для конкретного api_id |
| price | Цена блюда конкретного api_id |
Массив Payment
Maccив Payment должен содержать следующие параметры:
| Параметр | Описание |
|---|---|
| type | Способ оплаты, использованный для этого заказа. Значение должно содержать:
«1», если заказ оплачен наличными, или «2», если заказ оплачен картой, или «3», если заказ оплачен картой курьеру |
| status | Статус оплаты картой, использованный для этого заказа. Значение должно содержать:
«-1», если платеж возмещен «0», если платеж отменен «1», если платеж еще не обработан «2», если платеж обработан успешно |
| sum | Сумма всех товаров в заказе. В большинстве случаев это общая сумма заказа до вычета любых скидок и/или комиссии за обработку платежей (reciver_commission). |
| amount | Общая сумма, уплаченная (или подлежащая уплате) за заказ. В большинстве случаев общая сумма составляет сумму минус скидка и комиссия процессора платежа (reciver_commission) |
| public_key | Дополнительный параметр для карточных платежей, чтобы идентифицировать номер счета для обработки платежа. Этот параметр используется, если у вас есть несколько банковских счетов и/или вы пользуетесь несколькими платежными процессорами и предпочитаете их различать в Delivety. |
| reciver_commission | Комиссия платежной системы, если таковая имеется. |
Массив Promotion
Maccив Promotion должен содержать следующие параметры:
| Параметр | Описание |
|---|---|
| discount | Дополнительный параметр, содержащий общую сумму скидки в заказе. |
| discount_percent | Дополнительный параметр, содержащий процент скидки в заказе. |
| discount_code | Дополнительный параметр, содержащий буквенно-цифровой код купона, применим к заказу. |
| involved_dishes | Необязательный массив, содержащий блюда, принимающие участие в акции. |
| resulted_dishes | Необязательный массив, содержащий блюда, которые есть результатом рекламной акции. |
Массив Resulted Dishes
Массив resulted_dishes должен содержать следующие дополнительные параметры:
| Параметр | Описание |
|---|---|
| api_id | ID блюда, который есть результатом рекламной акции. Нельзя отправлять это блюдо в Maccив Product |
| count | Количество блюд определенного api_id |
| modification | Изменение цены на блюдо в результате акции |
Post-запрос
Пример PHP-кода успешного POST-запроса, показанный ниже, иллюстрирует заказы с двумя заказанными блюдами (api_id = 139, api_id = 385) со скидкой 10% и одним блюдом, полученным бесплатно в результате снижения цены:
$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);