API 总览

FreeMaint 面向系统间集成只提供一个 API 接口：位于 /api/v1/graphql 的 GraphQL。你在浏览器中看到的 REST 路由是应用自身的 API，使用用户会话认证——API 密钥无法访问它们。请基于 GraphQL 规划集成。

REST API

/api/v1/{resource} 下的 REST 路由是 FreeMaint 网页端和移动端自己调用的，使用用户会话（JWT）认证。API 密钥（fmk_...）无法认证这些路由——它只在 /api/v1/graphql 和能源数据接入端点上被接受。若要做集成，请阅读下方的 GraphQL 部分。

示例（用户会话，不是 API 密钥——fmk_ 密钥无法认证此路由）： curl -H 'Authorization: Bearer <session-token>' 'https://freemaint.com/api/v1/work-orders?status=OPEN&assigneeId=42&page=1&pageSize=20'

GraphQL API

GraphQL 端点为 POST /api/v1/graphql。它有意只覆盖产品的一个子集——工单、资产、设备停机、备件及其库存变动、计量表、采购订单、位置、供应商、客户和楼层平面图——而不是整个应用。当你本来需要调用多个端点才能拼出一个界面时，就用 GraphQL：例如一个同时显示工单、其资产明细、已用备件和人工总成本的卡片。ERP 集成指南列出了该模式无法触及的部分。

示例查询： query { workOrders(status: "OPEN", limit: 10) { id reference title status priority assetId dueDate } }

认证

两套 API 都接受 Authorization 头中的 JWT 令牌，由 POST /api/v1/auth/login 签发，有效期 2 小时（可用刷新令牌续期）。服务器对服务器的集成请改用 API 密钥：管理员在「公司设置 > API」（/company-settings/api）中创建，角色允许的人员也可在「个人资料 > 安全 > API 密钥」（/profile/api-keys）中创建自己的密钥；发送 Authorization: Bearer fmk_... 。密钥以其所有者的身份行事：它拥有所有者的权限，并且只能看到所有者能看到的内容。重要：API 密钥可用于 GraphQL 端点（POST /api/v1/graphql）、能耗数据接入端点以及 /public-api/{whoami,ping}——但不能用于 REST 资源路由，那些路由需要用户 JWT。

各套餐可用性

速率限制

配额是按公司计的每日计数器，由 GraphQL 与能耗数据接入端点共用，在 UTC 00:00 重置。Business 每天 5,000 次调用，Enterprise 100,000 次。每个响应都带有 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset。没有按分钟的窗口，也没有 Retry-After 响应头。在 REST 接口上，拒绝是 HTTP 403；在 GraphQL 上，HTTP 状态仍然是 200——GraphQL 始终返回 200——拒绝信息在 errors[0].extensions.code = FORBIDDEN 中。不要在 GraphQL 上检测 HTTP 403，请读取 errors 数组。

错误格式

每个错误都带有 HTTP 状态、可供程序识别的代码和可读的说明。4xx 是客户端错误（校验、权限、未找到）；5xx 是服务端错误，应采用指数退避重试。在 GraphQL 中，代码位于 extensions.code，可供匹配的取值为：BAD_REQUEST、UNAUTHENTICATED、FORBIDDEN、NOT_FOUND、CONFLICT、BAD_USER_INPUT 和 TOO_MANY_REQUESTS。校验失败时，消息会明确指出出错的字段——例如“quantity must be a number conforming to the specified constraints”——因此您无需猜测系统传错了哪一个。什么都没匹配上的查询并不是错误：part(barcode:) 返回 null。

官方 SDK 与工具

目前没有官方客户端 SDK。GraphQL 端点已启用内省（introspection），因此任何 GraphQL 客户端（Apollo、graphql-codegen、Insomnia、Postman）都可以用您的 API 密钥指向 POST /api/v1/graphql 来发现 schema。我们目前不在固定 URL 上发布静态 OpenAPI 文档或 SDL 文件。

Core 和 Starter 方案不提供 API 密钥。