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 сопоставляется со штрихкодом, QR-кодом, номером детали и внутренним артикулом (без учёта регистра, только активные позиции) — то же сопоставление, что и у сканера в приложении — и возвращает 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 сопоставляется со штрихкодом, QR-кодом, номером детали, ссылкой и пользовательской ссылкой — удобно для сканеров
• 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) или по erpReference, записанному вашей ERP; укажите ровно один параметр
• 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) к POST /api/v1/graphql с вашим токеном Bearer. Обозреватели, работающие в браузере, например Apollo Sandbox или онлайн-версия GraphiQL, отклоняются нашей политикой CORS.