GraphQL 查询（读）

GraphQL 端点 /api/v1/graphql 提供 16 个读取查询：whoami、workOrders、workOrder(id | reference)、assets、asset(id)、assetDowntimes、meters(assetId)、parts（含 lowStock 过滤）、part（按 id 或条码）、stockMovements、floorPlans(locationId)、locations、vendors、customers、purchaseOrders、purchaseOrder(id | reference | erpReference)。每个列表都可以用 limit（1-200）加 offset 一直翻到末尾——stockMovements 除外，它用 afterId 翻页。

端点

POST https://freemaint.com/api/v1/graphql，并设置 Content-Type: application/json。每个查询消耗每日配额中的 1 次。

示例：列出工单

query { workOrders(limit: 10, status: "OPEN") { id title priority status assetId assetName locationId locationName dueDate } } 最多返回 200 行；默认限制为 50。

获取单个零件（按 id 或条形码）

按 id 或条码获取单个备件，使用 part(id: N) 或 part(barcode: "CODE")。 barcode 会匹配条码、二维码、零件号和参考号（不区分大小写，仅限启用中的备件）——与应用内扫描器使用的匹配方式相同——没有命中时返回 null。示例： query { part(barcode: "ABC-123") { id name description partNumber quantity minQuantity maxStockLevel unitOfMeasure imageUrl area location { name } vendor { name website } } } 该备件还会返回 description、minQuantity、maxStockLevel、imageUrl 以及嵌套的 location 和 vendor——一次查询即可填满自助终端的物料界面。 它同样匹配你自己的 customReference，因此集成方可以用备件在你系统里的编码来查找它。

可用的过滤器

• workOrders(limit, offset, status, updatedSince) — 按从新到旧排列；用 limit（1-200，默认 50）加 offset 翻页；status 为状态字符串过滤器；updatedSince 只返回该时刻之后修改过的工单；回收站中的工单永远不会返回
• workOrder(id:) / workOrder(reference:) — 按 id 或团队常用的编号（WO-2026-11-016，不区分大小写）查找单个工单；二者只能传一个。每个工单还会返回 assetName 和 locationName，即表单或许可上要打印的名称
• assets(limit, offset, updatedSince) — 按从新到旧排列；用 limit（1-200，默认 50）加 offset 翻页；updatedSince 只返回该时刻之后修改过的资产
• assetDowntimes(assetId, openOnly, since, limit, offset) — 设备停机记录，最新的在前；用 limit（1-200，默认 50）加 offset 翻页；openOnly=true 只返回尚未结束的停机；since（ISO 8601）返回在某个时间戳当时或之后开始的停机，这是补齐漏投递的低成本办法
• parts(limit, offset, lowStock, updatedSince) — 用 limit（1-200）配合 offset 翻页；updatedSince 只返回该时间点之后变更的备件；lowStock=true 只返回库存等于或低于 minQuantity 的备件
• locations, vendors, customers (limit, offset, updatedSince) — 按名称排序；用 limit（1-200，默认 200）加 offset 翻页；updatedSince 只返回该时刻之后修改过的记录
• part(id, barcode) — 单件查询；barcode 可匹配条码、二维码、零件号、参考号和自定义参考号，适合扫码场景
• floorPlans(locationId) — — 某位置的平面图及其标记（x/y 百分比坐标）；自助终端可据此展示零件的存放位置
• meters(assetId, limit, offset) — 计量表（运行小时、计数器、里程表、仪表），按从新到旧排序；用 limit（1-200，默认 50）加 offset 翻页；assetId 可限定到一台设备；lastReadingValue 与 lastReadingDate 给出最新读数
• purchaseOrders(limit, offset, status, vendorId, updatedSince) — 采购订单及其明细行（每行含 receivedQuantity）、到货记录（receipts）和供应商，按从新到旧排列；用 limit（1-200，默认 50）加 offset 翻页；status 取值为 PENDING、APPROVED、ORDERED、PARTIALLY_RECEIVED、RECEIVED 或 CANCELLED；updatedSince 只返回该时刻之后修改过的订单
• purchaseOrder(id, reference, erpReference) — 单个采购订单，可按 id、FreeMaint 编号（PO-12）或您的 ERP 回写的 erpReference 查找；三者只能传一个
• stockMovements(limit, afterId, since, partId, workOrderId, type) — 库存流水账，按从旧到新排列；用 limit（1-200，默认 50）配合 afterId 翻页：传入您收到的最后一条变动的 id 即可获取下一页，即使有新的变动正在写入，结果也保持准确；since（ISO 8601）指定起始日期；type 取值为 ADJUSTMENT、PURCHASE、WORK_ORDER、TRANSFER、RETURN、SCRAP、INITIAL、CORRECTION 或 INSPECTION

模式自省

已启用内省。要以交互方式浏览完整的模式（每个查询、变更和输入类型及其字段），请使用桌面版 GraphQL 客户端（Altair、Insomnia 或 Postman），携带您的 Bearer 令牌连接 POST /api/v1/graphql。在浏览器中运行的调试工具（如 Apollo Sandbox 或在线 GraphiQL）会被我们的 CORS 策略拒绝。