API Delivety
Тут, в Delivety, ми намагаємося зробити все якомога простіше. І API Delivety саме таким і є, простим у користуванні..
У цьому посібнику ви знайдете вичерпну інформацію про те, як використовувати API Delivety, щоб почати відправляти замовлення з вашого існуючого сайту або додатку у ваш веб-додаток Delivety.
Ми хотіли б допомогти вам почати роботу з API Delivety якнайшвидше, тому, якщо у вас є будь-які запитання, ми будемо раді вам допомогти.
Вступ
API Delivety — це веб-сервіс REST, який дозволяє розробникам надсилати дані про замовлення з існуючого сайту чи додатка на URL-адресу вебхука Delivety.
URL-адреси вебхуків Delivety
Щоб взаємодіяти з API Delivety, вам потрібно зареєструвати обліковий запис Delivery. Після того, як ви створили обліковий запис, відкрийте розділ «Домен» на Адмін Панелі 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 | Дані про рекламу (додатковий масив, див. нижче)
|
Macив Product
Macив Product повинен містити наступні параметри:
| Параметр | Опис |
|---|---|
| api_id | ID страви відповідно до системи ідентифікації страви вашого сайту або додатку. Ви повинні встановити ті самі API ID, що й ID продуктів для кожної окремої страви у вашому Конструкторі меню Delivety
|
| count | Кількість страв для конкретного api_id
|
| price | Ціна страви конкретного api_id
|
Macив Payment
Macив Payment повинен містити такі параметри:
| Параметр | Опис |
|---|---|
| type | Спосіб оплати, використаний для цього замовлення. Значення має містити: «1», якщо замовлення оплачено готівкою, або «2», якщо замовлення оплачено карткою, або «3», якщо замовлення оплачено карткою кур'єру |
| status | Статус оплати карткою, використаний для цього замовлення. Значення має містити: «-1», якщо платіж відшкодовано «0», якщо платіж скасовано «1», якщо платіж ще не оброблено «2», якщо платіж оброблено успішно |
| sum | Сума усіх товарів у замовленні. У більшості випадків це загальна сума замовлення до вирахування будь-яких знижок та/або комісії за обробку платежів (reciver_commission).
|
| amount | Загальна сума, сплачена (або підлягає сплаті) за замовлення. У більшості випадків загальна сума дорівнює сумі мінус знижка та комісія процесора платежу (reciver_commission)
|
| public_key | Додатковий параметр для карткових платежів, щоб ідентифікувати номер рахунку для обробки платежу. Цей параметр використовується, якщо у вас є кілька банківських рахунків та/або користуєтеся кількома платіжними процесорами та віддаєте перевагу розрізняти їх у Delivety.
|
| reciver_commission | Комісія платежної системи, якщо така є.
|
Macив Promotion
Macив Promotion має містити такі параметри:
| Параметр | Опис |
|---|---|
| discount | Додатковий параметр, який містить загальну суму знижки в замовленні.
|
| discount_percent | Додатковий параметр, який містить відсоток знижки в замовленні.
|
| discount_code | Додатковий параметр, який містить буквено-цифровий код купона, застосований до замовлення.
|
| involved_dishes | Необов’язковий масив, який містить страви, якіприймають участь в акції.
|
| resulted_dishes | Необов’язковий масив, який містить страви, які є результатом рекламної акції. |
Macив Resulted Dishes
Масив resulted_dishes повинен містити такі додаткові параметри:
| Параметр | Опис |
|---|---|
| api_id | ID страви, яка є результатом рекламної акції. Не можна відправляти цю страву в Macив 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);