Замовлення

Замовлення об'єднує одну або кілька позицій (моделей із параметрами друку), дані клієнта та, опціонально, дані доставки. Створення замовлення розраховує вартість кожної позиції тим самим механізмом, що й POST /quotes, і зберігає замовлення в системі студії — воно з'явиться в панелі студії поруч із замовленнями, створеними іншими каналами (сторінка замовлення, віджет).

Об'єкт Order#

Поле	Тип	Опис
`id`	integer	Унікальний ідентифікатор замовлення
`customer`	Customer	Клієнт, що оформив замовлення
`status`	string	Статус замовлення — див. Статуси замовлення
`totalPrice`	Money	Загальна вартість замовлення
`items`	array	Позиції замовлення — див. Об'єкт OrderItem
`studioSlug`	string	Публічний ідентифікатор студії (використовується в URL сторінки замовлення)
`source`	string	Джерело створення замовлення, наприклад `"api"`
`delivery`	Delivery \| null	Дані доставки, якщо були передані
`createdAt`	string	Дата й час створення, ISO 8601
`updatedAt`	string	Дата й час останнього оновлення, ISO 8601

Статуси замовлення#

Статус	Значення
`pending`	Очікує підтвердження
`confirmed`	Підтверджено, прийнято в роботу
`printing`	Друкується
`post_processing`	Виконується постобробка
`ready`	Готове до відправки або самовивозу
`shipped`	Відправлено клієнту
`completed`	Клієнт отримав замовлення
`cancelled`	Скасовано

Об'єкт Customer#

Поле	Тип	Опис
`id`	integer	Ідентифікатор клієнта
`firstName`	string	Ім'я
`lastName`	string	Прізвище
`phoneNumber`	string	Номер телефону в міжнародному форматі
`email`	string	Email
`locale`	string	Мова клієнта
`totalOrders`	integer \| null	Кількість замовлень цього клієнта в студії
`totalSpent`	string \| null	Загальна сума витрат клієнта

Об'єкт OrderItem#

Поле	Тип	Опис
`id`	integer	Ідентифікатор позиції
`filePath`	string \| null	Внутрішній шлях до файлу моделі
`originalFileName`	string \| null	Оригінальна назва завантаженого файлу
`downloadUrl`	string \| null	Тимчасове підписане посилання для завантаження файлу
`quantity`	integer	Кількість копій
`price`	Money	Вартість позиції (за всю кількість)
`materialId`	integer \| null	Ідентифікатор використаного матеріалу
`finishingIds`	integer[]	Ідентифікатори застосованих послуг постобробки
`printingQualityId`	integer \| null	Ідентифікатор використаного профілю якості
`printingTime`	integer	Час друку в хвилинах
`weight`	string	Витрата матеріалу
`productId`	integer \| null	Якщо позиція створена з товару каталогу — його ідентифікатор
`productTitle`	string \| null	Назва товару, якщо застосовно
`costBreakdown`	CostBreakdown \| null	Повна деталізація розрахунку вартості позиції

Об'єкт Delivery#

Поле	Тип	Опис
`method`	string	Спосіб доставки
`cityName`, `cityRef`	string \| null	Місто доставки (назва та внутрішній довідник Нової Пошти)
`warehouseName`, `warehouseRef`	string \| null	Відділення (назва та довідник)
`streetName`, `streetRef`	string \| null	Вулиця, для кур'єрської доставки
`buildingNumber`, `apartmentNumber`	string \| null	Номер будинку та квартири
`npServiceType`	string \| null	Тип послуги Нової Пошти: `"WarehouseWarehouse"` або `"WarehouseDoors"`
`trackingNumber`	string \| null	Номер ТТН
`deliveryStatus`	string \| null	Статус доставки від перевізника
`scheduledDeliveryDate`, `actualDeliveryDate`	string \| null	Очікувана та фактична дата доставки

Створити замовлення#

POST /orders

Це запит типу multipart/form-data, а не JSON — для кожної позиції передається окремий файл моделі.

Параметри запиту

Поле	Тип	Обов'язкове	Опис
`models[]` (або `item_0`, `item_1`, ...)	file	так	По одному файлу моделі на позицію, у тому самому порядку, що й `items`
`items`	JSON-рядок	так	Масив позицій, див. нижче
`customerFirstName`	string	так	Ім'я клієнта — лише кириличні символи
`customerLastName`	string	так	Прізвище клієнта — лише кириличні символи
`customerPhoneNumber`	string	так	Номер телефону в міжнародному форматі, наприклад `+380671234567`
`customerEmail`	string	так	Email клієнта
`customerLocale`	string	ні	Мова клієнта
`deliveryMethodId`	integer	ні	Ідентифікатор способу доставки, налаштованого в студії
`deliveryCityName`, `deliveryCityRef`	string	ні	Місто доставки (Нова Пошта)
`deliveryWarehouseName`, `deliveryWarehouseRef`	string	ні	Відділення (Нова Пошта)
`deliveryNpServiceType`	string	ні	`"WarehouseWarehouse"` або `"WarehouseDoors"`
`deliveryStreetName`, `deliveryStreetRef`	string	ні	Вулиця — для кур'єрської доставки
`deliveryBuildingNumber`, `deliveryApartmentNumber`	string	ні	Номер будинку та квартири
`source`	string	ні	Довільна мітка джерела замовлення для вашої власної звітності

