Основные понятия: файлы, расчёты и задания

1. Аутентификация и безопасность

Каждый эндпоинт требует аутентификации вашим API-токеном Quote3D, за одним исключением: публичный маршрут загрузки, описанный в разделе «Управление файлами». Для внешних вызовов используйте базовый маршрут https://api.quote3d.com/v2. Передавайте токен либо как Authorization: Bearer YOUR_TOKEN, либо как X-API-Token. Создавайте токены в панели Quote3D и храните их в секрете.

Токены могут иметь область действия. Токен с полным доступом достигает всех эндпоинтов, а токен с областью виджета ограничен теми, что нужны встроенному виджету. Любой вызов вне области токена возвращает 403. Область токена можно посмотреть и изменить на странице «Токены» в панели.

2. Управление аккаунтом

Управляйте своим аккаунтом, загрузками и статистикой использования через выделенные конечные точки:

• GET /v2/user Возвращает данные аккаунта, тариф и месячные лимиты — здесь находятся quotes_used, quotes_limit, storage_used, storage_limit и reset_date
• GET /v2/user/uploads Список всех файлов, загруженных в ваш аккаунт. Отображаются от новых к старым.
• GET /v2/quota Возвращает ваши лимиты частоты запросов — общий лимит плюс разбивку по эндпоинтам с остатком вызовов и временем сброса — вместе с числом запросов за сегодня, месяц, год и всё время
• GET /v2/usage Получение подробной аналитики использования, включая статистику конечных точек, расход материалов и временные тенденции
• GET /v2/config Включённые технологии аккаунта, принтеры, материалы с цветами (в наличии или нет) и ценовые значения по умолчанию — всё, что предлагает виджет. Токены виджета тоже могут это читать.

3. Управление файлами

Загружайте, скачивайте и управляйте файлами ваших 3D-моделей (форматы STL, 3MF, OBJ, STEP):

• GET /v2/file/upload-id — Получите временный upload_id для загрузки нового файла через публичный маршрут загрузки.
• POST /v2/file/public/{upload_id} — Этот маршрут НЕ требует аутентификации. Используйте его на стороне клиента для прямой загрузки файлов в наше хранилище.

  Использование маршрута публичной загрузки позволяет избежать маршрутизации больших файлов через ваш сервер. Это предотвращает раскрытие вашего API-ключа и снижает нагрузку на сервер.

• POST /v2/file — Загрузите файл со стороны сервера (требуется аутентификация, используйте это, когда вы хотите загрузить файл из вашего бэкенда)
• GET /v2/file/{file_id} — Скачайте файл, используя его file_id
• DELETE /v2/file/{file_id} — Удалите файл, который вам больше не нужен

Загрузка отклоняется, если файл не является корректной моделью STL, 3MF, OBJ или STEP либо превышает лимит размера платформы (по умолчанию 50 МБ). Файлы STEP (.step/.stp) триангулируются на сервере с теми же настройками, что и в OrcaSlicer (линейное отклонение 0,003 мм, угловое отклонение 0,5 рад); все тела сборки объединяются, а длины переводятся в миллиметры. Оба маршрута загрузки применяют одинаковые проверки.

Как хранятся ваши файлы

Загруженные модели хранятся в зашифрованном виде и не доступны публично — не существует ссылки, позволяющей получить доступ к файлу напрямую. Поле file_path в ответах является путем для аутентифицированной загрузки (GET /v2/file/{file_id}), а не путем на диске, поэтому рассматривайте его как эндпоинт, а не как URL-адрес, которым можно поделиться. Удаление файла удаляет его из хранилища, а не только из ваших списков.

4. Информация о детали и технический анализ

Проверьте, можно ли напечатать ваши модели, получите размеры детали и продвинутые технические метрики:

• POST /v2/printability/{file_id} Мгновенный Анализ – Проверка размеров, объема, площади поверхности и геометрической целостности (открытые ребра/non-manifold) перед расчетом.

Quote3D выходит за рамки простых проверок размеров; он анализирует manifold-целостность модели и оценивает риск отслоения от стола, критичный для 3D-печати. Эти метрики предоставляются в ответах Printability и Quote.

5. Операции с расчетами стоимости

