Огляд

Placraftic REST API дозволяє студії 3D-друку інтегрувати свій каталог матеріалів, профілі якості друку, розрахунок вартості та замовлення із зовнішніми системами — власним сайтом, ERP, автоматизованими сценаріями чи будь-яким іншим сервісом, здатним виконувати HTTP-запити.

API побудоване на REST-принципах: передбачувані URL, стандартні HTTP-методи та коди відповіді, JSON для тіла відповіді. Кожен ключ належить конкретній студії — авторизований запит завжди працює в межах даних саме цієї студії.

Початок роботи#

1. Увійдіть у панель студії та відкрийте розділ Ключі API (доступно лише власнику студії, за умови що тариф студії включає доступ до API).
2. Натисніть «Створити ключ», дайте йому назву (наприклад, «Продакшн-інтеграція») і збережіть секрет — він показується рівно один раз.
3. Використовуйте секрет як bearer-токен у заголовку Authorization для кожного запиту до https://placraftic.com/api/v1.

Автентифікація#

Кожен запит до API повинен містити заголовок Authorization з ключем у форматі bearer-токена:

Authorization: Bearer pk_live_f4be019aadb13fb8e617950e36d351d67bc8e5312a7ebd022479cd0de95db21

Ключі мають префікс pk_live_, за яким слідує 64-символьний випадковий рядок. Секрет генерується один раз, під час створення ключа, і зберігається на сервері лише у вигляді хешу — переглянути його повторно неможливо. Якщо секрет втрачено, відкличте ключ у панелі студії та створіть новий.

Запит без заголовка Authorization, з невалідним ключем або з відкликаним ключем повертає 401 Unauthorized.

Базова адреса#

Усі запити виконуються відносно:

https://placraftic.com/api/v1

Формат запитів#

Ендпоінти, що приймають лише текстові поля (жодного зараз немає серед GET-запитів), очікують application/json. Ендпоінти, що приймають файл моделі (POST /quotes, POST /orders), очікують multipart/form-data — це стандартна вимога HTML-форм для завантаження файлів, і саме її використовує власна форма замовлення студії.

Формат відповіді#

Усі відповіді — JSON-об'єкт з таким конвертом:

{
  "data": { },
  "metadata": null,
  "errors": null,
  "errorCode": null
}

Пагінація#

Жоден ендпоінт списку (GET /materials, GET /printing-qualities, GET /finishings, GET /products) наразі не підтримує пагінацію — повертається повний список ресурсів студії за один запит. Каталоги студій зазвичай налічують від кількох до кількох десятків позицій, тому це не є практичним обмеженням, але майте на увазі: параметри на кшталt page/limit ігноруються.

Помилки#

Помилка повертається у вигляді HTTP-статусу, відмінного від 2xx, з тілом:

{ "data": null, "errorCode": "..." }

Для помилок валідації (400) додатково заповнюється поле errors — об'єкт, де ключ це назва поля, а значення — масив повідомлень:

{
  "data": null,
  "errors": { "materialId": ["This value should not be blank."] },
  "errorCode": "errors.validationFailed"
}

Ліміти запитів#

Ліміт рахується на студію, а не на IP-адресу — усі ключі, випущені для однієї студії, ділять один і той самий ліміт.

При перевищенні ліміту запит повертає 429 з тілом { "error": "API rate limit exceeded for this studio's plan" }. Заголовка Retry-After API поки не повертає — після 429 варто почекати кілька хвилин перед повторною спробою, а не орієнтуватись на точний час скидання лічильника.

Розділи довідника#