Кожен елемент масиву items — об'єкт:

Поле	Тип	Обов'язкове	Опис
`materialId`	integer	так	Ідентифікатор матеріалу з каталогу студії
`printingQualityId`	integer	так	Ідентифікатор профілю якості з каталогу студії
`finishingIds`	integer[]	ні	Ідентифікатори послуг постобробки
`quantity`	integer	ні	Кількість копій, за замовчуванням `1`

Валідація customerFirstName/customerLastName вимагає лише кириличних символів (regex /^[\p{Cyrillic}\s'-]+$/u) — так само, як і форма замовлення на сторінці студії. Латиниця в цих полях повертає 400.

Приклад запиту

curl https://placraftic.com/api/v1/orders \
  -H "Authorization: Bearer pk_live_..." \
  -F "models[][email protected]" \
  -F "models[][email protected]" \
  -F 'items=[{"materialId":2,"printingQualityId":1,"finishingIds":[7],"quantity":1},{"materialId":2,"printingQualityId":1,"finishingIds":[],"quantity":2}]' \
  -F "customerFirstName=Олена" \
  -F "customerLastName=Іванова" \
  -F "customerPhoneNumber=+380671234567" \
  -F "[email protected]" \
  -F "source=api"

Приклад відповіді

{
  "data": {
    "id": 48,
    "customer": {
      "id": 17,
      "firstName": "Олена",
      "lastName": "Іванова",
      "phoneNumber": "+380671234567",
      "email": "[email protected]",
      "locale": "uk",
      "totalOrders": 4,
      "totalSpent": "1245.00"
    },
    "status": "pending",
    "totalPrice": { "amount": "735.90", "currency": { "id": 5, "code": "UAH", "symbol": "₴" } },
    "items": [
      {
        "id": 36,
        "filePath": "orders/48/model-1.stl",
        "originalFileName": "model-1.stl",
        "downloadUrl": "https://.../orders/48/model-1.stl?X-Amz-Signature=...",
        "quantity": 1,
        "price": { "amount": "245.30", "currency": { "id": 5, "code": "UAH", "symbol": "₴" } },
        "materialId": 2,
        "finishingIds": [7],
        "printingQualityId": 1,
        "printingTime": 190,
        "weight": "100",
        "productId": null,
        "productTitle": null,
        "costBreakdown": null
      }
    ],
    "studioSlug": "my-studio",
    "source": "api",
    "delivery": null,
    "createdAt": "2026-07-11T17:20:00+00:00",
    "updatedAt": "2026-07-11T17:20:00+00:00"
  }
}

Асинхронна обробка#

Так само, як і в POST /quotes, якщо слайсинг хоча б однієї позиції не завершено миттєво, відповідь повертається як 202 Accepted з jobId для опитування. Після завершення слайсингу повторіть запит з тими самими файлами — результат уже буде в кеші.

Помилки

Код	Причина
`400`	Відсутні обов'язкові поля, кількість файлів не збігається з кількістю позицій, ім'я/прізвище містять символи поза кирилицею, невалідний формат телефону чи email
`404`	`materialId`, `printingQualityId` або `finishingIds` однієї з позицій не належить вашій студії

Отримати замовлення#

Повертає одне замовлення за ідентифікатором.

GET /orders/{id}

Параметри шляху

Параметр	Тип	Опис
`id`	integer	Ідентифікатор замовлення

Приклад запиту

curl https://placraftic.com/api/v1/orders/48 \
  -H "Authorization: Bearer pk_live_..."

Відповідь має ту саму структуру, що й у прикладі вище.

Помилки

Код	Причина
`404`	Замовлення з таким `id` не існує або належить іншій студії

Поки що недоступно#

Список замовлень — GET /orders без id не підтримується; наразі доступне лише отримання одного замовлення за ідентифікатором.
Вебхуки — сповіщення про створення замовлення чи зміну статусу заплановані на майбутній етап розвитку API.
Запис у каталог — створення, редагування та видалення матеріалів, профілів якості, послуг постобробки й товарів через API поки не підтримується; ці розділи каталогу доступні лише для читання.