系统集成与数据交换

可交换的数据

MetronQ 将加工厂的价目表存为一份计价配置。该配置包含三个目录（材料、机床、表面处理）和计价参数，可在面板之外读取和写入。数据可由 ERP、CRM 或表格提供，无需在面板中重复输入。可交换的内容如下：

• 材料 - 名称、EN 与 DIN 牌号、密度、每公斤价格、粗加工与车削金属去除率、精加工速率、毛坯余量、切削速度。
• 机床 - 名称、工艺、机时费率、行程范围、轴数、主轴功率与最高转速、刀位数、最小批量，以及制造商、型号、数控系统、出厂年份、序列号和资产编号。
• 表面处理与热处理 - 名称、类型、每公斤成本、每平方分米成本、每批固定费用、增加的交期工作日数、是否对客户可见。
• 计价规则 - 利润率、装夹与操作分钟数、最短循环时间、交期、加急系数、运费、税率，以及公差等级、几何等级和表面粗糙度的系数表。

支持两种格式：

• CSV - 每个目录一个文件。适用于 ERP 导出和人工编辑。
• JSON - 整份配置为一个文档。适用于由外部系统自动同步 MetronQ 数据的场景。

操作位置

1. 1在面板中打开「报价规则」标签页。
2. 2在左侧导航中选择「导入与导出」。
3. 3导出和导入使用下文所述的同一格式。

CSV 格式

每个目录（材料、机床、表面处理）一个文件。第一行为列名。列名在所有界面语言下都是英文标识符，导出和导入使用相同的列名。

• 行只按 key 列匹配。已有的键被更新，未知的键被新增。
• 只读取文件中存在的列。文件中缺少的列，在所有行中保持原值。
• 空单元格表示保持原值，不表示清空。因此可以导入部分数据，例如只含有库存的材料或只含本季度费率的文件。
• 导入不删除任何内容。材料和机床只能在面板中删除。
• 列分隔符与小数点成对使用：分号配逗号小数（1234,56），逗号配点号小数（1234.56）。导入时两种组合都能读取；导出使用账号的分隔符设置。
• 编码：UTF-8（带或不带 BOM），或 Windows 版 Excel 写入的中欧代码页（cp1250）。
• 单个文件最多 20 000 行，最大 2 MB。

CSV 不包含机床的刀具库，因为一行无法容纳刀具列表。通过 CSV 导入的机床保留现有刀具库，因此 CSV 导入不会改变机床的可加工范围。

JSON 格式

JSON 导出是完整的计价配置，格式与面板存储的格式相同，可原样导回。文档包含三个目录、全部计价参数、人工审核关卡设置、机床选择策略、毛坯采购策略和币种。适用于自行保存价目表副本的系统。导入时在「应用方式」中选择：

• 「合并」（默认，API 中为 merge）- 只应用文档中写明的内容。例如，含三种材料和一个利润率的文件只修改这三种材料和该利润率，其他设置保持原值。
• 「替换」（API 中为 replace）- 以文档为准，包括删除文档中未列出的条目。适用于外部系统是价目表权威数据源的情形。
• 目录按与 CSV 相同的 key 列合并，两种格式对同一条目的判定一致。

导入预览

每次导入先执行试运行，不写入任何数据。预览显示：新增和更新的条目数；现有价目表与导入后价目表之间的逐字段差异；无法读取的行；MetronQ 无法识别的列。

• 任何一行被拒绝（例如缺少密度、价格不是数字）时，整个文件被拒绝，不写入任何内容。不存在部分导入。
• 无法识别的列按名称列出，不从中读取任何数据。列错位或表头拼写错误的文件不会报错，只是相应的列不产生改动；应用导入前检查该列表。
• 预览打开期间有人保存了价目表时，导入被拒绝。重新执行导入。

每次应用的导入都逐字段记入设置变更历史，来源标记为导入。由导入引起的价格变动，可据此追溯到对应的导入文件。

API 密钥

以上操作也可通过 API 完成，无需登录面板。加工厂创建 API 密钥，交给自己的 ERP、CRM 或自动化工具使用。API 访问权限由 MetronQ 与每家加工厂单独商定：请来信说明所用的系统。密钥属于加工厂账号，不属于创建它的用户；该用户被停用或删除后，密钥仍然有效。

1. 1在面板中打开「设置」>「系统集成」。该标签页仅账号所有者可见。
2. 2点击「新建密钥」。在「用途」中填写使用该密钥的系统名称，在「可执行的操作」中勾选权限，然后点击「创建密钥」。
3. 3立即复制密钥。密钥只显示一次，MetronQ 不保存其明文。密钥遗失时，撤销该密钥并新建一个。

快速入门

以下六个步骤按集成的一般开发顺序排列。所有调用使用同一个认证请求头：Authorization: Bearer mq_live_YOUR_KEY。基础地址为 https://app.metronq.com，所有路径的前缀为 /api/v1/integration。路径以 .csv 结尾的调用返回 CSV；本节的其他调用返回 JSON。

1. 检查密钥

GET /whoami 不需要任何权限。响应包含密钥所属的加工厂、密钥的权限和请求额度。返回 200 表示密钥有效。

curl https://app.metronq.com/api/v1/integration/whoami \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "tenant": { "name": "示例精密机械有限公司", "slug": "shili-jingmi", "currency": "CNY" },
  "key": {
    "name": "ERP sync",
    "prefix": "a1b2c3d4",
    "scopes": ["config:read", "quotes:read"],
    "expires_at": "2027-09-16T10:12:00+00:00"
  },
  "rate_limit": {
    "requests_per_minute": 120,
    "requests_per_day": 20000,
    "day_resets": "00:00 UTC",
    "requests_total": 1000,
    "requests_total_used": 3,
    "requests_total_remaining": 997
  }
}

2. 读取目录

每个目录一个调用：GET /catalog/materials、GET /catalog/machines 或 GET /catalog/treatments。GET /config 一次返回整份计价配置。

curl https://app.metronq.com/api/v1/integration/catalog/materials \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "catalog": "materials",
  "count": 12,
  "items": [
    {
      "key": "alu_6061",
      "name": "6061 铝",
      "kind": "metal",
      "en_number": "EN AW-6061",
      "din_number": "3.3211",
      "density_g_cm3": 2.7,
      "price_per_kg": 6.4,
      "mrr_rough_cm3_min": 50.0,
      "mrr_turning_cm3_min": 60.0,
      "finishing_rate_cm2_min": 90.0,
      "stock_allowance_mm": 3.0,
      "cutting_speed_m_min": 250.0
    }
  ]
}

3. 轮询新的询价

在 since 参数中传入客户端已保存的最新 created_at，响应返回在该时刻及之后创建的报价（created_at >= since），因此客户端已保存的最新报价会再次返回。API 不保存游标，由客户端保存已读取的最新 created_at。limit 取值 1 到 200（默认 100），offset 用于翻页。

curl "https://app.metronq.com/api/v1/integration/quotes?since=2026-09-16T00:00:00Z&limit=50" \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "items": [
    {
      "id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33",
      "number": 1042,
      "ref": "WID-1042",
      "status": "priced",
      "created_at": "2026-09-16T08:41:12+00:00",
      "filename": "bracket.step",
      "material_key": "alu_6061",
      "quantity": 25,
      "unit_price": 330.0,
      "total_price": 8250.0,
      "discount_pct": null,
      "customer_unit_price": 330.0,
      "currency": "CNY",
      "customer_email": "caigou@example.com",
      "customer_data_visible": true,
      "external_ref": "",
      "source": "widget"
    }
  ],
  "limit": 50,
  "offset": 0
}

4. 读取文件分析数据

