API 与 ERP 集成

价目表取自您的 ERP，询价再回到 ERP。告别重复录入。

MetronQ 为贵厂已在使用的管理系统提供 API，无论它是 ERP、CRM、电子表格还是自动化工具。材料价格、机床、刀具和零件文件由它传入，报价、零件读数和订单再传回给它。价目表的每一次改动都要先经过预览，然后才会写入。

查看示例与我们洽谈集成

REST 与 JSON
7 种权限范围
写入前先预览
每个响应都显示限额

您的 ERPERP · CRM · 电子表格 · 自动化

材料价格POST /config/import
刀具库PUT /machines/{key}/tools
待报价文件POST /quotes
新询价GET /quotes?since=
零件读数GET /quotes/{id}/metrics
工单状态PATCH /orders/{id}

价目表 · 报价 · 订单

01优势

哪些工作不再需要手工完成

如今在加工厂里，有六件事要靠人从一个系统抄到另一个系统。接入 API 之后，这些交给系统去做，人只需核对差异。

材料价格

目前有人把批发商发票上的价格录入 ERP，然后在报价系统里再录一遍。一旦忘了，报价就会按旧价格发出去。

接入 API 后ERP 发送新的每公斤价格。MetronQ 逐字段显示差异，预览之后才会写入。

刀具库与机床设备

目前铣刀和钻头的清单存在电子表格里，报价系统只能假定使用通用刀具。

接入 API 后刀具管理系统发送每台机床的刀具库。最小的铣刀随即决定这台机床可报价的最小内圆角。

新询价

目前有人把报价插件收到的询价，在 ERP 里重新录成一份报价单。

接入 API 后ERP 每分钟请求一次在它已有的最新一条之后产生的询价，并连同文件、材料、数量和价格一起建档。

待报价文件

目前客户用邮件发来模型或图纸，有人下载附件，再在面板里手动创建报价。

接入 API 后文件所在的系统（PDM、邮箱、客户门户）直接把文件发送报价，并收回价格、成本构成和报价 PDF。

生产准备

目前工艺员还得重新打开模型，数一遍孔和螺纹，才能编制工艺路线。

接入 API 后零件读数，包括外形尺寸、孔、型腔、螺纹和最薄壁厚，以数据而不是图片的形式进入您的系统。

订单状态

目前工单状态分散在两个地方，客户还要发邮件来问零件做得怎么样了。

接入 API 后ERP 在 MetronQ 中推进订单状态。确认和发货通知通过与面板相同的邮件发给客户。

02数据路线

最常搭建的四条数据路线

选择一条路线，查看它经过的各个站点和最关键的那个调用，并附上真实的请求与响应。

价格和目录从您的系统流入 MetronQ。在预览显示出差异之前，不会保存任何内容。

从 ERP 导出
一份 CSV 表格，或者一份包含材料、机床和表面处理的 JSON 文档。
CSV · JSON
预览
逐字段列出将要新增和修改的内容，以及系统无法识别的行和列。
POST /config/import/preview
应用
系统回传预览给出的 base_hash。如果期间有人保存了价目表，就会收到 409，需要重新预览。
POST /config/import
历史记录
导入会逐字段记入设置变更历史，并注明执行导入的密钥名称。
设置变更历史

请求：预览一份材料表

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": "a2V5O25hbWU7cHJpY2VfcGVyX2tnCmFsdV82MDYxOy..." }'

响应：将会发生的变化200 OK

{
  "ok": true,
  "added": [],
  "updated": ["alu_6061", "steel_c45"],
  "errors": [],
  "ignored_columns": [],
  "changes": [
    {
      "section": "materials",
      "path": "price_per_kg",
      "kind": "edited",
      "default": 6.4,
      "current": 6.9,
      "entity_key": "alu_6061",
      "entity_name": "Aluminium 6061",
      "unit": "field"
    }
  ],
  "changes_total": 2,
  "base_hash": "9c1e4b0f2a7d",
  "config": { "materials": [ "..." ], "machines": [ "..." ], "...": "..." }
}

