Requêtes GraphQL (lecture)

Le point d'entrée GraphQL /api/v1/graphql expose 16 requêtes de lecture : whoami, workOrders, workOrder(id | reference), assets, asset(id), assetDowntimes, meters(assetId), parts (avec filtre lowStock), part (par id ou code-barres), stockMovements, floorPlans(locationId), locations, vendors, customers, purchaseOrders, purchaseOrder(id | reference | erpReference). Chaque liste peut être parcourue jusqu'au bout avec limit (1-200) et offset — sauf stockMovements, qui se pagine avec afterId.

Point de terminaison

POSTez https://freemaint.com/api/v1/graphql avec Content-Type : application/json. Chaque requête consomme 1 de votre quota quotidien.

Exemple : répertorier les bons de travail

query { workOrders(limit: 10, status: "OPEN") { id title priority status assetId assetName locationId locationName dueDate } } Renvoie jusqu'à 200 lignes ; la limite par défaut est de 50.

Récupérer une pièce (par id ou code-barres)

Récupérer une seule pièce par id ou par code-barres, avec part(id: N) ou part(barcode: "CODE"). barcode correspond au code-barres, au QR code, à la référence fabricant et à la référence interne (insensible à la casse, pièces actives uniquement) — la même correspondance que le scanner de l'application — et renvoie null si rien ne correspond. Exemple : query { part(barcode: "ABC-123") { id name description partNumber quantity minQuantity maxStockLevel unitOfMeasure imageUrl area location { name } vendor { name website } } } La pièce renvoie aussi description, minQuantity, maxStockLevel, imageUrl ainsi que location et vendor imbriqués — de quoi remplir l'écran d'une borne en une seule requête. Il correspond aussi à votre propre customReference : une intégration peut donc retrouver une pièce par le code qu'elle porte dans votre système.

Filtres disponibles

• workOrders(limit, offset, status, updatedSince) — du plus récent au plus ancien ; pagination avec limit (1-200, 50 par défaut) et offset ; status filtre sur l'état (chaîne) ; updatedSince ne renvoie que les ordres de travail modifiés depuis cet instant ; les ordres de travail placés dans la corbeille ne sont jamais renvoyés
• workOrder(id:) / workOrder(reference:) — un ordre de travail, retrouvé par son id ou par la référence que votre équipe cite (WO-2026-11-016, sans tenir compte de la casse) ; passez l'un ou l'autre, jamais les deux. Chaque ordre de travail renvoie aussi assetName et locationName, les noms qu'un formulaire ou un permis imprime
• assets(limit, offset, updatedSince) — du plus récent au plus ancien ; pagination avec limit (1-200, 50 par défaut) et offset ; updatedSince ne renvoie que les équipements modifiés depuis cet instant
• assetDowntimes(assetId, openOnly, since, limit, offset) — les arrêts machine, du plus récent au plus ancien ; pagination avec limit (1-200, 50 par défaut) et offset ; openOnly=true ne renvoie que les arrêts non terminés ; since (ISO 8601) renvoie les arrêts COMMENCÉS à partir d'un horodatage, le moyen économique de rattraper une livraison manquée
• parts(limit, offset, lowStock, updatedSince) — pagination avec limit (1-200) et offset ; updatedSince ne renvoie que les pièces modifiées depuis cet instant ; lowStock=true ne renvoie que les articles stockés au niveau ou en dessous de minQuantity
• locations, vendors, customers (limit, offset, updatedSince) — classés par nom ; pagination avec limit (1-200, 200 par défaut) et offset ; updatedSince ne renvoie que les lignes modifiées depuis cet instant
• part(id, barcode) — recherche d'une pièce ; barcode correspond au code-barres, au QR code, au numéro de pièce, à la référence et à la référence personnalisée, idéal pour les scanners
• floorPlans(locationId) — les plans d'étage d'un emplacement, avec leurs marqueurs (coordonnées x/y en pourcentage) ; permet à une borne d'afficher où la pièce est rangée
• meters(assetId, limit, offset) — compteurs (heures de marche, totalisateurs, odomètres, jauges), du plus récent au plus ancien ; pagination avec limit (1-200, 50 par défaut) et offset ; assetId restreint à une machine ; lastReadingValue et lastReadingDate donnent le dernier relevé
• purchaseOrders(limit, offset, status, vendorId, updatedSince) — bons de commande avec leurs lignes (chacune avec receivedQuantity), leurs livraisons (receipts) et leur fournisseur, du plus récent au plus ancien ; pagination par limit (1-200, 50 par défaut) et offset ; status vaut PENDING, APPROVED, ORDERED, PARTIALLY_RECEIVED, RECEIVED ou CANCELLED ; updatedSince ne renvoie que les commandes modifiées depuis cet instant
• purchaseOrder(id, reference, erpReference) — un bon de commande, retrouvé par son id, sa référence FreeMaint (PO-12) ou l'erpReference que votre ERP a réécrite ; passez-en exactement un
• stockMovements(limit, afterId, since, partId, workOrderId, type) — le journal des stocks, du plus ancien au plus récent ; pagination avec limit (1-200, 50 par défaut) et afterId : passez l'id du dernier mouvement reçu pour obtenir la page suivante, qui reste exacte pendant que de nouveaux mouvements sont écrits ; since (ISO 8601) part d'une date ; type vaut ADJUSTMENT, PURCHASE, WORK_ORDER, TRANSFER, RETURN, SCRAP, INITIAL, CORRECTION ou INSPECTION

Introspection de schéma

L'introspection est activée. Pour explorer le schéma complet de manière interactive — chaque requête, mutation et type d'entrée avec ses champs —, pointez un client GraphQL de bureau (Altair, Insomnia ou Postman) vers POST /api/v1/graphql avec votre jeton Bearer. Les explorateurs qui tournent dans le navigateur, comme Apollo Sandbox ou GraphiQL en ligne, sont refusés par notre politique CORS.