Генерируйте мгновенные расчеты стоимости для ваших 3D-печатей и управляйте историей расчетов:

• POST /v2/file/quote/{file_id} — Запустите асинхронный расчет стоимости для 3D-модели. Возвращает ID задания; используйте endpoint jobs для получения завершенного результата.
• POST /v2/file/quote/{file_id}/async — Альтернативный асинхронный endpoint для расчета стоимости. Возвращает ID задания, которое вы можете использовать для проверки статуса и получения завершенного результата.
• GET /v2/jobs/{job_id} — Проверьте статус асинхронного задания расчета стоимости. Возвращает процент выполнения и статус завершения.
• GET /v2/quotes — Получите всю вашу историю расчетов стоимости с поддержкой постраничной навигации
• GET /v2/quotes/{quote_id} — Получите подробную информацию о конкретном расчете стоимости
• DELETE /v2/quotes/{quote_id} — Удалите расчет стоимости из вашей истории

Параметры запроса расчета стоимости

При генерации расчета стоимости вы можете предоставить пользовательскую конфигурацию в теле запроса. Любые параметры, которые вы не укажете, будут автоматически взяты из настроек Slice Profile в вашей Панели управления. Это позволяет вам переопределять определенные настройки для каждого расчета стоимости, сохраняя при этом настройки по умолчанию для других.

Таблицы ниже охватывают параметры, которые интеграции переопределяют чаще всего. Это не полный список — движок принимает намного больше полей принтера, материала и ценообразования, и каждое из них можно задать один раз в профилях слайсинга в панели вместо отправки при каждом запросе. Настройте профили там и отправляйте только то, что меняется от расчёта к расчёту; полный список полей есть в схеме OpenAPI.

Request Validation

Числовые поля в printer_config, material_config и quote_config проверяются на допустимые границы до постановки задания в очередь. Значение вне диапазона, не конечное число (NaN, Infinity), неверный тип или отрицательное число там, где имеют смысл только ноль и выше, отклоняется с кодом HTTP 400 и ошибкой VALIDATION_ERROR, указывающей конкретное поле. Ноль по-прежнему принимается везде, где он осмыслен: скорость или ускорение 0 для отдельной роли означает «использовать значение принтера по умолчанию» — то же соглашение, что и в OrcaSlicer.

• Температурные пределы: температуры материала (temperature и bed_temperature, переданные в запросе или считанные из профиля материала) проверяются по значениям принтера min_hotend_temp / max_hotend_temp и min_bed_temp / max_bed_temp. Материал, которому требуется больше тепла, чем может дать выбранный принтер, отклоняется, а не рассчитывается. Только для FDM: у технологий на основе смолы и порошка нет ни сопла, ни подогреваемого стола. Оставьте пределы принтера незаполненными, чтобы пропустить проверку.
• Включенные технологии: если вы ограничили технологии в глобальных настройках, запрос расчета стоимости для отключенной технологии отклоняется. Оставьте настройку пустой, чтобы принимать все технологии.
• Поля цены материала: price_per_gram — это значение, по которому считает движок. При сохранении профиля материала price_per_kg автоматически пересчитывается из него (а price_per_gram выводится из price_per_kg, если указана только цена за килограмм), поэтому эти два значения никогда не расходятся.

Основные параметры

Логика количества и пакетного производства

Наша система использует продвинутый алгоритм упаковки, основанный на указанном значении 'quantity':

• Технология FDM: Детали размещаются рядом друг с другом на платформе сборки (по осям X и Y) по мере доступности места.
• Технология SLA: Детали располагаются рядом друг с другом в ванне со смолой (по осям X и Y).
• Технология SLS: Детали могут быть уложены по всем осям (X, Y и Z) для полного использования объема порошкового слоя.

printer_config

Параметры конфигурации принтера. Все поля необязательны и будут использовать значения по умолчанию из вашего Профиля принтера, если они не указаны.

material_config

Параметры конфигурации материала. Все поля необязательны и будут использовать значения по умолчанию из вашего Профиля материала, если они не указаны.

quote_config

Параметры конфигурации ценообразования. Все поля необязательны и будут использовать значения по умолчанию из ваших Глобальных настроек, если они не указаны. Валюта по умолчанию соответствует настройкам вашего личного кабинета (например, 'USD', 'TRY', 'EUR').