03访问控制

密钥属于加工厂，而不是集成商

您在设置中创建密钥并为它分配权限，还能看到它在什么时候做过什么。

密钥只在创建时显示一次，我们也不会以可读的形式保存它。遗失的密钥可以撤销，再换发一把新的。密钥属于加工厂而不属于某个人，所以即使创建它的人在休假，它也照常工作。

权限在设计上就刻意收窄。能读取目录的密钥读不了询价；能读取询价的密钥，如果没有各自单独的权限范围，既看不到客户的个人信息，也拿不到客户上传的文件。能发送文件的密钥，并不因此就能读取报价。任何密钥都不能创建或撤销另一把密钥。

七种权限范围

config:read: 读取目录和报价规则。
config:write: 修改目录和规则，经由与面板相同的预览和应用流程。
quotes:read: 询价和订单：零件、材料、数量、价格和读数。
customers:read: 客户的联系方式。没有这个权限范围，这些字段会返回为空。
quotes:write: 您的编号和订单状态。它不能报价，也不能审批任何内容。
quotes:create: 发送零件文件进行报价，并修改报价的参数。价格由引擎计算；密钥不能审批，也不能给出折扣。
files:read: 客户上传的文件和 3D 预览，需与 quotes:read 一起使用。有意单独设立：文件是别人的设计成果。

密钥在创建 365 天后过期
撤销从下一次请求起立即生效
访问日志保存两年
mq_live_ 前缀，便于您代码仓库中的密钥扫描工具识别

app.metronq.com/settings/integrations

设置

查找参数，例如利润、装夹+ 新建报价ZH

公司通知报价单团队系统集成

API 密钥

密钥让您的 ERP、CRM 或自动化工具无需有人登录即可使用本账号：读取和更新目录与计价规则、读取报价与订单、发送零件文件进行报价以及下载文件，每项都仅限于您授予的权限。

+ 新建密钥

额度：每分钟 120 次请求，每天 20,000 次，自 UTC 00:00 起计算。今日已用：212。

名称	权限	最近使用	有效期至	每日上限
ERP 同步a1b2c3d4...	config:read, quotes:read, quotes:write	今天 09:14	2027/9/16	账户额度	撤销
价目表导入e5f6a7b8...	config:read, config:write	昨天 06:00	2027/10/2	账户额度	撤销

访问日志

记录何时有对象获得或失去读取本账号的能力。保存两年。

已导入目录价目表导入 · e5f6a7b82026/9/18 06:00
已创建密钥ERP 同步 · a1b2c3d42026/9/16 10:12
已创建密钥价目表导入 · e5f6a7b82026/10/2 08:30

设置中的「系统集成」标签页，示例数据

04调用限额

每个响应都告诉您还剩多少

集成程序在触及限额之前就清楚自己的余量，而不是事后才知道。

API 访问权限及其限额与每家加工厂单独商定。默认情况下，加工厂每分钟可发 120 次、每天 20,000 次请求，日额度从 00:00 UTC 起计算；为某个账户商定的数值可能不同。每小时同步一次目录、每分钟轮询一次新询价，都远在默认限额之内。

每个响应都附带的响应头

HTTP

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

试用密钥

在搭建集成期间，加工厂可以获得一把带有总额度的密钥，额度覆盖整个测试期。该额度不会重置，并显示在面板、whoami 和响应头中。它足以完成对接的搭建，但有意不足以支撑正式运行。

拒绝的含义