返回分析从文件中测得的几何数据，不含价格。每次调用对应一份报价。

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/metrics \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "quote_id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33",
  "analyzed_at": "2026-09-16T08:41:29+00:00",
  "file_extension": ".step",
  "status": "priced",
  "gate_status": "instant",
  "gate_reasons": [],
  "complexity": 34.2,
  "material_key": "alu_6061",
  "quantity": 25,
  "tolerance_class": "m",
  "surface_finish": "ra_3_2",
  "confirmed_threads": ["M8"],
  "geometry_metrics": {
    "bounding_box": { "x": 120.0, "y": 80.0, "z": 18.0 },
    "volume": 74210.5,
    "surface_area": 31890.2,
    "face_count": 46,
    "holes": [
      { "diameter": 8.2, "depth": 18.0, "through": true, "direction": [0, 0, 1] }
    ],
    "pockets": [
      { "depth": 6.0, "floor_area": 1840.0, "corner_radius": 5.0, "open": false }
    ],
    "min_wall_thickness": 3.1,
    "derived": { "volume_ratio": 0.43, "area_ratio": 1.71 }
  },
  "parts": []
}

5. 写入自有编号并更新订单状态

只修改请求体中包含的字段。

curl -X PATCH https://app.metronq.com/api/v1/integration/orders/ORDER_ID \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_ref": "WO-2026-0912", "status": "in_production"}'

{
  "id": "1b7a44c0-9d2e-4e51-8a10-64d1f0a2e777",
  "quote_id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33",
  "status": "in_production",
  "payment_status": "unpaid",
  "external_ref": "WO-2026-0912",
  "quantity": 25,
  "unit_price": 330.0,
  "total_price": 8250.0,
  "min_order_top_up": 0.0,
  "delivery_cost": 0.0,
  "currency": "CNY",
  "customer": { "name": "张三", "email": "caigou@example.com", "city": "上海", "...": "..." },
  "customer_data_visible": true,
  "...": "..."
}

6. 从 ERP 更新价目表

分两个调用：预览（POST /config/import/preview 或 POST /config/import/preview-json）和提交（POST /config/import）。预览不写入任何数据，响应中含 base_hash。提交时必须原样发送该 base_hash。

密钥的权限

• config:read - 读取目录与计价规则。
• config:write - 更新目录与计价规则，流程与面板相同：先预览，再应用。
• quotes:read - 读取报价与订单：零件、材料、数量、价格和分析读数。不含客户联系方式，联系方式需要 customers:read。持有该权限的密钥可以读取加工厂的全部询价，只授予需要这些数据的系统。
• customers:read - 读取询价与订单上的客户联系方式。仅作为 quotes:read 的附加权限使用。没有该权限时，记录照常返回，但 customer_email、customer 块和客户备注（note）为 null。只需要零件、数量和价格的系统不要授予该权限。
• quotes:write - 写入自有编号（external_ref），更新订单状态和付款状态。不能计价，也不能审批。
• quotes:create - 发送零件文件进行报价；在有人做出决定之前，修改加工厂任一报价的计价参数。价格由引擎计算。该权限不能填写价格，不能审批、拒绝或给予折扣。每个文件计为加工厂套餐中的一次报价。不包含 quotes:read。
• files:read - 下载客户上传的文件和 3D 预览，读取报价的访问码。仅作为 quotes:read 的附加权限使用。与 quotes:read 分开授予，因为读数是无法据以重建零件的数值，而文件是客户的设计。

密钥不能创建或撤销密钥，也不能修改密钥权限；这些操作只能由已登录的所有者在面板中执行，因此密钥不能延长自身的有效期。密钥在创建 365 天后过期，面板不提供其他有效期选项；到期日显示在「有效期至」列。撤销从下一次请求起生效。

可读取的数据

API 只返回本加工厂的目录和询价，不返回其他加工厂的数据。各类数据对应的接口：

• 材料 - 整个目录：牌号（EN 编号与 Werkstoffnummer）、密度、每公斤价格、金属去除率和切削速度。GET /catalog/materials
• 机床 - 工艺、机时费率、行程、轴数、主轴功率与最高转速、刀库位数、最大工件重量，以及铭牌信息（制造商、型号、数控系统、年份、资产编号）。GET /catalog/machines
• 刀具 - 刀具库的扁平列表，每行包含所属机床和引擎由该刀具推导出的内圆角半径。GET /tools
• 切削数据 - 每种材料的计价用切削速度与去除率，以及每台机床用于缩放这些速率的主轴参数。GET /cutting-data
• 表面处理 - 表面处理与热处理，含费用和交期。GET /catalog/treatments
• 询价与订单 - GET /quotes 和 GET /orders，按创建时间倒序，可用 since= 轮询。单条报价含成本构成，订单含开票与收货的客户信息。
• 文件读数 - 分析测得的数据：外形尺寸、重量、孔、型腔、螺纹、面与公差；装配体按零件分别给出。GET /quotes/{id}/metrics

每把刀具属于一台机床，因此每行都包含所属机床。CSV 目录不包含刀具，因为一行无法容纳一个列表。GET /cutting-data 不是切削参数表：MetronQ 不使用每齿进给和切深，工时模型基于每种材料的去除率。该接口返回计价所用的全部数值：加工厂填写的数值，以及引擎由其推导出的两个数值。

字段说明

单位写在字段名中：_mm、_kg、_cm3_min、_m_min。数值为 JSON 数字或字符串，金额不带格式。所有价格使用加工厂的货币，货币代码由 GET /whoami 返回（tenant.currency）。

材料（GET /catalog/materials）

• key - 材料标识符，报价中以 material_key 引用。两个系统通过 key 识别同一种材料。修改 key 等于新增一种材料，不是重命名。
• name - 材料名称，加工厂的客户在报价插件和报价单上看到该名称。API 按存储的原文返回，不作翻译。
• kind - metal 或 plastic。决定客户可选的公差、配合和表面粗糙度。
• en_number、din_number - 标准牌号（例如 EN AW-6061、1.0503）。仅用于标识，引擎计算时不使用。
• density_g_cm3 - 密度，单位 g/cm3。用于计算零件重量和材料成本。
• price_per_kg - 每公斤采购价，使用加工厂的货币。ERP 同步最常写入该字段。
• mrr_rough_cm3_min - 粗加工去除率，单位 cm3/min，以 15 kW 基准主轴为准。决定不同材料之间的加工时间差异。
• mrr_turning_cm3_min - 车削去除率，单位 cm3/min。null 表示使用粗加工去除率。
• finishing_rate_cm2_min - 精加工速率（单位时间内精加工的表面积），单位 cm2/min。
• stock_allowance_mm - 选择毛坯时在零件每一侧增加的余量，单位 mm。
• cutting_speed_m_min - 切削速度 vc，单位 m/min。null 表示由粗加工去除率推导；实际使用的数值见 GET /cutting-data 中的 cutting_speed_effective_m_min。

机床（GET /catalog/machines）

机床字段如下。除 key、name 和 datasheet 外，每个字段都影响价格或可行性判断。

• key、name - 标识符和加工厂使用的机床名称。
• technology - milling、turning、bar_turning 或 mill_turn。决定机床可加工的零件类型和适用的去除率。
• hourly_rate - 机时费率，使用加工厂的货币。从 MetronQ 机床目录选择型号时，不写入该字段；由加工厂填写。
• envelope_mm - 加工范围，单位 mm。铣床为三个值（x、y、z）；车床的第一个值为车削直径，第二个值为车削长度。
• axes - 轴数，铣床为 3 到 5。轴数大于 3 时，零件所需装夹次数减少。
• spindle_power_kw - 主轴功率，单位 kW。低于基准值 15 kW 时，去除率按比例降低；高于基准值时不提高。因此填写该字段不会降低报价。
• max_spindle_rpm - 主轴最高转速。仅在小直径刀具达不到切削速度所需转速时起作用。
• min_tool_radius_mm - 机床可加工的最小内圆角半径，单位 mm。刀具库中有可加工内角的刀具（铣床上为立铣刀，车床上为车刀片）时，不读取该字段，改用其中最小的刀具。只含钻头和丝锥的刀具库不影响该字段。
• tool_stations、max_workpiece_kg、through_spindle_coolant - 刀库位数、工作台承重（kg）、是否有主轴中心内冷。
• datasheet - maker、model、control、year、serial、inventory_no、notes。仅用于标识，引擎不读取该块。

