核心概念：文件、报价与任务

1. 身份验证与安全

每个端点都需要使用您的Quote3D API令牌进行身份验证，只有一个例外：文件管理中记录的公开上传路由。外部调用请使用 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 获取详细的使用分析，包括端点统计信息、材料使用情况和基于时间的趋势

3. 文件管理

上传、下载和管理您的3D模型文件（STL、3MF、OBJ格式）：

• 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模型，或超过平台文件大小上限（默认50 MB），上传将被拒绝。两个上传路由都会执行相同的检查。

文件存储方式

上传的模型以加密方式存储，且无法被公开访问——不存在可以直接提供已存储文件的链接。响应中的 file_path 字段是经过身份验证的下载路径 (GET /v2/file/{file_id})，而非磁盘上的位置，因此请将其视为端点而非可分享的 URL。删除文件不仅会将其从您的列表中移除，还会将其从存储中彻底删除。

4. 部件信息与技术分析

检查模型是否可打印，并获取部件尺寸及高级技术指标：

• POST /v2/printability/{file_id} 即时分析 – 在生成报价前，验证尺寸、体积、表面积和几何完整性（开口边缘/非流形）。

Quote3D 不仅仅进行简单的尺寸检查；它分析模型的流形（manifold）完整性并评估对 3D 打印至关重要的附着风险。这些指标在 Printability 和 Quote 响应中均有提供。

5. 报价操作

为您的 3D 打印生成即时报价并管理报价历史：

• POST /v2/file/quote/{file_id} — 为 3D 模型启动异步报价计算。返回一个作业 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} — 从您的历史记录中删除报价

报价请求参数

在生成报价时，您可以在请求体中提供自定义配置。您未指定的任何参数将自动从您的仪表板切片配置文件设置中获取。这允许您为每个报价覆盖特定设置，同时为其他设置保留默认值。

下表涵盖了集成方最常覆盖的参数，但并非完整清单——报价引擎还接受更多打印机、材料和定价字段，而且每一项都可以在控制台的切片配置文件中设置一次，无需在每次请求时发送。请在那里配置好配置文件，只发送每次报价中变化的部分；完整字段清单见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_kg 推导出 price_per_gram），因此两者绝不会互相矛盾。

根参数

数量和批量生产逻辑

我们的系统利用基于指定 'quantity' 的高级打包算法：

• FDM 技术：零件尽可能地并排放置在构建板上（X 轴和 Y 轴）。
• SLA 技术：零件并排放置在树脂槽中（X 轴和 Y 轴）。
• SLS 技术：零件可以堆叠在所有轴（X、Y 和 Z）上，以充分利用粉末床的容量。

printer_config

打印机配置参数。所有字段都是可选的，如果未提供，将使用您的默认打印机配置文件值。

material_config

材料配置参数。所有字段都是可选的，如果未提供，将使用您的默认材料配置文件值。

quote_config

报价定价配置参数。所有字段都是可选的，如果未提供，将使用您的默认全局设置值。货币默认为您的仪表板偏好设置（例如 "USD", "TRY", "EUR"）。

6. 打印机和报价配置

配置打印机设置和定价以获得准确的报价。您可以在仪表盘的切片配置部分管理您的默认配置，当您在 API 请求中未指定参数时，系统将自动使用这些配置。

配置类型

• 打印机档案 - 配置您的打印机设置（打印床尺寸、喷嘴直径、打印速度、层高、加速度、抖动、温度等），以匹配您的实际打印机。在仪表盘中将其设置为您的默认档案，除非您覆盖特定参数，否则它将用于所有报价请求。
• 材料档案 - 为您使用的每种材料设置材料属性（灯丝类型、密度、直径、温度、风扇速度、回抽设置、定价）。当您在请求中指定 filament_type 时，API 将自动使用匹配的材料档案。
• 全局设置 - 配置全局报价设置，如税率、固定费用、能源成本和默认货币。这些设置适用于所有报价，除非在请求中被覆盖。

档案合并方式

当您提出报价请求时，API 会使用以下优先级将您的请求参数与仪表盘档案合并：

1. 请求参数 - 您在 API 请求中明确提供的数值具有最高优先级
2. 用户档案 - 如果您设置了用户特定的默认档案，则接下来使用它
3. 全局配置 - 如果不存在用户配置，系统将回退到全局默认值。

这意味着您可以仅覆盖您需要的参数（例如，仅 layer_height 或 fill_density），同时保留来自仪表盘档案的所有其他设置。

7. Webhooks

当您的账户中发生事件时，接收实时通知：

• POST /v2/webhooks - 创建新的Webhook端点
• GET /v2/webhooks - 列出您的所有 Webhooks
• GET /v2/webhooks/{webhook_id} - 获取 Webhook 详情和交付统计信息
• PUT /v2/webhooks/{webhook_id} - 更新Webhook设置
• DELETE /v2/webhooks/{webhook_id} - 删除Webhook

支持的事件： quote.completed, quote.failed, file.uploaded, file.deleted, job.status_changed, widget.added_to_cart. Webhooks包含HMAC-SHA256签名以进行安全验证。

Webhook参考：载荷结构、签名验证、重试与重新投递

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, X-RateLimit-Window
• 当达到速率限制时，您将收到 429 Too Many Requests 响应，其中包含 Retry-After 头
• 报价和存储的月度配额基于您的订阅计划
• 限制值可按部署配置，因此请读取当前值而不要写死在代码中。上面的响应标头和该端点都会报告这些值： GET /v2/quota

10. 响应与错误

每个JSON响应都使用相同的信封结构。成功的调用返回 success: true，端点载荷位于 data 之下，因此您的客户端在任何地方都能读到一致的结构。文件下载和CSV导出是例外——它们返回原始文件内容而不是信封。

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

分页与排序

/v2/quotes 和 /v2/user/uploads 等列表端点使用 limit 和 offset 查询参数分页（默认50条，最多100条）。除结果外还会返回包含 total、limit、offset、has_more、page 和 total_pages 的 pagination 对象，因此请使用 has_more，而不要自行推算列表末尾。排序使用 field:direction 形式的可重复单一参数，例如 ?sort=created_at:desc&sort=total_price:asc；上传记录默认按最新优先排列。

错误响应

失败时返回 success: false，并附带可读的错误消息和相应的HTTP状态码。请始终根据状态码分支，而不要依赖可能被改写的消息文本。

异步报价有所不同：任务入队会以202成功返回，而随后失败的计算会在任务端点上表现为带有错误消息的 failed 状态，而不是HTTP错误。请始终检查任务状态，而不只是启动时收到的状态码。

11. RESTful、带版本的API

• 所有端点都经过版本化（例如：/v2/）
• 使用标准的HTTP方法： GET, POST, PUT, DELETE
• 由OpenAPI 3.0.3架构描述，可导入您自己的工具中
• 破坏性变更与新增内容记录在 API更新日志