状态码	代码	如何处理
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。
404	`unknown_tool`	该机床下没有这个 key 的刀具。没有删除任何内容，因此同步程序能区分真正的删除和自身映射中的笔误。
404	`file_not_found`	无法读取已存储的文件或预览。报价本身存在，但其文件无法取回。
400	`invalid_base64`	导入预览中的 csv_base64 不是有效的 base64。没有读取或写入任何内容。
409	`config_changed`	预览与应用之间有人保存了价目表。请重新读取、预览并应用。
409	`not_analysed`	询价还没有读数：其文件仍在分析中，或者分析失败（状态为 analysis_failed）。
403	`quoting_blocked:...`	加工厂目前不能新建报价。原因写在冒号后面：trial_limit（试用的报价次数已用完）、plan_limit（套餐本月的报价次数已用完）或 daily_limit（加工厂自设的每日上限已用完）。
429	`analysis_backlog`	加工厂通过 API 发送的文件已有五个在等待分析或正在分析（来自报价插件和面板的报价不计入）。Retry-After：30 秒。
409	`file_not_uploaded`	上传的文件没有到达存储。请在上传地址有效期内（15 分钟）重新发送，然后再确认；过期之后，请新建报价。
409	`upload_expired`	确认太晚：报价创建 45 分钟后（上传地址有效期 15 分钟，另加 30 分钟宽限），上传即视为已放弃。请新建报价。
409	`quote_closed`	报价已由人工审批或拒绝，或者客户已经下单。其参数不能再更改。
409	`quote_in_review`	工艺员已开始处理，并为报价或其中某个零件填写了价格。重新计价会抹掉这些工作，因此被拒绝。
409	`not_a_drawing`	该报价不是图纸，因此没有可补全或转交人工的内容。
409	`quote_already_analyzed`	该图纸已不再等待补充信息：它已重建并报价、已转交加工厂，或正在重新分析。
422	`unknown_material, ...`	请求被拒绝，未写入任何内容。已知问题只返回一个简短代码：unknown_material、unknown_treatment、unknown_tolerance_class、unknown_hole_fit、file_too_large、unsupported_file_type、implausible_scale 等。
422	`detail: [...]`	请求体与结构定义不符：未知字段、超出范围的值、文件名中的控制字符。返回的是 FastAPI 的列表，位于 detail 下，每项包含 type、loc 和 msg。未写入任何内容。

05接口参考

全部调用，每个都附示例

一个基础地址，请求头里放密钥，收发都用 JSON。选择您编写集成所用的语言，所有示例都会随之切换。

基础地址https://app.metronq.com/api/v1/integration仅限 HTTPS

身份验证Authorization: Bearer mq_live_...加工厂设置中创建的密钥

格式JSON例外：CSV（.csv）、PDF（/pdf）、客户文件（/file）和 3D 预览（.glb）

入门

GET/whoami权限: 无

这把密钥是谁的

密钥属于哪家加工厂、能做什么、还剩多少额度。这是最值得先写的调用：它一旦跑通，剩下的就只是路径问题。

请求

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

响应200 OK

{
  "tenant": { "name": "Precision Works Ltd", "slug": "precision-works", "currency": "EUR" },
  "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,
    "requests_total": null,
    "requests_total_used": null,
    "requests_total_remaining": null,
    "day_resets": "00:00 UTC"
  }
}

{
  "materials": [ { "key": "alu_6061", "price_per_kg": 6.4, "...": "..." } ],
  "machines": [ { "key": "dmu50", "hourly_rate": 95.0, "...": "..." } ],
  "treatments": [ { "key": "anodising", "...": "..." } ],
  "params": { "margin_pct": 22.0, "...": "..." },
  "gates": { "mode": "review_all", "...": "..." },
  "machine_selection": "cheapest",
  "stock_selection": "cheapest",
  "currency": "EUR"
}

GET/catalog/materials权限: config:read

单个目录

以 JSON 返回材料、机床或表面处理目录，无需遍历整份价目表。机床条目附带各自的刀具库和标识信息块。

请求

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

响应200 OK

{
  "catalog": "materials",
  "count": 12,
  "items": [
    {
      "key": "alu_6061",
      "name": "Aluminium 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
    }
  ]
}

