Обзор API

FreeMaint предоставляет одну программную поверхность для интеграции между системами: GraphQL по адресу /api/v1/graphql. REST-маршруты, которые вы видите в браузере, — это API самого приложения, и они аутентифицируются пользовательской сессией: ключ API до них не достаёт. Стройте интеграцию на GraphQL.

REST API

REST-маршруты вида /api/v1/{resource} вызывают веб- и мобильное приложения 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 принимают JWT-токен в заголовке Authorization, выдаваемый 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 и эндпоинта приёма энергоданных; он обнуляется в 00:00 UTC. 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. Не проверяйте статус HTTP 403 в GraphQL: читайте массив 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 включена интроспекция, поэтому любой GraphQL-клиент (Apollo, graphql-codegen, Insomnia, Postman) может получить схему, обратившись к POST /api/v1/graphql с вашим API-ключом. Статический документ OpenAPI и файл SDL по постоянному адресу мы сейчас не публикуем.

Ключи API недоступны на тарифах Core и Starter.