刀具（GET /tools）

{
  "count": 2,
  "items": [
    {
      "key": "e12",
      "kind": "endmill",
      "name": "12 mm 硬质合金，4 刃",
      "diameter_mm": 12.0,
      "nose_radius_mm": null,
      "flute_length_mm": 45.0,
      "designation": "",
      "machine_key": "dmu50",
      "machine_name": "DMU 50",
      "cut_radius_mm": 6.0
    }
  ]
}

• machine_key、machine_name - 刀具所在的机床。每把刀具都属于一台机床。
• kind - drill、endmill、tap、thread_mill、reamer 或 turning_insert。
• diameter_mm - 切削直径，单位 mm。钻头和铰刀为加工出的孔径；立铣刀为刀具直径；丝锥为螺纹公称直径。
• nose_radius_mm - 车刀片的刀尖圆角半径，即车削轮廓上可加工的最小圆角。
• flute_length_mm - 可用切削长度，单位 mm。null 表示未限制，引擎不施加限制。
• cut_radius_mm - 该刀具可加工的最小内圆角半径，由 MetronQ 计算：直径的一半；车刀片为刀尖圆角半径。机床上立铣刀（车床上为车刀片）的最小 cut_radius_mm 即该机床的内角限制；钻头和丝锥不计入。

切削数据（GET /cutting-data）

响应中，引擎推导的数值与加工厂填写的数值并列返回：

{
  "reference": { "spindle_power_kw": 15.0, "cutting_speed_m_min": 250.0 },
  "materials": [
    {
      "key": "steel_c45",
      "name": "C45 碳钢",
      "kind": "metal",
      "en_number": "1.0503",
      "din_number": "",
      "density_g_cm3": 7.85,
      "cutting_speed_m_min": null,
      "cutting_speed_effective_m_min": 156.2,
      "machinability_factor": 1.6,
      "mrr_rough_cm3_min": 19.5,
      "mrr_turning_cm3_min": null,
      "mrr_turning_effective_cm3_min": 19.5,
      "finishing_rate_cm2_min": 40.0,
      "stock_allowance_mm": 3.0
    }
  ],
  "machines": [
    {
      "key": "dmu50",
      "name": "DMU 50",
      "technology": "milling",
      "spindle_power_kw": 13.0,
      "max_spindle_rpm": 10000.0,
      "spindle_power_factor": 0.867,
      "min_tool_radius_mm": 1.0,
      "tool_radius_effective_mm": 6.0,
      "tool_count": 2
    }
  ]
}

• reference - 整份价目表所依据的基准主轴功率和基准切削速度：15 kW 和 250 m/min。用于核算下列推导值。
• cutting_speed_effective_m_min - 实际使用的切削速度：加工厂填写了 cutting_speed_m_min 时使用该值，否则为 reference.cutting_speed_m_min / machinability_factor。
• machinability_factor - 材料相对铝的加工难度系数：铝为 1.0，普通钢约 1.6，不锈钢约 3。计算方法：铝基准去除率（50 cm3/min）与该材料 mrr_rough_cm3_min 之比的平方根，取值范围 1.0 到 4.0。
• mrr_turning_effective_cm3_min - 实际使用的车削去除率：mrr_turning_cm3_min；该值为 null 时取 mrr_rough_cm3_min。
• spindle_power_factor - 去除率在该机床上的缩放系数：spindle_power_kw / 15，上限 1.0，下限 0.25；未填写 spindle_power_kw 时为 1.0。
• tool_radius_effective_mm - 实际生效的最小内圆角半径：刀具库含立铣刀（车床上为车刀片）时取其中最小值，否则为 min_tool_radius_mm。

询价与订单（GET /quotes、GET /orders）

• id - 报价标识符（UUID），其他所有调用都使用该值。number 为报价编号；ref 为带来源前缀的编号，与面板显示一致，例如 WID-1042。
• status - 报价状态：created、uploaded、analyzing、analyzed、priced、approved、rejected、ordered、analysis_failed。priced、approved 和 ordered 状态带有价格。
• unit_price、total_price、currency - 单件价格和整批价格，使用加工厂的货币。未计价的报价中为 null。
• discount_pct、customer_unit_price - 加工厂给予该客户的折扣（百分比）和折后单价。unit_price 仍为已确认的价格；订单记录折后金额。无折扣时 discount_pct 为 null。
• min_order_top_up、delivery_cost - 仅订单包含：最低订单金额补差和运费。两者已计入订单的 total_price，与客户在报价插件和报价单 PDF 上看到的金额一致。在这两个字段启用之前下的订单中，两者均为 0。
• material_key、quantity - 客户选择的材料和数量。material_key 对应材料目录中的 key。
• external_ref - 自有系统的编号。系统写入前为空字符串；写入后可用 ?external_ref= 查找该报价。
• source - 报价来源：widget（加工厂网站上的报价插件）、panel（在面板中上传的文件）或 api（加工厂自己的系统通过 API 发送）。在该字段启用之前创建的报价中为空。
• customer_email - 询价中唯一的联系方式。客户的其他信息在下单时才产生。
• customer_email、customer、note - 密钥没有 customers:read 时为 null。customer_data_visible 区分两种情况：「密钥无权读取」和「客户未留下联系方式」。
• 订单另有：status（new、confirmed、in_production、shipped、cancelled）、payment_status（unpaid、paid），以及含完整开票与收货地址的 customer。
• breakdown - 仅在 GET /quotes/{id} 中返回：价格的已保存成本构成，用于在自有系统中核对价格。

文件读数（GET /quotes/{id}/metrics）

用于生产准备的字段：

• geometry_metrics.bounding_box - 外形尺寸，单位 mm。derived.bbox_sorted_dims 为同样三个值按大小排序的结果，可行性按排序后的尺寸判定。
• geometry_metrics.volume、surface_area - 零件体积（mm3）和表面积（mm2）。derived.volume_ratio 为零件体积与包围盒体积之比；比值低表示需去除的材料多。
• holes[] - 计入的每个孔：直径、深度、是否通孔、轴向。孔按圆周判定：圆柱面须覆盖近乎完整的圆周；开口圆弧（例如槽端、圆角）不计为孔。
• pockets[] - 深度、底面面积、内圆角半径，以及型腔是否开放或贯通。
• min_wall_thickness - 测得的最小壁厚，单位 mm；未测得足够薄的部位时为 null。
• gate_status、gate_reasons - 报价能否自动完成；不能时给出原因，格式为 code:machine:field:actual:limit，含拒绝所依据的实测值。

发送零件进行报价

加工厂的系统可以通过 API 发送零件文件进行报价，处理方式与报价插件上传的文件相同。支持的文件：STEP 或 IGES 模型、DXF 轮廓、PDF 图纸、图纸照片。所需权限：quotes:create。按以下顺序执行三个调用和一次上传。

1. 创建报价

调用 POST /quotes，发送文件名、文件大小和计价参数。

• 必填：filename、file_size_bytes。
• 可选：quantity（默认 1）、material_key、tolerance_class、geometric_class、surface_finish、treatments、lead_time、thickness_mm 和 units_mm（用于 DXF）、process、customer_email、locale、external_ref、label。process 决定拥有板材切割机的加工厂如何制造平板零件：machining（铣床或车床）、sheet_cutting 或 auto。auto 以及不含 process 的请求由引擎选择：加工厂的板材切割机能切割的零件均按切割报价。在没有板材切割机的加工厂，auto 的报价与以前完全相同。
• 请求体中的未知字段返回 422，不会被忽略；因此拼错的字段名不会导致按默认材料计价。
• 未知的材料在此步骤返回 422 unknown_material，不会在分析阶段才失败。