GET/catalog/machines.csv权限: config:read

表格形式的目录

同一个目录，形式与面板「导出」按钮生成的 CSV 相同：带 Excel 所需的 BOM，并使用加工厂自己的分隔符。

请求

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

响应200 OK

key;name;technology;hourly_rate;min_quantity;envelope_mm.1;envelope_mm.2;...
dmu50;DMU 50;milling;95,00;1;650,0;520,0;...
nlx2500;NLX 2500;turning;78,00;1;366,0;705,0;...

GET/cutting-data权限: config:read

切削数据

按材料给出计算价格所依据的切削速度和去除率，按机床给出用来缩放这些速率的主轴参数。它不是每齿进给表，也并不以此自居。

请求

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

响应200 OK

{
  "reference": { "spindle_power_kw": 15.0, "cutting_speed_m_min": 250.0 },
  "materials": [
    {
      "key": "steel_c45",
      "name": "Steel C45",
      "cutting_speed_m_min": null,
      "cutting_speed_effective_m_min": 156.2,
      "machinability_factor": 1.6,
      "mrr_rough_cm3_min": 19.5,
      "mrr_turning_effective_cm3_min": 19.5,
      "...": "..."
    }
  ],
  "machines": [
    {
      "key": "dmu50",
      "name": "DMU 50",
      "spindle_power_kw": 13.0,
      "spindle_power_factor": 0.867,
      "min_tool_radius_mm": 1.0,
      "tool_radius_effective_mm": 6.0,
      "tool_count": 3,
      "...": "..."
    }
  ]
}

刀具

GET/tools?machine=dmu50权限: config:read

加工厂的刀具

以扁平列表返回全部刀具，每把都标明所在机床及其留下的内圆角半径。用 machine 参数可以只看一台机床。

请求

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

响应200 OK

{
  "count": 3,
  "items": [
    {
      "key": "e12",
      "kind": "endmill",
      "name": "12 mm carbide, 4 flutes",
      "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", "cut_radius_mm": 4.0, "...": "..." }
  ]
}

GET/machines/dmu50/tools权限: config:read

单台机床的刀具

一台机床的刀库，以及由此得出的内圆角半径。

请求

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

响应200 OK

{
  "machine_key": "dmu50",
  "machine_name": "DMU 50",
  "count": 3,
  "min_tool_radius_mm": 1.0,
  "tool_radius_effective_mm": 6.0,
  "items": [ { "key": "e12", "...": "..." }, { "key": "d6.8", "...": "..." }, { "key": "m8", "...": "..." } ]
}

PUT/machines/dmu50/tools权限: config:write

替换刀具库

幂等操作：系统直接发送自己持有的列表，无需检查此前有什么。发送空列表，机床就恢复使用手动填写的半径。

请求

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 carbide", "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" } ] }'

响应200 OK

{
  "machine_key": "dmu50",
  "machine_name": "DMU 50",
  "count": 3,
  "min_tool_radius_mm": 1.0,
  "tool_radius_effective_mm": 6.0,
  "items": [ "..." ]
}

POST/machines/dmu50/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 }'

响应200 OK

{
  "machine_key": "dmu50",
  "machine_name": "DMU 50",
  "count": 4,
  "min_tool_radius_mm": 1.0,
  "tool_radius_effective_mm": 6.0,
  "items": [ "..." ]
}

DELETE/machines/dmu50/tools/r8h7权限: config:write

删除一把刀具

删除一把刀具。未知的 key 返回 404，同步程序因此能分辨真正的删除与自己映射中的笔误。

请求

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

响应200 OK

{
  "machine_key": "dmu50",
  "machine_name": "DMU 50",
  "count": 3,
  "min_tool_radius_mm": 1.0,
  "tool_radius_effective_mm": 6.0,
  "items": [ "..." ]
}

导入

POST/config/import/preview权限: config:write

预览表格导入

