Consultas GraphQL (leitura)

O endpoint GraphQL /api/v1/graphql expõe 16 queries de leitura: whoami, workOrders, workOrder(id | reference), assets, asset(id), assetDowntimes, meters(assetId), parts (com filtro lowStock), part (por id ou código de barras), stockMovements, floorPlans(locationId), locations, vendors, customers, purchaseOrders, purchaseOrder(id | reference | erpReference). Todas as listas podem ser percorridas até ao fim com limit (1-200) mais offset — exceto stockMovements, que se pagina com afterId.

Ponto final

POST https://freemaint.com/api/v1/graphql com Content-Type: application/json. Cada consulta consome 1 unidade da sua quota diária.

Exemplo: listar ordens de trabalho

query { workOrders(limit: 10, status: "OPEN") { id title priority status assetId assetName locationId locationName dueDate } } Devolve até 200 linhas; o limite predefinido é 50.

Obter uma peça (por id ou código de barras)

Obter uma única peça por id ou código de barras, com part(id: N) ou part(barcode: "CODE"). barcode corresponde ao código de barras, ao código QR, ao número de peça e à referência (sem distinguir maiúsculas, apenas peças ativas) — a mesma correspondência que o scanner da aplicação usa — e devolve null quando nada corresponde. Exemplo: query { part(barcode: "ABC-123") { id name description partNumber quantity minQuantity maxStockLevel unitOfMeasure imageUrl area location { name } vendor { name website } } } A peça devolve também description, minQuantity, maxStockLevel, imageUrl e os objetos aninhados location e vendor — o suficiente para preencher o ecrã de um quiosque numa só query. Corresponde também à sua própria customReference, pelo que uma integração pode encontrar uma peça pelo código que ela tem no seu sistema.

Filtros disponíveis

• workOrders(limit, offset, status, updatedSince) — da mais recente para a mais antiga; paginação com limit (1-200, 50 por omissão) e offset; status é um filtro de string de estado; updatedSince devolve apenas as ordens de trabalho alteradas desde esse momento; as ordens de trabalho que estão na Reciclagem nunca são devolvidas
• workOrder(id:) / workOrder(reference:) — uma ordem de trabalho, encontrada pelo seu id ou pela referência que a sua equipa cita (WO-2026-11-016, sem distinguir maiúsculas); indique apenas um dos dois. Cada ordem de trabalho devolve também assetName e locationName, os nomes que um formulário ou uma permissão imprime
• assets(limit, offset, updatedSince) — do mais recente para o mais antigo; paginação com limit (1-200, 50 por omissão) e offset; updatedSince devolve apenas os ativos alterados desde esse momento
• assetDowntimes(assetId, openOnly, since, limit, offset) — paragens de máquina, da mais recente para a mais antiga; paginação com limit (1-200, 50 por omissão) e offset; openOnly=true devolve apenas as paragens ainda abertas; since (ISO 8601) devolve as paragens INICIADAS a partir de um carimbo temporal, a forma barata de recuperar uma entrega falhada
• parts(limit, offset, lowStock, updatedSince) — paginação com limit (1-200) e offset; updatedSince devolve apenas as peças alteradas desde esse momento; lowStock=true devolve apenas os artigos com stock igual ou inferior a minQuantity
• locations, vendors, customers (limit, offset, updatedSince) — ordenados por nome; paginação com limit (1-200, 200 por omissão) e offset; updatedSince devolve apenas as linhas alteradas desde esse momento
• part(id, barcode) — procura de uma peça; barcode corresponde ao código de barras, ao código QR, ao número de peça, à referência e à referência personalizada, ideal para leitores
• floorPlans(locationId) — as plantas de uma localização, com os seus marcadores (coordenadas x/y em percentagem); permite a um quiosque mostrar onde a peça está guardada
• meters(assetId, limit, offset) — contadores (horas de funcionamento, totalizadores, conta-quilómetros, indicadores), do mais recente para o mais antigo; paginação com limit (1-200, 50 por omissão) e offset; assetId restringe a uma máquina; lastReadingValue e lastReadingDate dão a última leitura
• purchaseOrders(limit, offset, status, vendorId, updatedSince) — notas de encomenda com as suas linhas (cada uma com receivedQuantity), as suas entregas (receipts) e o fornecedor, da mais recente para a mais antiga; paginação com limit (1-200, predefinição 50) e offset; status é PENDING, APPROVED, ORDERED, PARTIALLY_RECEIVED, RECEIVED ou CANCELLED; updatedSince devolve apenas as encomendas alteradas desde esse momento
• purchaseOrder(id, reference, erpReference) — uma encomenda de compra, encontrada pelo id, pela referência FreeMaint (PO-12) ou pela erpReference que o seu ERP escreveu; indique exatamente um
• stockMovements(limit, afterId, since, partId, workOrderId, type) — o registo de movimentos de stock, do mais antigo para o mais recente; paginação com limit (1-200, 50 por omissão) e afterId: indique o id do último movimento recebido para obter a página seguinte, que se mantém exata enquanto são escritos novos movimentos; since (ISO 8601) parte de uma data; type é ADJUSTMENT, PURCHASE, WORK_ORDER, TRANSFER, RETURN, SCRAP, INITIAL, CORRECTION ou INSPECTION

Introspecção de esquema

A introspecção está ativada. Para explorar o esquema completo de forma interativa — cada consulta, mutação e tipo de entrada com os respetivos campos —, aponte um cliente GraphQL instalado no computador (Altair, Insomnia ou Postman) para POST /api/v1/graphql com o seu token Bearer. Os exploradores que correm no navegador, como o Apollo Sandbox ou o GraphiQL online, são recusados pela nossa política CORS.