curl -X POST https://app.metronq.com/api/v1/integration/quotes \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "bracket.step", "file_size_bytes": 482113, "quantity": 25,
       "material_key": "alu_6061", "tolerance_class": "f", "external_ref": "RFQ-2026-0455"}'

{
  "quote": {
    "id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33",
    "number": 1043,
    "ref": "API-1043",
    "status": "created",
    "filename": "bracket.step",
    "quantity": 25,
    "unit_price": null,
    "external_ref": "RFQ-2026-0455",
    "source": "api",
    "...": "..."
  },
  "release": { "state": "waiting", "customer_may_see_price": false },
  "upload": {
    "method": "PUT",
    "url": "https://OBJECT_STORAGE/...",
    "headers": {
      "x-amz-server-side-encryption-customer-algorithm": "AES256",
      "x-amz-server-side-encryption-customer-key": "...",
      "x-amz-server-side-encryption-customer-key-MD5": "..."
    },
    "content_length": 482113,
    "expires_at": "2026-09-25T10:15:00+00:00"
  }
}

2. 用 PUT 把文件上传到 upload.url

文件直接上传到对象存储，不经过 MetronQ 的应用服务器。

• 原样发送 upload.headers 中的每个请求头，因为加密请求头包含在签名中。
• Content-Length 必须等于第 1 步中声明的 file_size_bytes。
• 上传地址在 expires_at 之前有效，即创建后 15 分钟。
• 文件写入存储时即以该文件专用的密钥加密。
• 如果网络只允许访问已知主机，请放行对象存储的主机。

curl -X PUT "UPLOAD_URL" \
  -H "x-amz-server-side-encryption-customer-algorithm: AES256" \
  -H "x-amz-server-side-encryption-customer-key: ..." \
  -H "x-amz-server-side-encryption-customer-key-MD5: ..." \
  --data-binary @bracket.step

3. 确认

调用 POST /quotes/{id}/confirm-upload。服务器将分析排入队列并返回 202。分析完成后，按第 1 步的参数计价。此调用再次检查套餐额度和分析中文件数上限（5 个），因为分析从此调用开始。

• 409 file_not_uploaded - 存储中没有该文件，PUT 未成功。在上传地址有效期内重新上传。
• 409 upload_expired - 上传地址已过期。重新创建报价。
• 409 quote_not_awaiting_upload - 该报价已确认过。重复确认不产生其他影响。

curl -X POST https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/confirm-upload \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "quote": { "id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33", "ref": "API-1043", "status": "uploaded", "...": "..." },
  "release": { "state": "waiting", "customer_may_see_price": false },
  "poll_after_seconds": 10
}

4. 等待价格

约每 10 秒调用一次 GET /quotes/{id}（间隔见响应中的 poll_after_seconds），直到 status 不再是 uploaded 或 analyzing。该调用返回精简记录。然后调用一次 GET /quotes/{id}/detail 读取完整报价（见下文）。这两个调用需要 quotes:read；quotes:create 不包含该权限。

• 每个文件计为一次报价。API 报价与报价插件和面板中的报价一样计入套餐额度，并受加工厂设置的每日报价上限约束。超出限制时返回 403 quoting_blocked:<reason>，<reason> 为达到的限制。只有引擎完成计价后，该报价才计费。
• 每家加工厂同时最多有 5 个经 API 发送的文件处于分析流程中；报价插件和面板中的报价不计入。第 6 个返回 429 analysis_backlog 和 Retry-After: 30。上传地址已过期但未上传文件的报价不计入。
• API 限制：文件最大 50 MB；quantity 为 1 到 100 000；treatments 最多 10 项；thickness_mm 最大 200，units_mm 最大 1000；external_ref 最多 80 个字符，label 最多 200 个字符；filename 最多 255 个字符，不得包含控制字符；drawing-inputs 中 scale_ratio 为 0.02 到 50，厚度为 0.2 到 500 mm。
• 报价创建 45 分钟后仍未确认上传时，confirm-upload 返回 upload_expired：上传地址有效期 15 分钟，另加 30 分钟宽限。
• 经 API 发送的文件在分析队列中排在报价插件和面板上传的文件之后。单个零件的分析通常需要几秒，大型装配体需要几分钟。
• API 报价的编号前缀为 API（例如 API-1043）。面板中显示发送该报价的密钥名称。
• 报价带有 customer_email 时，报价在面板中被审批后，系统将报价链接通过邮件发送给该客户，与面板中创建的报价相同。不带 customer_email 时，MetronQ 不向加工厂以外的任何人发送消息。
• POST /quotes 超时后，报价可能已经创建。发送 external_ref；超时后先调用 GET /quotes?external_ref= 查找，再决定是否重新创建。
• 文件未到达的报价不计费，其存储对象在 6 小时后删除。该报价仍保留在列表中，并计入加工厂设置的每日报价上限。

重新报价

POST /quotes/{id}/reprice（权限 quotes:create）修改报价的计价参数，由引擎重新计价。适用于加工厂的任何报价，与来源渠道无关。以下情况返回错误：

• 409 quote_closed - 报价已被审批或拒绝，或客户已下单。
• 409 quote_in_review - 工艺员已为该报价或其中某个零件填写价格。重新计价会覆盖该价格，因此被拒绝。

所有字段均为可选，省略的字段保持原值：quantity、material_key、tolerance_class、geometric_class、surface_finish、confirmed_threads、confirmed_external_threads、hole_fits、face_tolerances、treatments、lead_time、process、countersinks。process 的取值与 POST /quotes 相同。countersinks 标记切割零件需要沉孔的通孔：choices.sheet_holes 中的孔键对应 choices.countersink_angles 中的角度（{"6.0": 90}）；排样中使用该零件自己的键（2:8.0）。{} 删除所有标记。对机加工零件忽略该字段。螺纹和配合的可用取值见报价详情中的 choices。对于装配体，confirmed_threads、confirmed_external_threads 和 hole_fits 可以指定单个零件：螺纹写作 "<序号>:<规格>"（1:M16），配合写作 "<序号>:<直径>"（2:80.0）。各零件的键由 GET /quotes/{id}/parts 列出。不带序号的规格或直径适用于含有该规格或直径的所有零件。confirmed_threads、confirmed_external_threads 和 face_tolerances 各最多 200 项。face_tolerances 以 3D 预览中的面节点（例如 face_3）为键；下载预览需要 files:read。

图纸

引擎无法重建为 3D 模型的图纸停在 status analyzed，release.state 为 needs_input，drawing.reconstruction_declined 说明缺少的信息。经 API 发送的图纸有两种处理方式：

• POST /quotes/{id}/drawing-inputs - 补充 material_key、scale_ratio（图纸比例 1:2 对应 2.0）或 thickness_mm。分析重新运行，然后计价。
• POST /quotes/{id}/submit-drawing - 将图纸转交工艺员手工报价。

这两个调用只适用于经 API 发送的图纸。对通过报价插件上传的图纸返回 409 not_an_api_quote；这类图纸由上传它的客户在报价插件中处理。

完整报价详情