看看这份表格会带来什么。不写入任何内容：返回新增和更新的条目、逐字段差异、有问题的行、无法识别的列，以及 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": "a2V5O25hbWU7cHJpY2VfcGVyX2tnCmFsdV82MDYxOy..." }'

响应200 OK

{
  "ok": true,
  "added": [],
  "updated": ["alu_6061", "steel_c45"],
  "errors": [],
  "ignored_columns": [],
  "changes": [
    {
      "section": "materials",
      "path": "price_per_kg",
      "kind": "edited",
      "default": 6.4,
      "current": 6.9,
      "entity_key": "alu_6061",
      "entity_name": "Aluminium 6061",
      "unit": "field"
    }
  ],
  "changes_total": 2,
  "base_hash": "9c1e4b0f2a7d",
  "config": { "materials": [ "..." ], "machines": [ "..." ], "...": "..." }
}

POST/config/import/preview-json权限: config:write

预览文档导入

对整份文档做同样的预览。merge 只改动文档中写明的内容；replace 则完全以文档为准，删除也包括在内。

请求

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": [ "..." ] } }'

响应200 OK

{
  "ok": true,
  "added": ["pom_c"],
  "updated": [],
  "changes_total": 1,
  "base_hash": "9c1e4b0f2a7d",
  "...": "..."
}

POST/config/import权限: config:write

应用导入

保存预览返回的内容，并带上其 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 '{ "config": { "materials": [ "..." ], "...": "..." }, "base_hash": "9c1e4b0f2a7d" }'

响应200 OK

{
  "materials": [ { "key": "alu_6061", "price_per_kg": 6.9, "...": "..." } ],
  "machines": [ "..." ],
  "params": { "margin_pct": 22.0, "...": "..." },
  "currency": "EUR"
}

询价

GET/quotes?since=2026-09-16T00:00:00Z&limit=50权限: quotes:read

询价列表

询价按从新到旧排列。轮询用 since；status、external_ref、limit 和 offset 负责其余部分。状态取值为 created、uploaded、analyzing、analyzed、priced、approved、rejected、ordered、analysis_failed 之一。

请求

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

响应200 OK

{
  "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": 41.5,
      "total_price": 1037.5,
      "discount_pct": null,
      "customer_unit_price": 41.5,
      "currency": "EUR",
      "customer_email": "purchasing@example.com",
      "customer_data_visible": true,
      "external_ref": "",
      "source": "widget"
    }
  ],
  "limit": 50,
  "offset": 0
}

GET/quotes/QUOTE_ID权限: quotes:read

单条询价

单条询价及其已保存的价格拆解，也就是需要在自己账目中核对这笔询价的系统所需要的内容。

请求

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

响应200 OK

{
  "id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33",
  "number": 1042,
  "status": "priced",
  "unit_price": 41.5,
  "total_price": 1037.5,
  "...": "...",
  "breakdown": {
    "machine_key": "dmu50",
    "machine_name": "DMU 50",
    "machine_hourly_rate": 95.0,
    "material_cost": 172.5,
    "machining_minutes": 11.2,
    "machining_cost": 443.3,
    "setup_cost_batch": 71.3,
    "programming_cost_batch": 47.5,
    "delivery_cost": 25.0,
    "lead_days": 10,
    "...": "..."
  }
}

GET/quotes/QUOTE_ID/metrics权限: quotes:read

零件读数

分析测得的内容：外形尺寸、体积、孔、型腔、螺纹、最薄壁厚，以及报价被拦下的原因。409 not_analysed 表示文件仍在读取中。

请求

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

响应200 OK

{
  "quote_id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33",
  "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,
    "holes": [ { "diameter": 6.8, "depth": 18.0, "through": true } ],
    "pockets": [ { "depth": 6.0, "floor_area": 1840.0, "direction": [0, 0, 1], "corner_radius": 5.0, "open": false, "...": "..." } ],
    "min_wall_thickness": 3.1,
    "...": "..."
  },
  "parts": [],
  "...": "..."
}

