> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://dots.crisp.help/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 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. Потік статусів замовлення
Типовий успішний потік:
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 лише керує статусами існуючих замовлень.