External Orders API
1. Загальна інформація
External Orders API
Опис: API, який дозволяє зовнішнім системам та інтеграціям керувати статусами замовлень на платформі Dots. Зовнішні сервіси (такі як POS-системи, агрегатори доставки або кастомні інтеграції) можуть приймати, завершувати, відхиляти або позначати замовлення як невдалі через API-виклики.
2. Автентифікація
2.1 Необхідні заголовки
Кожен API-запит повинен містити ці заголовки:
· App-Auth-Token — токен автентифікації користувача, який виконує дію (обов'язковий).
· App-Account-Token — токен, що ідентифікує бізнес-акаунт (обов'язковий).
· Content-Type: application/json — для запитів з тілом.
2.2 Де отримати Auth Token
Щоб отримати App-Auth-Token, зверніться до адміністратора платформи. Токен прив'язаний до конкретного користувача і за замовчуванням не має терміну дії.
Важливо! Користувач, прив'язаний до токена, повинен мати дозвіл order.edit. Без нього всі запити будуть відхилені з помилкою 403.Корисно! Рекомендується створювати окремого користувача та токен для кожної інтеграції.3. API-ендпоінти
Всі ендпоінти використовують токен замовлення як URL-параметр — унікальний рядковий ідентифікатор замовлення.
3.1 Прийняття замовлення компанією
POST /orders/{order}/accept
Приймає замовлення від імені компанії та встановлює час приготування.
Тіло запиту:
· timeMadeIn (integer, обов'язковий) — timestamp приготування у хвилинах.
Приклад:
{ "timeMadeIn": 1774624708 }
3.2 Прийняття замовлення на доставку
POST /orders/{order}/accept-delivery
Позначає замовлення як прийняте на доставку кур'єром. Тіло запиту не потрібне.
3.3 Приготування завершено
POST /orders/{order}/preparation-finished
Позначає, що компанія завершила приготування замовлення. Тіло запиту не потрібне.
3.4 Доставку завершено
POST /orders/{order}/delivery-finished
Позначає доставку як завершену. Тіло запиту не потрібне.
3.5 Завершення замовлення
POST /orders/{order}/finish
Позначає замовлення як повністю завершене (фінальний статус). Тіло запиту не потрібне.
3.6 Відхилення замовлення компанією
POST /orders/{order}/decline-by-company
Компанія відхиляє замовлення з вказаною причиною.
Тіло запиту:
· declinedReasonType (integer, обов'язковий) — код причини відхилення.
Приклад:
{ "declinedReasonType": 1 }
3.7 Невдале замовлення
POST /orders/{order}/fail
Позначає замовлення як невдале. Тіло запиту не потрібне.
3.8 Скасування замовлення (користувачем)
POST /orders/{order}/decline
Скасовує замовлення від імені користувача.
3.9 Отримання інформації про замовлення
GET /orders/{order}
Повертає детальну інформацію про замовлення: статус, ціни, товари, інформацію про доставку, часові мітки.
4. Потік статусів замовлення
Типовий успішний потік:
- accept — Компанія приймає замовлення та встановлює час приготування.
- accept-delivery — Кур'єр приймає доставку.
- preparation-finished — Компанія завершує приготування.
- delivery-finished — Кур'єр доставляє замовлення.
- finish — Замовлення завершене.
У будь-який момент замовлення також може бути:
· decline — Скасовано користувачем.
· decline-by-company — Відхилено компанією (з причиною).
· fail — Позначено як невдале.
Зверніть увагу! Не всі переходи валідні з кожного статусу. Платформа валідує переходи та повертає помилку для невалідних.5. Коди відповідей
· 200 OK — Дію виконано успішно. Відповідь: ["Ok"].
· 400 Bad Request — Відсутній обов'язковий параметр або невалідний перехід статусу.
· 401 Unauthorized — Відсутній або невалідний App-Auth-Token.
· 403 Forbidden — Користувач не має необхідного дозволу.
· 404 Not Found — Замовлення не знайдено.
6. Приклади використання
Приклад 1: POS-інтеграція — Прийняти та приготувати
POS-система отримує нове замовлення і потрібно його обробити:
- Надіслати POST /orders/{order}/accept з тілом {"timeMadeIn": 25}.
- Коли кухня завершить, надіслати POST /orders/{order}/preparation-finished.
Приклад 2: Доставка — Повний цикл
Додаток кур'єра керує доставкою:
- Кур'єр забирає: POST /orders/{order}/accept-delivery.
- Кур'єр доставляє: POST /orders/{order}/delivery-finished.
- Замовлення завершено: POST /orders/{order}/finish.
Приклад 3: Компанія відхиляє замовлення
Компанія не може виконати замовлення:
- Надіслати POST /orders/{order}/decline-by-company з тілом {"declinedReasonType": 1}.
7. FAQ
Q: Де взяти App-Auth-Token?
A: Зверніться до адміністратора платформи для отримання токена.
Q: Чи можна використовувати один токен для кількох інтеграцій?
A: Так, але рекомендується використовувати окремий токен для кожної інтеграції.
Q: Чи закінчуються токени?
A: Ні, за замовчуванням токени не мають терміну дії. Адміністратор може деактивувати їх вручну.
Q: Що станеться при невалідному переході статусу?
A: Запит поверне помилку. Використовуйте GET /orders/{order}/ для перевірки поточного статусу.
Q: Що таке токен замовлення в URL?
A: Це унікальний рядковий ідентифікатор замовлення, не числовий ID.
Q: Чи можна створювати замовлення через цей API?
A: Ні. Цей API лише керує статусами існуючих замовлень.
Оновлено: 28/03/2026
Дякуємо!