GET/quotes/QUOTE_ID/detail权限: quotes:read

完整报价

报价页面显示的全部内容：价格处于什么状态、客户能否看到，价格明细和增值税，规格，重新计价可接受的取值，已解析的拒绝原因，审核情况，读数，装配体的各个零件，以及文件的位置。

请求

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

响应200 OK

{
  "id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33",
  "ref": "API-1043",
  "status": "priced",
  "unit_price": 41.5,
  "source": "api",
  "...": "...",
  "release": { "state": "needs_review", "customer_may_see_price": false },
  "pricing": {
    "engine_unit_price": 41.5,
    "customer_total": 1037.5,
    "delivery_cost": 25.0,
    "order_total": 1062.5,
    "vat_rate_pct": 19.0,
    "order_gross": 1264.38,
    "lead_days": 10,
    "...": "..."
  },
  "material": { "key": "alu_6061", "name": "Aluminium 6061", "density_g_cm3": 2.7, "...": "..." },
  "part_mass_kg": 0.2004,
  "specification": { "tolerance_class": "m", "surface_finish": "ra_3_2", "treatments": [], "...": "..." },
  "choices": {
    "thread_candidates": [ { "designation": "M8", "count": 4, "total_depth_mm": 72.0, "hole_key": "6.8" } ],
    "hole_fit_options": [ { "key": "8.0", "diameter": 8.0, "count": 2 } ],
    "...": "..."
  },
  "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
      }
    ],
    "review": { "note": null, "reviewed_at": null, "reviewed_by": null },
    "...": "..."
  },
  "readout": { "geometry_metrics": { "...": "..." }, "...": "..." },
  "items": [],
  "files": {
    "original": { "available": true, "path": "/quotes/6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33/file" },
    "preview": { "available": true, "path": "/quotes/6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33/preview.glb" },
    "readable": true,
    "...": "..."
  },
  "created_by_key": { "name": "PDM", "prefix": "a1b2c3d4" },
  "...": "..."
}

GET/quotes/QUOTE_ID/similar权限: quotes:read

相似零件

加工厂已审核零件中与此件最接近的三个，附带批准的价格，以及引擎当时的报价与它相差多少。

请求

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

响应200 OK

