Consultas GraphQL (leitura)

O endpoint GraphQL em /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). Toda lista pode ser percorrida até o fim com limit (1-200) mais offset — exceto stockMovements, que pagina com afterId.

Ponto final

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

Exemplo: listar ordens de serviço

query { workOrders(limit: 10, status: "OPEN") { id title priority status assetId assetName locationId locationName dueDate } } Retorna até 200 linhas; o limite padrão é 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 QR code, ao número da peça e à referência (sem diferenciar maiúsculas, apenas peças ativas) — a mesma correspondência usada pelo scanner do app — e retorna 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 também retorna description, minQuantity, maxStockLevel, imageUrl e os objetos aninhados location e vendor — o suficiente para preencher a tela de um quiosque em uma única query. Também corresponde ao seu próprio customReference, então uma integração pode achar 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, padrão 50) e offset; status é um filtro de string de status; updatedSince retorna apenas as ordens de serviço alteradas desde aquele momento; ordens de serviço na lixeira nunca são retornadas
• workOrder(id:) / workOrder(reference:) — uma ordem de serviço, encontrada pelo id ou pela referência que sua equipe cita (WO-2026-11-016, sem diferenciar maiúsculas); informe apenas um dos dois. Cada ordem de serviço também retorna 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, padrão 50) e offset; updatedSince retorna apenas os ativos alterados desde aquele momento
• assetDowntimes(assetId, openOnly, since, limit, offset) — paradas de máquina, da mais recente para a mais antiga; paginação com limit (1-200, padrão 50) e offset; openOnly=true retorna apenas as paradas ainda abertas; since (ISO 8601) retorna as paradas que COMEÇARAM a partir de um carimbo de tempo, o jeito barato de se recuperar de uma entrega perdida
• parts(limit, offset, lowStock, updatedSince) — paginação com limit (1-200) e offset; updatedSince retorna apenas as peças alteradas desde aquele momento; lowStock=true retorna apenas os itens com estoque igual ou abaixo de minQuantity
• locations, vendors, customers (limit, offset, updatedSince) — ordenados por nome; paginação com limit (1-200, padrão 200) e offset; updatedSince retorna apenas as linhas alteradas desde aquele momento
• part(id, barcode) — busca de uma peça; barcode corresponde ao código de barras, ao QR code, ao número da peça, à referência e à referência personalizada, ideal para leitores
• floorPlans(locationId) — as plantas baixas de uma localização, com seus marcadores (coordenadas x/y em porcentagem); permite que um quiosque mostre onde a peça está armazenada
• meters(assetId, limit, offset) — medidores (horas de funcionamento, contadores, hodômetros, indicadores), do mais recente para o mais antigo; paginação com limit (1-200, padrão 50) e offset; assetId restringe a uma máquina; lastReadingValue e lastReadingDate trazem a última leitura
• purchaseOrders(limit, offset, status, vendorId, updatedSince) — pedidos de compra com suas linhas (cada uma com receivedQuantity), suas entregas (receipts) e o fornecedor, do mais recente ao mais antigo; paginação com limit (1-200, padrão 50) e offset; status é PENDING, APPROVED, ORDERED, PARTIALLY_RECEIVED, RECEIVED ou CANCELLED; updatedSince retorna apenas os pedidos alterados desde esse momento
• purchaseOrder(id, reference, erpReference) — um pedido de compra, encontrado pelo id, pela referência FreeMaint (PO-12) ou pela erpReference que o seu ERP gravou; informe exatamente um
• stockMovements(limit, afterId, since, partId, workOrderId, type) — o histórico de movimentações de estoque, da mais antiga para a mais recente; paginação com limit (1-200, padrão 50) e afterId: informe o id da última movimentação recebida para obter a próxima página, que continua exata enquanto novas movimentações são gravadas; since (ISO 8601) começa a partir de uma data; type é ADJUSTMENT, PURCHASE, WORK_ORDER, TRANSFER, RETURN, SCRAP, INITIAL, CORRECTION ou INSPECTION

Introspecção de esquema

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