GET /quotes/{id}/detail（权限 quotes:read）返回面板报价详情页显示的全部数据，用于在自有系统中直接根据报价建立工单。响应包含 GET /quotes/{id} 的全部字段（名称和含义相同），以及下列字段。读取不修改报价：面板中该报价不会被标记为已打开。

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/detail \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33",
  "ref": "API-1043",
  "status": "priced",
  "unit_price": 41.5,
  "source": "api",
  "...": "...",
  "breakdown": { "machine_name": "DMU 50", "...": "..." },
  "release": { "state": "needs_review", "customer_may_see_price": false },
  "pricing": {
    "engine_unit_price": 41.5,
    "adjusted_unit_price": null,
    "customer_total": 1037.5,
    "min_order_top_up": 0.0,
    "delivery_cost": 25.0,
    "order_total": 1062.5,
    "vat_rate_pct": 19.0,
    "order_vat": 201.88,
    "order_gross": 1264.38,
    "lead_days": 10
  },
  "material": { "key": "alu_6061", "name": "Aluminium 6061", "en_number": "EN AW-6061", "din_number": "3.3211", "density_g_cm3": 2.7 },
  "part_mass_kg": 0.2004,
  "specification": {
    "tolerance_class": "f",
    "geometric_class": "K",
    "surface_finish": "ra_3_2",
    "lead_time": "standard",
    "treatments": [ { "key": "anodising", "name": "Anodising", "customer_visible": true } ],
    "confirmed_threads": null,
    "hole_fits": {},
    "...": "..."
  },
  "choices": {
    "thread_candidates": [ { "designation": "M8", "count": 4, "total_depth_mm": 72.0, "hole_key": "6.8" } ],
    "external_thread_candidates": [],
    "hole_fit_options": [ { "key": "8.0", "diameter": 8.0, "count": 2 } ],
    "section_candidate": null
  },
  "outcome": {
    "gate_status": "pending_review",
    "gate_reasons": [
      {
        "raw": "part_exceeds_envelope:vf2:part_size_y:350:310",
        "code": "part_exceeds_envelope",
        "machine_key": "vf2",
        "machine_name": "Haas VF-2",
        "field": "part_size_y",
        "actual": 350.0,
        "limit": 310.0
      }
    ],
    "dfm_reasons": [],
    "complexity": 34.2,
    "thresholds": { "complexity": 60.0, "thin_wall_mm": 1.0 },
    "analysis_error": null,
    "upload_abandoned": false,
    "review": { "note": null, "reviewed_at": null, "reviewed_by": null }
  },
  "drawing": { "is_drawing": false, "fallback": false, "reconstruction_declined": null },
  "readout": { "...": "exactly what GET /quotes/{id}/metrics returns" },
  "items": [],
  "order": null,
  "files": {
    "deleted_at": null,
    "original": { "available": true, "size_bytes": 482113, "path": "/quotes/6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33/file" },
    "preview": { "available": true, "path": "/quotes/6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33/preview.glb" },
    "readable": false
  },
  "customer_link": "https://quoting.metronq.com/precision-works/quote/1043?lang=en",
  "customer_link_shared_at": null,
  "access_code": null,
  "created_by_key": { "name": "PDM", "prefix": "a1b2c3d4" },
  "timestamps": { "analysis_queued_at": "...", "analyzed_at": "...", "billable_at": "...", "...": "..." }
}

• release.state - 价格状态：waiting（尚无价格）、abandoned（文件未到达）、needs_input（图纸等待补充信息）、failed（文件无法读取）、instant（已计价，未被拦截）、needs_review（已计价，须经工艺员审批后客户才能看到）、manual（引擎无法计价，由工艺员手工定价）、approved、rejected、ordered。
• release.customer_may_see_price - 客户的报价页面当前是否显示该价格，判断规则与该页面相同。在将价格发给任何人之前检查该字段：所有已计价的报价都有 unit_price，包括等待工艺员审批的报价。
• pricing.engine_unit_price - 引擎计算的价格。unit_price 的含义不变：当前有效价格；工艺员调整过价格时为调整后的价格（pricing.adjusted_unit_price）。
• pricing.order_total、order_vat、order_gross - 按下单规则计算的金额：零件扣除客户折扣后的价格，加上最低订单金额补差和运费，再按加工厂的税率计算增值税。计算方法与报价插件和报价单 PDF 相同。
• material、part_mass_kg - 加工厂目录中的材料，以及零件重量（体积乘以材料密度）。
• specification - 计价条件。confirmed_threads 为 null 表示该问题未被回答；空列表表示答案为「没有螺纹」。customer_visible 为 false 的表面处理由加工厂收费，但不向客户列出名称。price_overrides 为工艺员对该报价的修正，只能在面板中修改。process 为该报价选定的工艺，null 表示由引擎选择；technologies 说明报价零件的制造方式：milling、turning、laser、plasma 或 waterjet。板材切割零件另有 edge_quality（ISO 9013 标记和极限偏差）和 countersinks。ISO 2768 等级、surface_finish、hole_fits 和 face_tolerances 不适用于切割零件。
• choices - POST /quotes/{id}/reprice 对该零件接受的取值，来自分析结果：螺纹规格、外螺纹、可采用 ISO 286 配合的孔，以及识别出的轧制型材（如有）。按板材切割报价的零件 part_kind 为 sheet，processes 列出该零件可用的 process 取值（加工厂既能切割又能机加工时为两个）。切割零件另有：sheet_threads（板厚足以攻丝的螺纹）、sheet_countersinks（模型中画出的沉孔）、sheet_holes 和 countersink_angles（countersinks 接受的取值）。对于装配体，choices 描述整个模型，所有零件的孔合并计数；各零件自己的选项由 GET /quotes/{id}/parts 返回。
• outcome.gate_reasons - 审核关卡拦截报价的原因。每条包含原始字符串（raw）和解析结果：code、machine_key、machine_name、field、actual、limit。使用解析结果，不要自行解析 raw，因为机床 key 中可能含有冒号。dfm_reasons 列出零件本身难以加工的原因代码，不包括加工厂规则造成的拦截。outcome.review 包含工艺员的备注、决定时间和决定人。
• readout - 与 GET /quotes/{id}/metrics 的响应相同；分析完成前为 null。
• items - 装配体的各个零件，每个零件有自己的价格、状态、原因和成本构成。零件的几何数据在 readout.parts 中，顺序相同。文件中没有零件名称时 label 为 null。
• files - 上传文件和 3D 预览的 API 路径。下载需要 files:read；readable 表示当前密钥是否具有该权限。响应中不含下载链接，因此记录了响应的日志不能用于打开客户文件。
• customer_link、access_code - 客户查看该报价的页面地址，以及打开该页面所需的访问码。access_code 仅在密钥具有 files:read 时返回，因为该页面显示客户的图纸和 3D 模型。
• created_by_key - 经 API 创建的报价中，发送该报价的密钥名称和前缀。

相关的四个调用：

• GET /quotes/{id}/similar - 本加工厂已审核零件中与该零件最相似的 3 个，含批准价格，以及当时引擎报价与批准价格的偏差。
• GET /quotes/{id}/machine-options - 该报价在每台机床上的价格，或机床无法加工该零件的原因，以及引擎自动选择的机床。只读；指定机床只能在面板中操作。
• GET /quotes/{id}/parts - 装配体的各个零件，每个零件有自己的螺纹和配合选项，以及工艺员为其选择的机床、材料和毛坯采购方式。
• GET /quotes/{id}/pdf - 报价单 PDF，使用加工厂的语言或其提供的任一语言（?locale=）。密钥没有 customers:read 时，文档不含「客户」一行（客户邮箱）。

全部调用与示例

基础地址为 https://app.metronq.com，所有路径的前缀为 /api/v1/integration。密钥通过 Authorization: Bearer 请求头发送。请求体为 JSON。响应为 JSON，以下调用除外：路径以 .csv 结尾的调用返回 CSV；GET /quotes/{id}/pdf 返回 PDF；GET /quotes/{id}/file 和预览调用返回文件内容。每个调用的说明以所需权限开头；GET /whoami 不需要权限。

GET /whoami

无需权限。返回密钥所属的加工厂（名称、slug、货币）、密钥的名称、前缀、权限（scopes）和到期时间，以及请求额度（rate_limit）。用于检查密钥和排查 403 错误。

curl https://app.metronq.com/api/v1/integration/whoami \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

GET /config