6. Профили принтера и калькуляции стоимости

Настройте параметры принтера и цены, чтобы получать точные калькуляции стоимости. Вы можете управлять своими профилями по умолчанию в разделе 'Профили слайсера' в Панели управления, которые будут использоваться автоматически, когда вы не указываете параметры в API-запросах.

Типы профилей

• Профиль принтера - Настройте параметры вашего принтера (размер платформы, диаметр сопла, скорость печати, высота слоя, ускорение, рывок, температуры и т.д.), чтобы они соответствовали вашему фактическому принтеру. Установите этот профиль как профиль по умолчанию в Панели управления, и он будет использоваться для всех запросов калькуляции стоимости, если вы не переопределите конкретные параметры.
• Профиль материала - Установите свойства материала (тип нити, плотность, диаметр, температуры, скорость вентилятора, настройки убирания нити, цены) для каждого используемого вами материала. API автоматически будет использовать профиль материала, соответствующий типу нити (filament_type), который вы указываете в запросе.
• Глобальные настройки - Настройте глобальные параметры калькуляции стоимости, такие как ставка налога, фиксированные сборы, стоимость электроэнергии и валюта по умолчанию. Эти настройки применяются ко всем калькуляциям стоимости, если они не переопределены в запросе.

Как работает объединение профилей

Когда вы делаете запрос калькуляции стоимости, API объединяет параметры вашего запроса с вашими профилями из Панели управления, используя следующий приоритет:

1. Параметры запроса - Значения, которые вы явно указываете в API-запросе, имеют наивысший приоритет
2. Профиль пользователя - Если у вас есть профиль, специфичный для пользователя, установленный как профиль по умолчанию, он используется следующим
3. Глобальный профиль - Если профиль пользователя не существует, система переходит к глобальным настройкам по умолчанию

Это означает, что вы можете переопределить только те параметры, которые вам нужны (например, только layer_height или fill_density), сохраняя при этом все остальные настройки из ваших профилей в Панели управления.

7. Веб-хуки

Получайте уведомления в реальном времени о событиях в вашей учетной записи:

• POST /v2/webhooks - Создать новую конечную точку веб-хука
• GET /v2/webhooks - Список всех ваших веб-хуков
• GET /v2/webhooks/{webhook_id} - Получить сведения о веб-хуке и статистику доставки
• PUT /v2/webhooks/{webhook_id} - Обновить настройки веб-хука
• DELETE /v2/webhooks/{webhook_id} - Удалить веб-хук
• POST /v2/webhooks/{webhook_id}/deliveries/{delivery_id}/resend - Повторно отправить прошлую доставку, например после исправления вашего эндпоинта

Поддерживаемые события: quote.completed, quote.failed, file.uploaded, file.deleted, job.status_changed, widget.added_to_cart, usage.alert. Веб-хуки включают подписи HMAC-SHA256 для проверки безопасности.

Справочник по вебхукам: структура полезной нагрузки, проверка подписи, повторы и повторная доставка

8. Аналитика и отчетность

Получите информацию об использовании вашего API и статистике расчетов стоимости:

• GET /v2/analytics/quotes - Получите полную статистику расчетов стоимости, включая общее количество расчетов, средние цены и тенденции использования материалов
• GET /v2/analytics/popular - Просмотрите ваши самые популярные материалы и конфигурации принтеров
• GET /v2/analytics/cost-trends - Анализируйте тенденции изменения стоимости с течением времени (группировка по дням, неделям или месяцам)
• GET /v2/analytics/export - Экспортируйте ваши расчеты стоимости и данные об использовании в формате CSV или JSON

9. Каталог и запас

Управляйте собственными принтерами, материалами, цветами, запасом по цветам, ценами и технологиями аккаунта с серверным токеном. Виджет читает тот же каталог, поэтому изменение сразу попадает в форму расчёта. Токены виджета отклоняются, а эти вызовы не расходуют месячную квоту запросов:

