从 Business 套餐起，GraphQL 端点支持 12 个写入 mutation：对工单、资产和备件的创建、更新与删除，另加用于库存变动的 adjustStock。Mutation 走的是应用自身使用的同一套服务，因此审计日志、通知以及编号自动生成（WO-XX、ASS-XX、PART-XX）表现完全一致。第十一个 addMeterReading 用于记录计量表读数（运行小时、计数器），详见下文。第十二个 setPurchaseOrderErpReference 把您 ERP 的单据编号写到采购订单上（仅限 FULL 权限的密钥），且不会触发任何 webhook，因此您的 ERP 永远不会收到自己写入的回声。
可用突变
- createWorkOrder(input) → WorkOrder
- updateWorkOrder(id, input) → WorkOrder
- deleteWorkOrder(id) → DeleteResult
- createAsset(input) → Asset
- updateAsset(id, input) → Asset
- deleteAsset(id, force?) → DeleteResult
- createPart(input) → Part
- updatePart(id, input) → Part
- deletePart(id, force?) → DeleteResult
- adjustStock(id, quantity, reason?, vendorId?, documentNumber?) → Part
- addMeterReading(meterId, value?, incrementValue?, date?, notes?, confirmRegression?) → MeterReading
- setPurchaseOrderErpReference(id, erpReference?) → PurchaseOrder
输入形状
每个突变都有一个仅包含安全字段的InputType - companyId、sequenceNumber、reference 和createdById 在服务器端填充。您只需传递标题、描述、状态、优先级、assetId、locationId 等。 零件输入还接受 barcode、maxStockLevel、locationId 和 vendorId；quantity/minQuantity/maxStockLevel 支持小数（如 0.5）。 枚举字段会被校验：priority 必须是 LOW, MEDIUM, HIGH, CRITICAL 之一；工单的 status 必须是 OPEN, SCHEDULED, IN_PROGRESS, ON_HOLD, COMPLETED, VALIDATED, CANCELLED, CLOSED 之一；资产的 status 必须是 OPERATIONAL, DEGRADED, DOWN, MAINTENANCE, STANDBY, RETIRED 之一。其他值一律以 BAD_REQUEST 拒绝。 备件输入还接受 customReference —— 你自己给这个备件的编码（例如 ERP 里的编码），随后 part(barcode:) 即可据此匹配。系统不强制其唯一性，这需要你自己保证。
示例：创建工单
创建工单： mutation($i: WorkOrderCreateInput!) { createWorkOrder(input: $i) { id title reference status createdAt } } 变量为 {"i": {"title": "Pump #3 leak", "priority": "HIGH"}}
调整库存
要更改零件数量，请使用带符号增量的 adjustStock——负数表示消耗，正数表示入库。它在单个原子事务中更新数量并写入 StockMovement 审计记录，并且绝不会让库存低于零。对于按位置管理库存的零件，请传入 locationId：变动将作用于该位置；不传则调用会被拒绝：errors[0].extensions.code 为 BAD_REQUEST，extensions.reason 为 LOCATION_STOCK_REQUIRES_LOCATION。而 updatePart(quantity) 设置的是绝对值：出于同样的原因，它在按位置管理库存的零件上会被拒绝；在其他零件上，它会把差额记录为一条 ADJUSTMENT 变动。 你还可以记录货物来源：vendorId 和 documentNumber（供应商发票或送货单号，最多 64 个字符）保存在库存变动记录本身上，因此历史记录会显示是谁供的货、凭哪份单据。两者都是可选的——普通领用不发送任何一个。供应商必须属于你的公司。
记录计量表读数
addMeterReading 在计量表（运行小时、计数器、里程表、仪表）上记录一条读数，使外部系统（SCADA、PLC 网关、ERP）无需任何人手工录入数字，即可为基于计量表的预防性维护提供数据。先查出计量表的 id：query { meters(assetId: 7) { id reference name unit type lastReadingValue lastReadingDate } } 然后在 value（计量表显示的绝对累计值）与 incrementValue（例如自上次读数以来的运行小时，服务器会将其加到上一条读数上）之间二选一，只能发送其中一个：mutation { addMeterReading(meterId: 12, value: 1250.5, date: "2026-09-25T06:00:00Z") { id value date isAnomaly } } date 可选（ISO 8601，默认为当前时间），可以是过去，但不能是将来。对于 RUNTIME 和 COUNTER 类型的计量表，低于上一条读数的值会以 BAD_REQUEST 被拒绝——计量表归零或更换后，请带上 confirmRegression: true 重新发送。读数与应用中计量表页面走同一套服务：如果它是最新一条读数，计量表触发器和基于计量表的预防性维护会与技术员录入读数时完全一样地触发。此 mutation 需要具备 FULL 访问级别的密钥。
归因
每个变更操作都以密钥所有者——即密钥所代表的那个人——的身份运行，带有其权限和数据可见范围，并在审计日志中留下其姓名。即使所有者本人可以审批，密钥也绝不会审批工作流程步骤。
安全重试（Idempotency-Key）
网络超时无法告诉您变更（mutation）是否已执行。请在每个写入请求中发送 Idempotency-Key 请求头（8 到 64 个字母、数字或连字符——可使用 UUID），重试时发送同一个键。在 7 天内，使用同一个键的重试会返回第一次调用保存的结果（响应带有 "Idempotent-Replayed: true"），而不会再次执行变更：不会产生第二个工单，也不会重复记录库存变动。
- 每次写入使用一个键。在包含多个别名变更的请求中，每个变更都会在该键下单独记录。不会比较发送的值：使用同一个键但值不同，返回的仍是第一次调用的结果。
- 失败的调用不会保留任何内容：使用同一个键重试会再次执行。
- IDEMPOTENCY_KEY_REUSED —— 在该键下，同一名称（字段或别名）已执行过另一个变更，或另一个调用方使用了该键：新的写入请使用新的键。
- IDEMPOTENCY_IN_PROGRESS —— 第一次调用仍在执行：请等待几秒后重试。
常见错误
- GRAPHQL_VALIDATION_FAILED — 输入结构不匹配（例如缺少必填的 title）
- BAD_REQUEST — 取值校验失败（例如 title 超过 500 个字符）
- FORBIDDEN — 你的套餐低于 Business
- NOT_FOUND — 该 id 不存在，或属于另一家公司
- FORBIDDEN — 密钥的访问级别不足（例如用 READ 密钥调用 mutation）
提示
相关文章
本页对您有帮助吗?