权限：config:read。返回整份计价配置：三个目录、全部计价参数、审核关卡设置、选择策略和货币。POST /config/import/preview-json 接受该文档原样回传，无需外层包装，此时使用 merge 模式。使用 replace 模式（删除文档中未列出的条目）时，必须使用包装格式：{"config": ..., "mode": "replace"}。POST /config/import 始终需要 {config, base_hash}。

curl https://app.metronq.com/api/v1/integration/config \
  -H "Authorization: Bearer mq_live_YOUR_KEY" > pricing.json

GET /catalog/{name}

权限：config:read。以 JSON 返回一个目录，{name} 为 materials、machines 或 treatments；其他值返回 404 unknown_catalog。响应为 {catalog, count, items}。机床条目包含 tools 和 datasheet。

curl https://app.metronq.com/api/v1/integration/catalog/materials \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

GET /catalog/{name}.csv

权限：config:read。以 CSV 返回同一目录，内容与面板中「导出 CSV」生成的文件相同：带 BOM（供 Excel 识别编码），使用加工厂设置的分隔符，每个条目一行。CSV 中的机床不含刀具列表。

curl https://app.metronq.com/api/v1/integration/catalog/machines.csv \
  -H "Authorization: Bearer mq_live_YOUR_KEY" > machines.csv

key;name;technology;hourly_rate;min_quantity;envelope_mm.1;envelope_mm.2;...
dmu50;DMU 50;milling;280,00;1;500,0;450,0;400,0;...

GET /tools

权限：config:read。以扁平列表返回加工厂的全部刀具，每行包含所属机床。?machine= 只返回一台机床的刀具；该机床 key 不存在时返回 404 unknown_machine。

curl https://app.metronq.com/api/v1/integration/tools \
  -H "Authorization: Bearer mq_live_YOUR_KEY"
curl "https://app.metronq.com/api/v1/integration/tools?machine=dmu50" \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

GET /machines/{key}/tools

权限：config:read。返回一台机床的刀具库、填写的 min_tool_radius_mm，以及由刀具库得出的 tool_radius_effective_mm。

curl https://app.metronq.com/api/v1/integration/machines/dmu50/tools \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "machine_key": "dmu50",
  "machine_name": "DMU 50",
  "count": 3,
  "min_tool_radius_mm": 1.0,
  "tool_radius_effective_mm": 6.0,
  "items": [
    {
      "key": "e12",
      "kind": "endmill",
      "name": "12 mm 硬质合金",
      "diameter_mm": 12.0,
      "nose_radius_mm": null,
      "flute_length_mm": 45.0,
      "designation": "",
      "machine_key": "dmu50",
      "machine_name": "DMU 50",
      "cut_radius_mm": 6.0
    },
    { "key": "d6.8", "kind": "drill", "diameter_mm": 6.8, "cut_radius_mm": 3.4, "...": "..." },
    { "key": "m8", "kind": "tap", "diameter_mm": 8.0, "designation": "M8", "...": "..." }
  ]
}

PUT /machines/{key}/tools

权限：config:write。用请求中的列表替换整个刀具库。该调用是幂等的，结果与原有刀具库无关。列表最多 500 把刀具。同一 key 出现两次时返回 422 duplicate_tool_key。

curl -X PUT https://app.metronq.com/api/v1/integration/machines/dmu50/tools \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tools": [
        {"key": "e12", "kind": "endmill", "name": "12 mm 硬质合金",
         "diameter_mm": 12.0, "flute_length_mm": 45.0},
        {"key": "d6.8", "kind": "drill", "diameter_mm": 6.8},
        {"key": "m8", "kind": "tap", "diameter_mm": 8.0, "designation": "M8"}
      ]}'

POST /machines/{key}/tools

权限：config:write。新增一把刀具；该 key 已存在时替换该刀具。用于逐条同步变更、不重发整个刀具库的系统。

curl -X POST https://app.metronq.com/api/v1/integration/machines/dmu50/tools \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "r8h7", "kind": "reamer", "diameter_mm": 8.0}'

DELETE /machines/{key}/tools/{tool}

权限：config:write。删除一把刀具。该 key 不存在时返回 404 unknown_tool，不返回 200。

curl -X DELETE https://app.metronq.com/api/v1/integration/machines/dmu50/tools/r8h7 \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

GET /cutting-data

权限：config:read。返回每种材料的计价用切削速度和去除率，以及每台机床用于缩放这些速率的主轴参数。该接口不是切削参数表，见上文「可读取的数据」。

curl https://app.metronq.com/api/v1/integration/cutting-data \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

POST /config/import/preview

权限：config:write。对一个 CSV 目录执行试运行，不写入任何数据。请求体：catalog（materials、machines 或 treatments）和 csv_base64（Base64 编码的 CSV 文件）。响应：导入后的文档、新增和更新的键、无法读取的行、无法识别的列，以及 base_hash。

curl -X POST https://app.metronq.com/api/v1/integration/config/import/preview \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"catalog\": \"materials\", \"csv_base64\": \"$(base64 -w0 materials.csv)\"}"

POST /config/import/preview-json

权限：config:write。对整份 JSON 文档执行试运行。请求体：config 和 mode（merge 或 replace，默认 merge），或不带包装的 GET /config 文档（此时为 merge）。merge 只应用文档中写明的内容；replace 以文档为准，包括删除。两种模式下文档都必须完整：materials 和 machines 为必填，每个条目必须包含其必填字段。mode 只决定写入哪些内容，不放宽必填要求。

curl -X POST https://app.metronq.com/api/v1/integration/config/import/preview-json \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "merge", "config": {"materials": [ ... ], "machines": [ ... ]}}'

POST /config/import

权限：config:write。应用预览返回的文档。请求体：config（预览返回的文档）和 base_hash（预览返回的值）。预览之后价目表被保存过时，返回 409 config_changed。响应为已保存的文档。

curl -X POST https://app.metronq.com/api/v1/integration/config/import \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d @commit.json      # {"config": ..., "base_hash": "..."} from the preview

{
  "materials": [ { "key": "alu-6061", "price_per_kg": 32.0, "...": "..." } ],
  "machines": [ "..." ],
  "treatments": [ "..." ],
  "params": { "margin_pct": 30.0, "...": "..." },
  "gates": { "mode": "review_all", "...": "..." },
  "machine_selection": "cheapest",
  "stock_selection": "cheapest",
  "currency": "PLN"
}

GET /quotes

权限：quotes:read。返回报价列表，按 created_at 倒序。参数：since=（ISO 8601，用于轮询；返回 created_at >= since 的报价，包括客户端已有的最新报价）、status=、external_ref=、limit（1-200，默认 100）、offset。密钥没有 customers:read 时，联系方式字段为 null。

curl "https://app.metronq.com/api/v1/integration/quotes?since=2026-09-16T00:00:00Z&status=priced&limit=50&offset=0" \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

GET /quotes/{id}

权限：quotes:read。返回一条报价，含已保存的成本构成（breakdown）。加工厂在面板中移入回收站的报价，仍可通过 GET /quotes、GET /quotes/{id}、GET /quotes/{id}/metrics 和 PATCH /quotes/{id} 读取或修改；其他单条报价接口对此类报价返回 404。

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

GET /quotes/{id}/metrics

权限：quotes:read。返回分析测得的数据。文件仍在分析时返回 409 not_analysed，表示稍后重试；标识符不存在时返回 404 not_found。

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/metrics \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

GET /orders

权限：quotes:read。返回订单列表，按 created_at 倒序，参数与 GET /quotes 相同。不包含加工厂移入回收站的订单。密钥没有 customers:read 时，customer 和 note 为 null。

