Основные концепции
Эта страница знакомит с основополагающими идеями и паттернами, которые обеспечивают работу платформы. Понимание этих концепций поможет вам максимально эффективно использовать API и создавать надежные интеграции для рабочих процессов 3D-печати.
Базовый маршрут API
Для внешних вызовов API отправляйте запросы напрямую на https://api.quote3d.com/v2/... (например, GET https://api.quote3d.com/v2/user).
В вашем программном обеспечении установите https://api.quote3d.com в качестве хоста API/базового URL-адреса и вызывайте пути v2, такие как /v2/user, /v2/file и /v2/quotes.
1. Аутентификация и безопасность
Все конечные точки API требуют аутентификации с использованием вашего API-токена Quote3D. Для внешних вызовов используйте базовый маршрут https://api.quote3d.com/v2. Передавайте его либо как Authorization: Bearer <token>, либо как X-API-Token. Создавайте токены в панели управления Quote3D и храните их в секрете.
Напоминание: Храните ваши API токены в безопасности. Никогда не делитесь ими публично или не добавляйте их в систему контроля версий.
2. Управление аккаунтом
Управляйте своим аккаунтом, загрузками и статистикой использования через выделенные конечные точки:
GET /v2/userПолучить информацию о вашем аккаунтеGET /v2/user/uploadsСписок всех файлов, загруженных в ваш аккаунт. Отображаются от новых к старым.GET /v2/quotaПолучить текущие лимиты квоты и использование для расчетов и храненияGET /v2/usageПолучение подробной аналитики использования, включая статистику конечных точек, расход материалов и временные тенденции
3. Управление файлами
Загружайте, скачивайте и управляйте файлами ваших 3D-моделей (форматы STL, 3MF, OBJ):
- Получите временный upload_id для загрузки нового файла через публичный маршрут загрузки.:
GET /v2/file/upload-id- Получите временный upload_id для загрузки нового файла через публичный маршрут загрузки. - Этот маршрут НЕ требует аутентификации. Используйте его на стороне клиента для прямой загрузки файлов в наше хранилище.:
POST /v2/file/public/{upload_id}- Этот маршрут НЕ требует аутентификации. Используйте его на стороне клиента для прямой загрузки файлов в наше хранилище.Использование маршрута публичной загрузки позволяет избежать маршрутизации больших файлов через ваш сервер. Это предотвращает раскрытие вашего API-ключа и снижает нагрузку на сервер.
- Загрузите файл со стороны сервера (требуется аутентификация, используйте это, когда вы хотите загрузить файл из вашего бэкенда):
POST /v2/file— Загрузите файл со стороны сервера (требуется аутентификация, используйте это, когда вы хотите загрузить файл из вашего бэкенда) - Скачайте файл, используя его file_id:
GET /v2/file/{file_id}— Скачайте файл, используя его file_id - Удалите файл, который вам больше не нужен:
DELETE /v2/file/{file_id}— Удалите файл, который вам больше не нужен
4. Информация о детали и технический анализ
Проверьте, можно ли напечатать ваши модели, получите размеры детали и продвинутые технические метрики:
POST /v2/printability/{file_id}Мгновенный Анализ – Проверка размеров, объема, площади поверхности и геометрической целостности (открытые ребра/non-manifold) перед расчетом.
Quote3D выходит за рамки простых проверок размеров; он анализирует manifold-целостность модели и оценивает риск отслоения от стола, критичный для 3D-печати. Эти метрики предоставляются в ответах Printability и Quote.
5. Операции с расчетами стоимости
Генерируйте мгновенные расчеты стоимости для ваших 3D-печатей и управляйте историей расчетов:
- Запустите асинхронный расчет стоимости для 3D-модели. Возвращает ID задания; используйте endpoint jobs для получения завершенного результата.:
POST /v2/file/quote/{file_id}— Запустите асинхронный расчет стоимости для 3D-модели. Возвращает ID задания; используйте endpoint jobs для получения завершенного результата. - Альтернативный асинхронный endpoint для расчета стоимости. Возвращает ID задания, которое вы можете использовать для проверки статуса и получения завершенного результата.:
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}— Удалите расчет стоимости из вашей истории
Асинхронный рабочий процесс: POST /v2/file/quote/{file_id} возвращает ID задания. Используйте GET /v2/jobs/{job_id} для получения краткого результата, и GET /v2/quotes/{quote_id} для получения подробных данных расчета, когда они будут доступны.
Параметры запроса расчета стоимости
При генерации расчета стоимости вы можете предоставить пользовательскую конфигурацию в теле запроса. Любые параметры, которые вы не укажете, будут автоматически взяты из настроек Slice Profile в вашей Панели управления. Это позволяет вам переопределять определенные настройки для каждого расчета стоимости, сохраняя при этом настройки по умолчанию для других.
Важно: Если вы не предоставите параметр в своем запросе, API будет использовать значение из вашего Slice Profile в Панели управления (Профиль принтера, Профиль материала или Глобальные настройки). Убедитесь, что вы настроили свои профили по умолчанию в Панели управления для получения согласованных расчетов стоимости. Вы также можете настроить все свои параметры в конкретном Профиле принтера в Панели управления и просто передать его 'printer_id' в вашем запросе, чтобы мгновенно применить эти настройки без их индивидуальной передачи.
Приоритет конфигурации: Значения, отправленные в запросе V2 API, переопределяют выбранные значения профиля пользователя; любые еще отсутствующие поля затем возвращаются к профилям по умолчанию для пользователя/глобальным настройкам.
Основные параметры
| Параметр | Тип | Описание |
|---|---|---|
| printer_id | string | Необязательно. ID конкретного принтера для использования вместо принтера по умолчанию. |
| quantity | number | Необязательно. Общее количество копий для производства (По умолчанию: 1). |
Логика количества и пакетного производства
Наша система использует продвинутый алгоритм упаковки, основанный на указанном значении 'quantity':
- Технология FDM: Детали размещаются рядом друг с другом на платформе сборки (по осям X и Y) по мере доступности места.
- Технология SLA: Детали располагаются рядом друг с другом в ванне со смолой (по осям X и Y).
- Технология SLS: Детали могут быть уложены по всем осям (X, Y и Z) для полного использования объема порошкового слоя.
Благодаря этой оптимизированной упаковке, если несколько деталей помещаются в одну партию, фиксированные накладные расходы, такие как предварительный нагрев, охлаждение и смена слоев, применяются только к каждой необходимой партии. Это обеспечивает реалистичные и экономически эффективные цены для больших заказов.
printer_config
Параметры конфигурации принтера. Все поля необязательны и будут использовать значения по умолчанию из вашего Профиля принтера, если они не указаны.
| Параметр | Тип | Описание |
|---|---|---|
| bed_size_x | number | Build volume X dimension (mm) |
| bed_size_y | number | Build volume Y dimension (mm) |
| bed_size_z | number | Build volume Z dimension (mm) |
| nozzle_diameter | number | Nozzle diameter (mm) |
| nozzle_count | number | Number of nozzles |
| print_speed | number | Default print speed (mm/s) |
| max_print_speed | number | Maximum print speed (mm/s) |
| travel_speed | number | Travel speed (mm/s) |
| first_layer_speed | number | First layer speed (mm/s) |
| layer_height | number | Layer height (mm) |
| min_layer_height | number | Minimum layer height (mm) |
| max_layer_height | number | Maximum layer height (mm) |
| perimeters | number | Number of perimeters/walls |
| top_solid_layers | number | Top solid layers count |
| bottom_solid_layers | number | Bottom solid layers count |
| min_wall_count | number | Minimum wall count |
| max_wall_count | number | Maximum wall count |
| fill_density | number | Infill density (0-100%) |
| infill_pattern | string | Infill pattern. Options: rectilinear, alignedrectilinear, zigzag, crosszag, lockedzag, line, grid, triangles, trihexagon, cubic, adaptivecubic, supportcubic, honeycomb, honeycomb3d, lateralhoneycomb, gyroid, monotonic, monotonicline, lightning. Default: rectilinear |
| support_material | boolean | Enable support material |
| support_overhang_angle | number | Support overhang angle (degrees) |
| support_density | number | Support density (0-100%) |
| acceleration_print | number | Print acceleration (mm/s²) |
| acceleration_travel | number | Travel acceleration (mm/s²) |
| acceleration_retraction | number | Retraction acceleration (mm/s²) |
| jerk_print | number | Print jerk (mm/s) |
| jerk_travel | number | Travel jerk (mm/s) |
| jerk_retraction | number | Retraction jerk (mm/s) |
| min_hotend_temp | number | Minimum hotend temperature (°C) |
| max_hotend_temp | number | Maximum hotend temperature (°C) |
| min_bed_temp | number | Minimum bed temperature (°C) |
| max_bed_temp | number | Maximum bed temperature (°C) |
| hourly_cost | number | Machine hourly cost |
| СПЕЦИФИЧНО ДЛЯ SLA | ||
| sla_exposure_time | number | SLA: Время экспозиции слоя (секунды) |
| sla_bottom_exposure_time | number | SLA: Базовое время экспозиции (секунды) |
| sla_bottom_layer_count | number | SLA: Количество нижних слоев |
| sla_lift_distance | number | SLA: Расстояние подъема (мм) |
| sla_lift_speed | number | SLA: Скорость подъема (мм/с) |
| sla_retract_speed | number | SLA: Скорость отвода (мм/с) |
| sla_cleaning_cost | number | SLA: Фиксированная стоимость очистки за печать (IPA, расходные материалы) |
| СПЕЦИФИЧНО ДЛЯ SLS | ||
| sls_laser_speed | number | SLS: Скорость лазера (мм/с) |
| sls_hatch_spacing | number | SLS: Шаг штриховки (мм) |
| sls_layer_thickness | number | SLS: Толщина слоя (мм) |
| sls_layer_recoat_time | number | SLS: Время переукладки слоя (секунды) |
| sls_preheat_time | number | SLS: Время предварительного нагрева (секунды) |
| sls_cooling_time | number | SLS: Время охлаждения (секунды) |
| sla_light_off_delay | number | SLA: Light-off delay for each layer (seconds). |
| sla_transition_layer_count | number | SLA: Number of transition layers. |
| sla_drain_holes | array | SLA: Drainage holes configuration to prevent suction cups. |
| sls_bb_multiplier | number | SLS Bounding Box cost multiplier. |
| max_volumetric_flow | number | Maximum volumetric flow rate in mm³/s. |
material_config
Параметры конфигурации материала. Все поля необязательны и будут использовать значения по умолчанию из вашего Профиля материала, если они не указаны.
Интеграция с профилем материала: параметр filament_type должен соответствовать названию материала из вашего Профиля материала в Панели управления. При указании filament_type (например, "PLA", "ABS", "PETG"), API автоматически загружает все свойства из этого Профиля материала, включая плотность, температуры, настройки утяжки и цены.
Точность ценообразования: Для точных расчетов стоимости убедитесь, что вы установили как price_per_kg, так и price_per_gram в вашем Профиле материала. API использует эти значения для расчета стоимости материала на основе фактического веса нити, используемого в печати. Если эти значения не установлены в вашем профиле, вы можете переопределить их в запросе API.
Пример: Если у вас есть профиль материала "PLA" в вашей Панели управления с price_per_kg: 20.0 и price_per_gram: 0.02, вы можете просто отправить {"filament_type": "PLA"} в своем запросе, и вся цена будет рассчитана автоматически.
| Параметр | Тип | Описание |
|---|---|---|
| filament_type | string | Filament type (PLA, ABS, PETG, etc.) |
| color | string | Необязательно: Название цвета (например, 'Белый', 'Черный', '#FFFFFF'). Примечание: Для технологий SLA/SLS цвет применяется только если 'post_processing' установлен в 'painted'. |
| density | number | Material density (g/cm³) |
| diameter | number | Filament diameter (mm) |
| powder_bulk_density | number | SLS: Bulk density of loose powder in g/cm³. Used for reusable powder and refresh calculations. |
| temperature | number | Print temperature (°C) |
| print_temp_min | number | Minimum print temperature (°C) |
| print_temp_max | number | Maximum print temperature (°C) |
| bed_temperature | number | Bed temperature (°C) |
| bed_temp_min | number | Minimum bed temperature (°C) |
| bed_temp_max | number | Maximum bed temperature (°C) |
| fan_speed | number | Fan speed (0-100%) |
| min_fan_speed | number | Minimum fan speed (0-100%) |
| retraction_distance | number | Retraction distance (mm) |
| retraction_speed | number | Retraction speed (mm/s) |
| price_per_kg | number | Price per kilogram |
| price_per_gram | number | Price per gram |
| support_cost_multiplier | number | Support material cost multiplier |
| sls_refresh_factor | number | SLS Powder Refresh cost factor (e.g. 1.2). |
| max_volumetric_flow | number | Material specific volumetric flow limit in mm³/s. |
| min_layer_time | number | Minimum layer time in seconds for cooling. |
quote_config
Параметры конфигурации ценообразования. Все поля необязательны и будут использовать значения по умолчанию из ваших Глобальных настроек, если они не указаны. Валюта по умолчанию соответствует настройкам вашего личного кабинета (например, 'USD', 'TRY', 'EUR').
| Параметр | Тип | Описание |
|---|---|---|
| currency | string | Currency code (USD, TRY, EUR, GBP, JPY, CNY, RUB). Defaults to your dashboard preference. |
| tax_rate | number | Tax rate percentage (0-100) |
| fixed_fee | number | Fixed fee per quote |
| energy_cost_per_kwh | number | Energy cost per kWh |
| hollowing | string | Специфично для SLA/смол: 'solid', '2 мм' или '3 мм' (По умолчанию: 'solid') |
| post_processing | string | Специфично для SLA/SLS: 'standard', 'sanding', 'painting' или 'painted' (По умолчанию: 'standard') |
| enable_batch_system | boolean | Enable/disable batch calculation system (default: true) |
| material_wastage_factor | number | Factor for calculating material wastage (e.g. 1.10 for 10% wastage). |
Совет: Коммерческие предложения автоматически сохраняются в вашей учетной записи. Вы можете получить к ним доступ в любое время через конечные точки истории коммерческих предложений.
6. Профили принтера и калькуляции стоимости
Настройте параметры принтера и цены, чтобы получать точные калькуляции стоимости. Вы можете управлять своими профилями по умолчанию в разделе 'Профили слайсера' в Панели управления, которые будут использоваться автоматически, когда вы не указываете параметры в API-запросах.
Типы профилей
- Профиль принтера - Настройте параметры вашего принтера (размер платформы, диаметр сопла, скорость печати, высота слоя, ускорение, рывок, температуры и т.д.), чтобы они соответствовали вашему фактическому принтеру. Установите этот профиль как профиль по умолчанию в Панели управления, и он будет использоваться для всех запросов калькуляции стоимости, если вы не переопределите конкретные параметры.
- Профиль материала - Установите свойства материала (тип нити, плотность, диаметр, температуры, скорость вентилятора, настройки убирания нити, цены) для каждого используемого вами материала. API автоматически будет использовать профиль материала, соответствующий типу нити (filament_type), который вы указываете в запросе.
- Глобальные настройки - Настройте глобальные параметры калькуляции стоимости, такие как ставка налога, фиксированные сборы, стоимость электроэнергии и валюта по умолчанию. Эти настройки применяются ко всем калькуляциям стоимости, если они не переопределены в запросе.
Рекомендации: Настройте свои профили по умолчанию в разделе 'Профили слайсера' в Панели управления. Таким образом, вы можете делать простые запросы калькуляции стоимости, не указывая все параметры, и API автоматически будет использовать ваши настроенные значения по умолчанию. Вы по-прежнему можете переопределить любой параметр для каждого запроса при необходимости.
Как работает объединение профилей
Когда вы делаете запрос калькуляции стоимости, API объединяет параметры вашего запроса с вашими профилями из Панели управления, используя следующий приоритет:
- Параметры запроса - Значения, которые вы явно указываете в API-запросе, имеют наивысший приоритет
- Профиль пользователя - Если у вас есть профиль, специфичный для пользователя, установленный как профиль по умолчанию, он используется следующим
- Глобальный профиль - Если профиль пользователя не существует, система переходит к глобальным настройкам по умолчанию
Это означает, что вы можете переопределить только те параметры, которые вам нужны (например, только height_layer или fill_density), сохраняя при этом все остальные настройки из ваших профилей в Панели управления.
7. Веб-хуки
Получайте уведомления в реальном времени о событиях в вашей учетной записи:
POST /v2/webhooks- Создать новую конечную точку веб-хукаGET /v2/webhooks- Список всех ваших веб-хуковGET /v2/webhooks/{webhook_id}- Получить сведения о веб-хуке и статистику доставкиPUT /v2/webhooks/{webhook_id}- Обновить настройки веб-хукаDELETE /v2/webhooks/{webhook_id}- Удалить веб-хук
Поддерживаемые события: quote.completed, quote.failed, job.status_changed, widget.added_to_cart, file.uploaded. Веб-хуки включают подписи HMAC-SHA256 для проверки безопасности.
8. Аналитика и отчетность
Получите информацию об использовании вашего API и статистике расчетов стоимости:
GET /v2/analytics/quotes- Получите полную статистику расчетов стоимости, включая общее количество расчетов, средние цены и тенденции использования материаловGET /v2/analytics/popular- Просмотрите ваши самые популярные материалы и конфигурации принтеровGET /v2/analytics/cost-trends- Анализируйте тенденции изменения стоимости с течением времени (группировка по дням, неделям или месяцам)GET /v2/analytics/export- Экспортируйте ваши расчеты стоимости и данные об использовании в формате CSV или JSON
9. Ограничение скорости и квоты
Quote3D использует ограничение скорости для обеспечения справедливого использования и стабильности системы:
- Ограничения скорости применяются для каждого API токена и различаются в зависимости от конечной точки
- Информация об ограничении скорости содержится в заголовках ответа:
X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-Reset - При превышении лимита запросов вы получите ответ 429 Too Many Requests с заголовком Retry-After
- Ежемесячные квоты на расчеты и хранилище зависят от вашего тарифного плана
Рекомендации: Реализуйте экспоненциальную задержку при обработке ошибок ограничения скорости, чтобы избежать перегрузки API.
10. RESTful API с версиями
- Все конечные точки имеют версии (например, /v2/)
- Использует стандартные HTTP-методы:
- Соответствует стандартам OpenAPI 3.1.0 для схемы и документации
- Журнал изменений API доступен по адресу: