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. Потік статусів замовлення

Типовий успішний потік:

1.      accept — Компанія приймає замовлення та встановлює час приготування.
2.      accept-delivery — Кур'єр приймає доставку.
3.      preparation-finished — Компанія завершує приготування.
4.      delivery-finished — Кур'єр доставляє замовлення.
5.      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-система отримує нове замовлення і потрібно його обробити: 6.      Надіслати POST /orders/{order}/accept з тілом {"timeMadeIn": 25}. 7.      Коли кухня завершить, надіслати POST /orders/{order}/preparation-finished.

Приклад 2: Доставка — Повний цикл

Додаток кур'єра керує доставкою: 8.      Кур'єр забирає: POST /orders/{order}/accept-delivery. 9.      Кур'єр доставляє: POST /orders/{order}/delivery-finished. 10. Замовлення завершено: POST /orders/{order}/finish.

Приклад 3: Компанія відхиляє замовлення

Компанія не може виконати замовлення: 11. Надіслати POST /orders/{order}/decline-by-company з тілом {"declinedReasonType": 1}. | Корисно! Використовуйте GET /orders/{order}/ для перевірки поточного статусу перед спробою переходу.

7. FAQ

Q: Де взяти App-Auth-Token? A: Зверніться до адміністратора платформи для отримання токена.

Q: Чи можна використовувати один токен для кількох інтеграцій? A: Так, але рекомендується використовувати окремий токен для кожної інтеграції.

Q: Чи закінчуються токени? A: Ні, за замовчуванням токени не мають терміну дії. Адміністратор може деактивувати їх вручну.

Q: Що станеться при невалідному переході статусу? A: Запит поверне помилку. Використовуйте GET /orders/{order}/ для перевірки поточного статусу.

Q: Що таке токен замовлення в URL? A: Це унікальний рядковий ідентифікатор замовлення, не числовий ID.

Q: Чи можна створювати замовлення через цей API? A: Ні. Цей API лише керує статусами існуючих замовлень.