curl "https://app.metronq.com/api/v1/integration/orders?since=2026-09-16T00:00:00Z&external_ref=WO-2026-0912" \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "items": [
    {
      "id": "1b7a44c0-9d2e-4e51-8a10-64d1f0a2e777",
      "quote_id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33",
      "status": "confirmed",
      "payment_status": "unpaid",
      "created_at": "2026-09-16T09:12:40+00:00",
      "paid_at": null,
      "quantity": 25,
      "unit_price": 330.0,
      "total_price": 8250.0,
      "min_order_top_up": 0.0,
      "delivery_cost": 0.0,
      "currency": "CNY",
      "external_ref": "WO-2026-0912",
      "customer": {
        "name": "张三",
        "email": "caigou@example.com",
        "company": "示例机械有限公司",
        "phone": "+86 21 0000 0000",
        "address": "示例路 12 号",
        "postcode": "200000",
        "city": "上海"
      },
      "note": "",
      "customer_data_visible": true
    }
  ],
  "limit": 100,
  "offset": 0
}

GET /orders/{id}

权限：quotes:read。返回一个订单，含开票与收货的客户信息（需要 customers:read）。

curl https://app.metronq.com/api/v1/integration/orders/ORDER_ID \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

PATCH /quotes/{id}

权限：quotes:write。只写入报价的 external_ref（最多 80 个字符；空字符串清除该值）。不能修改价格、状态或审批结果。

curl -X PATCH https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_ref": "RFQ-2026-0455"}'

PATCH /orders/{id}

权限：quotes:write。修改订单的 external_ref、status（new、confirmed、in_production、shipped、cancelled）和 payment_status（unpaid、paid）。只修改请求体中包含的字段。status 改为 confirmed 或 shipped 时，系统向客户发送邮件，与在面板中操作相同。

curl -X PATCH https://app.metronq.com/api/v1/integration/orders/ORDER_ID \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_ref": "WO-2026-0912", "status": "in_production",
       "payment_status": "paid"}'

POST /quotes

权限：quotes:create。为文件创建报价并返回上传地址。成功时返回 201，响应含 quote、release 和 upload。错误：403 quoting_blocked:<reason>；429 analysis_backlog；未知的字段、文件类型、材料、表面处理、交期或等级，以及文件过大，返回 422。

curl -X POST https://app.metronq.com/api/v1/integration/quotes \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "bracket.step", "file_size_bytes": 482113, "quantity": 25,
       "material_key": "alu_6061", "tolerance_class": "f", "external_ref": "RFQ-2026-0455"}'

POST /quotes/{id}/confirm-upload

权限：quotes:create。确认文件已上传。服务器将分析排入队列，分析完成后计价，返回 202。仅适用于经 API 创建的报价，其他报价返回 409 not_an_api_quote。此调用再次检查额度和分析中文件数（403 quoting_blocked、429 analysis_backlog）。上传地址已过期时返回 409 upload_expired。

curl -X POST https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/confirm-upload \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

POST /quotes/{id}/reprice

权限：quotes:create。按新参数由引擎重新计价。适用于加工厂的任何报价，直到有人做出决定。文件仍在分析时返回 409 analysis_pending；图纸等待补充信息时返回 409 drawing_needs_input；另见上文的 409 quote_closed 和 409 quote_in_review。对于装配体，螺纹或配合的键可以指定单个零件（1:M16、2:80.0）；各零件的键由 GET /quotes/{id}/parts 列出。

curl -X POST https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/reprice \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 50, "confirmed_threads": ["M8"], "hole_fits": {"8.0": "H7"}}'

POST /quotes/{id}/drawing-inputs

权限：quotes:create。为经 API 发送、引擎无法重建的图纸补充材料、比例或厚度。分析重新运行，然后计价。返回 202。该图纸与新文件一样计入分析中文件数上限。请求体中三个字段都未提供时返回 422 no_inputs_given。

curl -X POST https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/drawing-inputs \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scale_ratio": 2.0, "material_key": "steel_c45"}'

POST /quotes/{id}/submit-drawing

权限：quotes:create。将经 API 发送、引擎无法重建的图纸转交工艺员手工报价；release.state 变为 manual。可选字段：quantity、material_key、customer_email。

curl -X POST https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/submit-drawing \
  -H "Authorization: Bearer mq_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 10}'

GET /quotes/{id}/detail

权限：quotes:read。返回面板报价详情页的全部数据，字段见上文「完整报价详情」。

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/detail \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

GET /quotes/{id}/similar

权限：quotes:read。返回本加工厂已审核零件中与该零件最相似的 3 个。auto_error_pct 为当时引擎报价与批准价格的偏差（百分比）。分析完成前 items 为空。

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/similar \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "count": 1,
  "items": [
    {
      "id": "0d9e7c21-5b3a-4f10-8c6d-9a2e4b7f1c05",
      "number": 1017,
      "ref": "WID-1017",
      "original_filename": "bracket-rev-a.step",
      "approved_unit_price": 39.0,
      "quantity": 20,
      "currency": "EUR",
      "auto_error_pct": 4.1,
      "date": "2026-08-30T14:02:11+00:00"
    }
  ]
}

GET /quotes/{id}/machine-options

权限：quotes:read。返回每台机床上的单价，或机床无法加工该零件的原因。auto 标记引擎自动选择的机床，pinned 标记工艺员指定的机床。只读。

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/machine-options \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "count": 2,
  "items": [
    { "key": "dmu50", "name": "DMU 50", "technology": "milling", "unit_price": 41.5,
      "feasible": true, "reasons": [], "pinned": false, "auto": true },
    { "key": "vf2", "name": "Haas VF-2", "technology": "milling", "unit_price": null,
      "feasible": false, "pinned": false, "auto": false,
      "reasons": [ { "raw": "part_exceeds_envelope:vf2:part_size_y:350:310", "code": "part_exceeds_envelope", "...": "..." } ] }
  ]
}

GET /quotes/{id}/parts

权限：quotes:read。返回装配体的各个零件，每个零件附带可确认的螺纹和孔，以及工艺员在面板中为该零件所做的选择。只读。单个零件（其选项见 GET /quotes/{id}/detail 的 choices）以及分析完成前，items 为空。报价不存在或属于其他加工厂时返回 404 not_found。

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/parts \
  -H "Authorization: Bearer mq_live_YOUR_KEY"

{
  "count": 2,
  "items": [
    {
      "index": 1,
      "label": "housing",
      "count": 1,
      "gate_status": "instant",
      "gate_reasons": [],
      "unpriced_reason": null,
      "price_overrides": { "machine_key": "dmu50", "stock_selection": "standard_stock" },
      "choices": {
        "thread_candidates": [ { "designation": "M16", "count": 4, "total_depth_mm": 96.0, "hole_key": "14.0", "key": "1:M16", "item_index": 1 } ],
        "external_thread_candidates": [],
        "hole_fit_options": [ { "key": "1:80.0", "diameter": 80.0, "count": 1, "hole_key": "80.0", "item_index": 1 } ]
      }
    },
    {
      "index": 2,
      "label": null,
      "count": 4,
      "gate_status": "tbd",
      "gate_reasons": [ { "raw": "probable_norm_part", "code": "probable_norm_part", "...": "..." } ],
      "unpriced_reason": "norm_part",
      "price_overrides": {},
      "choices": { "thread_candidates": [], "external_thread_candidates": [], "hole_fit_options": [] }
    }
  ]
}

• index - 零件序号，与 GET /quotes/{id}/detail 的 items 以及 readout.parts 中的序号相同。文件中没有零件名称时 label 为 null。count - 该零件在装配体中出现的次数。
• gate_status、gate_reasons - 该零件的审核关卡结果；每条原因包含原始字符串和解析结果，与报价详情相同。
• unpriced_reason - 引擎未给该零件计价的原因：norm_part（可能是外购标准件）、casting（可能是铸件）、implausible_time（计算出的加工时间不合理）、no_machine（机床库中没有机床能加工该零件；详见 gate_reasons）。引擎已计价时为 null。
• price_overrides - 工艺员在面板中为该零件所做的选择：machine_key、material_key 和 stock_selection（cheapest、cut_to_size 或 standard_stock）。缺少某个键表示该零件沿用报价的设置；{} 表示未做任何选择。只能在面板中修改。
• choices - 仅属于该零件的选项：thread_candidates、external_thread_candidates 和 hole_fit_options。key 是 POST /quotes/{id}/reprice 对该零件接受的取值：螺纹为 "<序号>:<规格>"（1:M16），用于 confirmed_threads 或 confirmed_external_threads；配合为 "<序号>:<直径>"（1:80.0），作为 hole_fits 的键。hole_key 是 3D 预览中标识该孔所用的直径。