{
  "count": 1,
  "items": [
    {
      "id": "0d9e7c21-5b3a-4f10-8c6d-9a2e4b7f1c05",
      "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/QUOTE_ID/machine-options权限: quotes:read

每台机床上的价格

按这份报价为整个机床设备逐台计价：每台机床的单价，或它无法加工该零件的原因，以及引擎会选择哪一台。

请求

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

响应200 OK

{
  "count": 2,
  "items": [
    { "key": "dmu50", "name": "DMU 50", "unit_price": 41.5, "feasible": true, "reasons": [], "auto": true, "...": "..." },
    {
      "key": "vf2",
      "name": "Haas VF-2",
      "unit_price": null,
      "feasible": false,
      "reasons": [ { "code": "part_exceeds_envelope", "field": "part_size_y", "actual": 350.0, "limit": 310.0, "...": "..." } ],
      "auto": false,
      "...": "..."
    }
  ]
}

GET/quotes/QUOTE_ID/parts权限: quotes:read

装配体的各个零件

装配体的每个零件：各自待确认的螺纹和配合、工艺员为其选择的机床、材料和毛坯，以及零件没有价格时的原因。

请求

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

响应200 OK

{
  "count": 2,
  "items": [
    {
      "index": 1,
      "label": "Housing cover",
      "count": 1,
      "unpriced_reason": null,
      "price_overrides": { "machine_key": "dmu50" },
      "choices": {
        "thread_candidates": [ { "key": "1:M16", "designation": "M16", "...": "..." } ],
        "hole_fit_options": [ { "key": "1:80.0", "diameter": 80.0, "...": "..." } ],
        "...": "..."
      },
      "...": "..."
    },
    { "index": 2, "label": "Bearing 6208", "count": 2, "gate_status": "tbd", "unpriced_reason": "norm_part", "...": "..." }
  ]
}

PATCH/quotes/QUOTE_ID权限: quotes:write

在询价上写入您的编号

只保存您系统中的编号，别的一概不动。价格和审批属于引擎和工艺员。

请求

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" }'

响应200 OK

{
  "id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33",
  "number": 1042,
  "external_ref": "RFQ-2026-0455",
  "...": "..."
}

发送零件

POST/quotes权限: quotes:create

为文件创建报价

提供文件名、文件大小以及报价依据。响应中带有上传地址和请求头；文件直接进入存储，不经过我们。每个文件都计为套餐中的一次报价。

请求

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" }'

响应201 Created

{
  "quote": {
    "id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33",
    "number": 1043,
    "ref": "API-1043",
    "status": "created",
    "source": "api",
    "external_ref": "RFQ-2026-0455",
    "...": "..."
  },
  "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"
  }
}

POST/quotes/QUOTE_ID/confirm-upload权限: quotes:create

确认上传

文件已经到达：分析进入队列，分析一完成就为零件计价。重复确认不会造成任何影响。

请求

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

响应202 Accepted

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

POST/quotes/QUOTE_ID/reprice权限: quotes:create

修改参数

数量、材料、公差、螺纹、配合、表面处理或交期，改动后由引擎重新计价。适用于任何报价，直到有人做出决定为止。

请求

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" } }'

响应200 OK

{
  "quote": { "id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33", "status": "priced", "quantity": 50, "unit_price": 36.9, "...": "..." },
  "release": { "state": "instant", "customer_may_see_price": true }
}

POST/quotes/QUOTE_ID/drawing-inputs权限: quotes:create

补全图纸信息

为您的系统发送、引擎却无法转换成模型的图纸补充材料、比例或厚度，分析随后重新运行。

请求

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" }'

响应202 Accepted

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

POST/quotes/QUOTE_ID/submit-drawing权限: quotes:create

将图纸转交人工

由您的系统发送、引擎无法重建的图纸会转给工艺员，由其手工报价。

请求

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 }'

响应200 OK

{
  "quote": { "id": "6f1c0f5a-2a4d-4d7e-9f0b-2c9b8f0a1d33", "status": "priced", "unit_price": null, "...": "..." },
  "release": { "state": "manual", "customer_may_see_price": false }
}

文件与文档

GET/quotes/QUOTE_ID/pdf?locale=en权限: quotes:read

报价单文档

与面板「导出」按钮生成的 PDF 相同，可使用加工厂提供的任一语言。

请求

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

响应200 OK

Content-Type: application/pdf
Content-Disposition: attachment; filename="quote-API-1043.pdf"

GET/quotes/QUOTE_ID/file权限: quotes:read + files:read

上传的文件

客户的文件，保留原始文件名，在传出时解密。

请求

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

响应200 OK

Content-Type: application/octet-stream
Content-Disposition: attachment; filename="bracket.step"
Content-Length: 482113

GET/quotes/QUOTE_ID/preview.glb权限: quotes:read + files:read

3D 预览

面板查看器所绘制的模型，格式为二进制 glTF。其中的各个面就是逐面公差所用的键。

请求

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

响应200 OK

Content-Type: model/gltf-binary
Content-Length: 211904

GET/quotes/QUOTE_ID/items/2/preview.glb权限: quotes:read + files:read

装配体中的单个零件

单个零件的预览，按完整报价中列出的序号选取。

请求

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

响应200 OK

Content-Type: model/gltf-binary
Content-Length: 48212

订单

GET/orders?since=2026-09-16T00:00:00Z权限: quotes:read

订单列表

订单按从新到旧排列，筛选参数相同。只有具备 customers:read 权限范围时，才会返回客户信息。

请求

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

响应200 OK

{
  "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": 41.5,
      "total_price": 1062.5,
      "min_order_top_up": 0.0,
      "delivery_cost": 25.0,
      "currency": "EUR",
      "external_ref": "",
      "customer": { "name": "Alex Morgan", "company": "Example Engineering Ltd", "city": "Riverton", "...": "..." },
      "note": "",
      "customer_data_visible": true
    }
  ],
  "limit": 100,
  "offset": 0
}