• GET /v2/store/catalog - Всё, что предлагает аккаунт, с готовностью по технологиям и заканчивающимися цветами
• GET /v2/store/catalog/schema - Формы принтера, материала и цен из панели с границами, единицами и справочными текстами на запрошенном языке
• POST /v2/store/catalog/adopt - Скопировать глобальные принтеры и материалы в аккаунт с выбранными цветами, ценой и начальным запасом
• POST /v2/store/catalog/materials - Создать материал, при желании на основе глобального
• GET · PATCH · DELETE /v2/store/catalog/materials/{id} - Прочитать, изменить или удалить материал вместе с настройками запаса
• PUT /v2/store/catalog/materials/{id}/colors - Заменить список цветов материала; запас существующих цветов сохраняется
• GET · PATCH · DELETE /v2/store/catalog/printers/{id} - Прочитать, изменить или удалить принтер
• GET · PATCH · DELETE /v2/store/catalog/pricing - Прочитать, изменить или сбросить цены; смена валюты меняет валюту аккаунта без пересчёта сумм
• GET · PUT /v2/store/catalog/technologies - Какие технологии разрешает тариф и какие включены
• GET · POST /v2/store/stock/movements - Записать поступление, инвентаризацию или списание и получить историю запаса
• POST /v2/store/stock/orders - Списать, вернуть или проверить материал оплаченного заказа, не более одного раза на расчёт

Тело PATCH содержит values и updated_at. values использует те же имена полей в snake_case, что и список каталога (имя, которого нет в форме, отклоняется с 400); если профиль изменился после вашего чтения, вызов вернёт 409 с error_key stale.

10. Ограничение скорости и квоты

Quote3D использует ограничение скорости для обеспечения справедливого использования и стабильности системы:

• Ограничения скорости применяются для каждого API токена и различаются в зависимости от конечной точки
• Информация об ограничении скорости содержится в заголовках ответа: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-Window
• При превышении лимита запросов вы получите ответ 429 Too Many Requests с заголовком Retry-After
• Тариф задаёт лимит расчётов, который сбрасывается каждый расчётный период, и лимит хранилища, который не сбрасывается: место освобождается только при удалении файлов
• Лимиты настраиваются для каждой установки, поэтому читайте текущие значения, а не задавайте их в коде. Их сообщают и заголовки ответа выше, и этот эндпоинт: GET /v2/quota

11. Ответы и ошибки

Успешные ответы бывают двух видов. Вызовы расчёта, задачи, деталей сохранённого расчёта, веб-хуков, аналитики, использования, квоты и конфигурации оборачивают данные в success: true с результатом в data. Вызовы файлов, идентификатора загрузки, пользователя, загрузок, списка расчётов, проверки печатаемости и раздела «Каталог и запас» возвращают поля на верхнем уровне. Точная схема каждого вызова — в справочнике API. Скачивание файлов и экспорт CSV возвращают содержимое файла как есть.

{
  "success": true,
  "data": { "...": "endpoint-specific payload" }
}

Постраничный вывод и сортировка

Списочные эндпоинты, такие как /v2/quotes и /v2/user/uploads, разбиваются на страницы параметрами limit и offset (по умолчанию 50 результатов, максимум 100). Вместе с результатами возвращается объект pagination с полями total, limit, offset, has_more, page и total_pages, поэтому используйте has_more вместо самостоятельного вычисления конца списка. Сортировка задаётся одним повторяемым параметром вида field:direction, например ?sort=created_at:desc&sort=total_price:asc; загрузки по умолчанию идут от новых к старым.

Ответы с ошибкой

Все ошибки имеют одну форму: список detail с именем параметра или поля (loc, msg, code), error_code вида AUTH_001, error_summary и, где полезно, recovery_suggestions и documentation_url. Ветвитесь по HTTP-статусу и error_code, а не по тексту, который может меняться.

С асинхронными расчётами иначе: постановка задания в очередь завершается кодом 202, а неудавшийся впоследствии расчёт проявляется как статус failed с сообщением об ошибке на эндпоинте задания, а не как ошибка HTTP. Всегда проверяйте статус задания, а не только код, полученный при запуске.

12. RESTful API с версионированием

• Все конечные точки имеют версии (например, /v2/)
• Использует стандартные HTTP-методы: GET, POST, PUT, DELETE
• Описан схемой OpenAPI 3.0.3, которую можно импортировать в свои инструменты
• Несовместимые изменения и дополнения фиксируются в журнале изменений API