GET /quotes/{id}/pdf

权限：quotes:read。返回 PDF 格式的报价单。?locale= 选择加工厂提供的语言之一，默认为加工厂的语言；其他语言返回 422 language_not_offered。

curl "https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/pdf?locale=en" \
  -H "Authorization: Bearer mq_live_YOUR_KEY" -o quote.pdf

GET /quotes/{id}/file

权限：quotes:read 和 files:read。返回客户上传的文件，使用原始文件名。文件尚未上传时返回 409 file_not_uploaded；文件已按保留期删除时返回 404 files_deleted。

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/file \
  -H "Authorization: Bearer mq_live_YOUR_KEY" -o bracket.step

GET /quotes/{id}/preview.glb 与 GET /quotes/{id}/items/{index}/preview.glb

权限：quotes:read 和 files:read。返回二进制 glTF 格式的 3D 预览：第一个路径为整个零件，第二个路径为装配体中序号为 {index} 的零件。没有预览时返回 404 no_preview。预览中的面节点名称（face_3 等）即 face_tolerances 使用的键。

curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/preview.glb \
  -H "Authorization: Bearer mq_live_YOUR_KEY" -o bracket.glb
curl https://app.metronq.com/api/v1/integration/quotes/QUOTE_ID/items/2/preview.glb \
  -H "Authorization: Bearer mq_live_YOUR_KEY" -o part-2.glb

请求限额

请求限额与 API 访问权限一起，由 MetronQ 与每家加工厂单独商定，不属于公开资费。默认限额为每分钟 120 次请求、每天 20 000 次；日限额按 UTC 日计算，00:00 UTC 重置。为某个账号商定的数值可以不同。每分钟限额同时按密钥和按加工厂计算。每小时同步一次目录、每分钟轮询一次报价的用量远低于默认限额。当前适用的数值见每个响应的标头、GET /whoami 的 rate_limit，以及面板的「设置」>「系统集成」。创建密钥时，可在「此密钥的每日上限（可选）」中为单个密钥设置低于账号的日限额。

用于试用的 API 访问另有第三个限额：整个试用期间的请求总数，不按日重置。其数值为每家加工厂单独设定，足以开发和测试一套集成，不用于长期运行。当前总额度和已用量见面板的「设置」>「系统集成」、GET /whoami 的 requests_total 和 requests_total_used，以及每个响应的标头。本页示例中的数值仅作说明。总额度用完后返回 429 total_quota_exceeded，不带 Retry-After，因为该额度不会自动恢复。

每个响应都包含以下标头，客户端可据此在达到限额之前调整请求频率。最后两个标头仅在试用总额度生效时出现：

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 41
X-RateLimit-Quota: 20000
X-RateLimit-Quota-Remaining: 19863
X-RateLimit-Quota-Reset: 51240
X-RateLimit-Total: 1000
X-RateLimit-Total-Remaining: 947

• X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset - 分钟窗口：限额、剩余次数、距窗口重置的秒数。
• X-RateLimit-Quota、X-RateLimit-Quota-Remaining、X-RateLimit-Quota-Reset - 日窗口：限额、剩余次数、距 00:00 UTC 的秒数。
• X-RateLimit-Total、X-RateLimit-Total-Remaining - 试用总额度和剩余次数。

错误代码

错误响应体的 detail 字段包含一个简短代码。根据该代码决定下一步处理；仅凭 HTTP 状态码无法区分错误原因。例外：请求体不符合模式时，detail 为列表，见下文的 422。

• 429 rate_limited - 分钟窗口已用完。稍后重试同一请求；Retry-After 给出等待秒数。
• 429 daily_quota_exceeded - 当日额度已用完。Retry-After 给出距 00:00 UTC 的秒数。
• 429 total_quota_exceeded - 试用总额度已用完。不带 Retry-After，因为该额度不会自动恢复。
• 401 invalid_api_key - 以下任一情况：密钥不存在、已撤销或已过期；账号的 API 访问已关闭；账号的试用、套餐或教育许可已结束。出于安全原因，所有情况返回相同的响应。
• 403 missing_scope - 密钥有效，但缺少该接口所需的权限。使用同一密钥重试无效；请使用具有所需权限的密钥。
• 404 not_found、unknown_catalog、unknown_machine - 该账号下不存在该报价或订单、目录、机床。
• 409 config_changed - 预览与提交之间价目表被保存过，提交的文档已不反映实际会发生的变更。重新读取配置，重新预览，再重新提交。
• 409 not_analysed - 报价存在，但尚无读数，文件仍在分析中。稍后重试。
• 403 quoting_blocked:<reason> - 加工厂当前不能新建报价。<reason> 为：trial_limit（试用报价次数已用完）、plan_limit（套餐当月报价次数已用完）或 daily_limit（已达到加工厂设置的每日报价上限）。冒号后的原因与面板显示的原因相同。
• 429 analysis_backlog - 该加工厂已有 5 个经 API 发送的文件处于分析流程中（报价插件和面板中的报价不计入）。Retry-After: 30 给出重试前的等待秒数。
• 409 file_not_uploaded、quote_not_awaiting_upload - 上传的文件未到达存储；或该报价已确认过。
• 409 upload_expired - 该报价的上传地址已过期。新建一份报价。
• 409 quote_in_review - 工艺员已为该报价或其中某个零件填写了价格。在面板中重新计价。
• 409 analysis_pending、drawing_needs_input、quote_closed - 依次表示：文件仍在分析中；报价是等待补充信息的图纸；已有人做出决定或客户已下单。
• 409 not_an_api_quote - 该报价不是经 API 创建的。由 confirm-upload、drawing-inputs 和 submit-drawing 返回。
• 404 files_deleted、no_preview - 文件已按保留期删除；或该报价没有 3D 预览。
• 409 quote_already_analyzed、not_a_drawing - 图纸已重建、已转交工艺员或仍在分析中，不能再补充信息或提交；或该报价不是图纸。均由 drawing-inputs 和 submit-drawing 返回。
• 404 unknown_tool、file_not_found - 该机床上没有此 key 的刀具；或无法从存储中读取该文件。
• 400 invalid_base64 - csv_base64 不是有效的 Base64。
• 422 - 请求被拒绝，未写入任何数据。已知问题以简短代码表示：unknown_material、file_too_large、unsupported_file_type、unknown_treatment、unknown_lead_time、unknown_tolerance_class、unknown_geometric_class、unknown_surface_finish、unknown_thread、unknown_external_thread、unknown_hole、unknown_hole_fit、unknown_countersink_angle、unknown_region、no_inputs_given、implausible_scale、implausible_thickness、duplicate_tool_key、language_not_offered。请求体不符合模式（取值超出范围、文件名含控制字符）时，返回 FastAPI 的错误列表：{"detail":[{"type","loc","msg"}]}。POST /quotes、POST /quotes/{id}/reprice、POST /quotes/{id}/drawing-inputs 和 POST /quotes/{id}/submit-drawing 对未知字段也返回该列表；其他接口忽略未知字段。

权限要求

面板中的导入与导出需要「报价规则」标签页的访问权限：所有者和获得该权限的员工可以使用。面板中的导出是登录会话内的下载。在面板之外，只能通过具有相应权限的 API 密钥导出。没有其他导出途径。

API 不提供定时同步，也不在报价生成时向加工厂的系统推送数据。如有此类需求，请写信至 contact@metronq.com 并说明所用的系统。