Query GraphQL (lettura)

L'endpoint GraphQL /api/v1/graphql espone 16 query di lettura: whoami, workOrders, workOrder(id | reference), assets, asset(id), assetDowntimes, meters(assetId), parts (con filtro lowStock), part (per id o codice a barre), stockMovements, floorPlans(locationId), locations, vendors, customers, purchaseOrders, purchaseOrder(id | reference | erpReference). Ogni lista può essere scorsa fino in fondo con limit (1-200) più offset, tranne stockMovements, che si pagina con afterId.

Punto finale

POST https://freemaint.com/api/v1/graphql con Content-Type: application/json. Ogni query consuma 1 dalla tua quota giornaliera.

Esempio: elencare gli ordini di lavoro

query { workOrders(limit: 10, status: "OPEN") { id title priority status assetId assetName locationId locationName dueDate } } Restituisce fino a 200 righe; il limite predefinito è 50.

Recupera un articolo (per id o codice a barre)

Recuperare un singolo ricambio per id o codice a barre, con part(id: N) o part(barcode: "CODE"). barcode corrisponde al codice a barre, al codice QR, al codice articolo e al riferimento (senza distinzione tra maiuscole e minuscole, solo ricambi attivi) — la stessa corrispondenza usata dallo scanner dell'app — e restituisce null quando non trova nulla. Esempio: query { part(barcode: "ABC-123") { id name description partNumber quantity minQuantity maxStockLevel unitOfMeasure imageUrl area location { name } vendor { name website } } } Il ricambio restituisce anche description, minQuantity, maxStockLevel, imageUrl e gli oggetti annidati location e vendor — abbastanza per riempire lo schermo di un chiosco con una sola query. Corrisponde anche al vostro customReference, così un'integrazione può trovare un ricambio dal codice che porta nel vostro sistema.

Filtri disponibili

• workOrders(limit, offset, status, updatedSince) — dal più recente; paginazione con limit (1-200, predefinito 50) e offset; status è un filtro stringa sullo stato; updatedSince restituisce solo gli ordini di lavoro modificati da quel momento; gli ordini di lavoro nel cestino non vengono mai restituiti
• workOrder(id:) / workOrder(reference:) — un ordine di lavoro, trovato tramite il suo id o il riferimento che il vostro team cita (WO-2026-11-016, senza distinzione tra maiuscole e minuscole); indicate uno solo dei due. Ogni ordine di lavoro restituisce anche assetName e locationName, i nomi che un modulo o un permesso stampa
• assets(limit, offset, updatedSince) — dal più recente; paginazione con limit (1-200, predefinito 50) e offset; updatedSince restituisce solo gli asset modificati da quel momento
• assetDowntimes(assetId, openOnly, since, limit, offset) — fermi macchina, dal più recente; paginazione con limit (1-200, predefinito 50) e offset; openOnly=true restituisce solo i fermi non ancora chiusi; since (ISO 8601) restituisce i fermi INIZIATI a partire da un timestamp, il modo economico per recuperare una consegna persa
• parts(limit, offset, lowStock, updatedSince) — paginazione con limit (1-200) e offset; updatedSince restituisce solo i ricambi modificati da quel momento; lowStock=true restituisce solo gli articoli a magazzino pari o inferiori a minQuantity
• locations, vendors, customers (limit, offset, updatedSince) — ordinati per nome; paginazione con limit (1-200, predefinito 200) e offset; updatedSince restituisce solo le righe modificate da quel momento
• part(id, barcode) — ricerca di un singolo ricambio; barcode corrisponde a codice a barre, QR code, numero di parte, riferimento e riferimento personalizzato, ideale per gli scanner
• floorPlans(locationId) — le planimetrie di una posizione, con i loro marcatori (coordinate x/y in percentuale); consente a un chiosco di mostrare dove è riposto il ricambio
• meters(assetId, limit, offset) — contatori (ore di funzionamento, contapezzi, contachilometri, indicatori), dal più recente; paginazione con limit (1-200, predefinito 50) e offset; assetId limita a una macchina; lastReadingValue e lastReadingDate danno l'ultima lettura
• purchaseOrders(limit, offset, status, vendorId, updatedSince) — ordini d'acquisto con le loro righe (ciascuna con receivedQuantity), le consegne (receipts) e il fornitore, dal più recente; paginazione con limit (1-200, predefinito 50) e offset; status è PENDING, APPROVED, ORDERED, PARTIALLY_RECEIVED, RECEIVED o CANCELLED; updatedSince restituisce solo gli ordini modificati da quel momento
• purchaseOrder(id, reference, erpReference) — un singolo ordine di acquisto, trovato tramite id, riferimento FreeMaint (PO-12) o l'erpReference scritta dal tuo ERP; indicane esattamente uno
• stockMovements(limit, afterId, since, partId, workOrderId, type) — il registro dei movimenti di magazzino, dal più vecchio; paginazione con limit (1-200, predefinito 50) e afterId: passa l'id dell'ultimo movimento ricevuto per ottenere la pagina successiva, che resta esatta anche mentre vengono scritti nuovi movimenti; since (ISO 8601) parte da una data; type è ADJUSTMENT, PURCHASE, WORK_ORDER, TRANSFER, RETURN, SCRAP, INITIAL, CORRECTION o INSPECTION

Introspezione dello schema

L'introspezione è abilitata. Per esplorare lo schema completo in modo interattivo — ogni query, mutation e tipo di input con i suoi campi — punta un client GraphQL desktop (Altair, Insomnia o Postman) su POST /api/v1/graphql con il tuo token Bearer. Gli explorer che girano nel browser, come Apollo Sandbox o GraphiQL online, vengono rifiutati dalla nostra policy CORS.