GET/orders/ORDER_ID权限: quotes:read

单个订单

单个订单，附带开票与发货所需的客户信息。

请求

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

响应200 OK

{
  "id": "1b7a44c0-9d2e-4e51-8a10-64d1f0a2e777",
  "status": "confirmed",
  "payment_status": "unpaid",
  "customer": {
    "name": "Alex Morgan",
    "email": "purchasing@example.com",
    "company": "Example Engineering Ltd",
    "address": "12 Industrial Road",
    "postcode": "AB1 2CD",
    "city": "Riverton",
    "...": "..."
  },
  "note": "",
  "...": "..."
}

PATCH/orders/ORDER_ID权限: quotes:write

状态与工单号

您的编号、状态和付款标记。只改动请求体中出现的字段；确认和发货会通过邮件通知客户。

请求

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" }'

响应200 OK

{
  "id": "1b7a44c0-9d2e-4e51-8a10-64d1f0a2e777",
  "status": "in_production",
  "payment_status": "unpaid",
  "external_ref": "WO-2026-0912",
  "quantity": 25,
  "total_price": 1062.5,
  "currency": "EUR",
  "...": "..."
}

06常见问题

关于 API 的常见问题

如何获得 API 访问权限？

访问权限与每家加工厂单独商定，只需告诉我们您使用的是哪套系统。之后由账户所有者在「设置」的「系统集成」标签页中创建密钥。

做决定之前可以先测试集成吗？

可以。在搭建对接期间，加工厂可以获得一把试用密钥，附带覆盖整个测试期的请求额度。额度会显示在面板和每一个 API 响应中。

API 能自行更改客户看到的价格吗？

只能通过预览和应用来更改，与在面板中导入完全一样，而且只有持有 config:write 的密钥才能操作。每一处改动都会记入设置变更历史，并注明执行改动的密钥名称。

API 密钥能审批报价，或修改报价的价格吗？

不能。密钥可以发送文件，并修改报价所依据的参数，之后由引擎计价；也可以在询价上写入您的编号，以及推进订单状态。手工填写的价格、审批和折扣都由人工负责。

我的系统能发送零件文件进行报价吗？

可以，只需使用持有 quotes:create 的密钥。系统先创建报价，把文件直接上传到加密存储，然后确认；引擎完成分析和计价后，完整的报价就会传回。每个文件都计为加工厂套餐中的一次报价，与来自报价插件的报价完全相同。

MetronQ 会主动通知我的系统有新询价吗？

目前还不会。现在由您的系统使用 since 参数轮询新的询价和订单，这完全在默认的每分钟 120 次请求范围之内。如果您需要由我们主动推送通知，请告诉我们：下一步开发什么，取决于大家提出的需求。

集成能看到哪些客户数据？

只能看到密钥允许的内容。没有 customers:read 权限范围时，返回的询价和订单不包含客户的邮箱、联系方式和备注，customer_data_visible 字段会明确说明这些信息已被隐去。

不找开发人员，能通过 Excel 交换数据吗？

可以。面板的「报价规则」中就有 CSV 导出和导入：先导出，在表格中修改，然后导入并预览改动。

把 MetronQ 接入您已在使用的系统

告诉我们您使用的是哪款 ERP 或 CRM。我们会与您商定权限范围和限额，并在搭建对接期间为您提供试用密钥。

与我们洽谈集成完整文档