Consultas GraphQL (lectura)

El endpoint GraphQL /api/v1/graphql expone 16 consultas de lectura: whoami, workOrders, workOrder(id | reference), assets, asset(id), assetDowntimes, meters(assetId), parts (con filtro lowStock), part (por id o código de barras), stockMovements, floorPlans(locationId), locations, vendors, customers, purchaseOrders, purchaseOrder(id | reference | erpReference). Todas las listas se pueden recorrer hasta el final con limit (1-200) más offset, salvo stockMovements, que se pagina con afterId.

Punto final

POST https://freemaint.com/api/v1/graphql con Content-Type: application/json. Cada consulta consume 1 de su cuota diaria.

Ejemplo: listar órdenes de trabajo

query { workOrders(limit: 10, status: "OPEN") { id title priority status assetId assetName locationId locationName dueDate } } Devuelve hasta 200 filas; el límite por defecto es 50.

Obtener una pieza (por id o código de barras)

Obtener un único repuesto por id o por código de barras, con part(id: N) o part(barcode: "CODE"). barcode coincide con el código de barras, el código QR, el número de pieza y la referencia (sin distinguir mayúsculas, solo repuestos activos) — la misma coincidencia que usa el escáner de la app — y devuelve null si no encuentra nada. Ejemplo: query { part(barcode: "ABC-123") { id name description partNumber quantity minQuantity maxStockLevel unitOfMeasure imageUrl area location { name } vendor { name website } } } El repuesto también devuelve description, minQuantity, maxStockLevel, imageUrl y los objetos anidados location y vendor — suficiente para llenar la pantalla de un quiosco en una sola consulta. También coincide con su propio customReference, de modo que una integración puede localizar un repuesto por el código que lleva en su sistema.

Filtros disponibles

• workOrders(limit, offset, status, updatedSince) — de la más reciente a la más antigua; pagine con limit (1-200, 50 por defecto) y offset; status es un filtro de cadena de estado; updatedSince devuelve solo las órdenes de trabajo modificadas desde ese momento; las órdenes de trabajo que están en la papelera nunca se devuelven
• workOrder(id:) / workOrder(reference:) — una orden de trabajo, encontrada por su id o por la referencia que cita su equipo (WO-2026-11-016, sin distinguir mayúsculas); indique solo uno de los dos. Cada orden de trabajo devuelve también assetName y locationName, los nombres que imprime un formulario o un permiso
• assets(limit, offset, updatedSince) — del más reciente al más antiguo; pagine con limit (1-200, 50 por defecto) y offset; updatedSince devuelve solo los activos modificados desde ese momento
• assetDowntimes(assetId, openOnly, since, limit, offset) — paradas de máquina, de la más reciente a la más antigua; pagine con limit (1-200, 50 por defecto) y offset; openOnly=true devuelve solo las paradas aún abiertas; since (ISO 8601) devuelve las paradas que EMPEZARON a partir de una marca de tiempo, la forma barata de ponerse al día tras una entrega perdida
• parts(limit, offset, lowStock, updatedSince) — paginación con limit (1-200) y offset; updatedSince devuelve solo los repuestos modificados desde ese momento; lowStock=true devuelve solo los artículos con stock igual o inferior a minQuantity
• locations, vendors, customers (limit, offset, updatedSince) — ordenados por nombre; pagine con limit (1-200, 200 por defecto) y offset; updatedSince devuelve solo las filas modificadas desde ese momento
• part(id, barcode) — búsqueda de un repuesto; barcode coincide con el código de barras, el código QR, el número de pieza, la referencia y la referencia personalizada, ideal para escáneres
• floorPlans(locationId) — los planos de planta de una ubicación, con sus marcadores (coordenadas x/y en porcentaje); permite a un quiosco mostrar dónde está almacenada la pieza
• meters(assetId, limit, offset) — contadores (horas de funcionamiento, totalizadores, odómetros, indicadores), del más reciente al más antiguo; pagine con limit (1-200, 50 por defecto) y offset; assetId limita a una máquina; lastReadingValue y lastReadingDate dan la última lectura
• purchaseOrders(limit, offset, status, vendorId, updatedSince) — órdenes de compra con sus líneas (cada una con receivedQuantity), sus entregas (receipts) y su proveedor, de la más reciente a la más antigua; pagine con limit (1-200, 50 por defecto) y offset; status es PENDING, APPROVED, ORDERED, PARTIALLY_RECEIVED, RECEIVED o CANCELLED; updatedSince devuelve solo los pedidos modificados desde ese momento
• purchaseOrder(id, reference, erpReference) — una orden de compra, buscada por su id, su referencia FreeMaint (PO-12) o la erpReference que escribió su ERP; indique exactamente uno
• stockMovements(limit, afterId, since, partId, workOrderId, type) — el libro de movimientos de inventario, del más antiguo al más reciente; pagine con limit (1-200, 50 por defecto) y afterId: pase el id del último movimiento recibido para obtener la página siguiente, que sigue siendo exacta mientras se escriben nuevos movimientos; since (ISO 8601) parte de una fecha; type es ADJUSTMENT, PURCHASE, WORK_ORDER, TRANSFER, RETURN, SCRAP, INITIAL, CORRECTION o INSPECTION

Introspección de esquemas

La introspección está habilitada. Para explorar el esquema completo de forma interactiva —cada consulta, mutación y tipo de entrada con sus campos—, apunte un cliente GraphQL de escritorio (Altair, Insomnia o Postman) a POST /api/v1/graphql con su token Bearer. Nuestra política CORS rechaza los exploradores que se ejecutan en el navegador, como Apollo Sandbox o GraphiQL en línea.