核心概念
本页面介绍驱动该平台的基础理念和模式。理解这些概念将帮助您充分利用 API，并为 3D 打印工作流程构建强大的集成。
API 基础路由
对于外部 API 调用，请直接向 https://api.quote3d.com/v2/... 发送请求（例如：GET https://api.quote3d.com/v2/user）。
在您的软件中，将 https://api.quote3d.com 设置为 API 主机/基础 URL，并调用诸如 /v2/user、/v2/file 和 /v2/quotes 等 v2 路径。
1. 身份验证与安全
所有 API 端点都需要使用您的 Quote3D API 令牌进行身份验证。对于外部调用，请使用 https://api.quote3d.com/v2 基础路由。请以 Authorization: Bearer <token> 或 X-API-Token 的形式发送。请从您的 Quote3D 控制面板生成令牌并妥善保管。
提醒：请妥善保管您的 API token。切勿公开分享或提交到版本控制。
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}即时分析 – 在生成报价前，验证尺寸、体积、表面积和几何完整性（开口边缘/非流形）。
Quote3D 不仅仅进行简单的尺寸检查；它分析模型的流形（manifold）完整性并评估对 3D 打印至关重要的附着风险。这些指标在 Printability 和 Quote 响应中均有提供。
5. 报价操作
为您的 3D 打印生成即时报价并管理报价历史：
- 为 3D 模型启动异步报价计算。返回一个作业 ID；使用作业端点检索完成的结果。:
POST /v2/file/quote/{file_id}— 为 3D 模型启动异步报价计算。返回一个作业 ID；使用作业端点检索完成的结果。 - 替代的异步报价端点。返回一个作业 ID，您可以使用它来检查状态并获取完成的结果。:
POST /v2/file/quote/{file_id}/async— 替代的异步报价端点。返回一个作业 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} 获取可用的存储的详细报价数据。
报价请求参数
在生成报价时，您可以在请求体中提供自定义配置。您未指定的任何参数将自动从您的仪表板切片配置文件设置中获取。这允许您为每个报价覆盖特定设置，同时为其他设置保留默认值。
重要提示：如果您在请求中未提供参数，API 将使用您的仪表板切片配置文件（打印机配置文件、材料配置文件或全局设置）中的值。请确保在仪表板中设置您的默认配置文件，以获得一致的报价。您还可以配置仪表板上的特定打印机配置文件中的所有参数，并简单地在您的请求中传递其 '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'（实心）, '2mm' 或 '3mm' (默认: '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 请求中未指定参数时，系统将自动使用这些配置。
配置类型
- 打印机档案 - 配置您的打印机设置（打印床尺寸、喷嘴直径、打印速度、层高、加速度、抖动、温度等），以匹配您的实际打印机。在仪表盘中将其设置为您的默认档案，除非您覆盖特定参数，否则它将用于所有报价请求。
- 材料档案 - 为您使用的每种材料设置材料属性（灯丝类型、密度、直径、温度、风扇速度、回抽设置、定价）。当您在请求中指定 filament_type 时，API 将自动使用匹配的材料档案。
- 全局设置 - 配置全局报价设置，如税率、固定费用、能源成本和默认货币。这些设置适用于所有报价，除非在请求中被覆盖。
最佳实践：在仪表盘切片档案部分设置您的默认档案。这样，您可以在不指定所有参数的情况下提出简单的报价请求，API 将自动使用您配置的默认值。在需要时，您仍然可以按请求覆盖任何参数。
档案合并方式
当您提出报价请求时，API 会使用以下优先级将您的请求参数与仪表盘档案合并：
- 请求参数 - 您在 API 请求中明确提供的数值具有最高优先级
- 用户档案 - 如果您设置了用户特定的默认档案，则接下来使用它
- 全局配置 - 如果不存在用户配置，系统将回退到全局默认值。
这意味着您可以仅覆盖您需要的参数（例如，仅 layer_height 或 fill_density），同时保留来自仪表盘档案的所有其他设置。
7. Webhooks
当您的账户中发生事件时，接收实时通知：
POST /v2/webhooks- 创建新的Webhook端点GET /v2/webhooks- 列出您的所有 WebhooksGET /v2/webhooks/{webhook_id}- 获取 Webhook 详情和交付统计信息PUT /v2/webhooks/{webhook_id}- 更新Webhook设置DELETE /v2/webhooks/{webhook_id}- 删除Webhook
支持的事件： quote.completed, quote.failed, job.status_changed, widget.added_to_cart, file.uploaded. Webhooks包含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 变更日志请访问：