Vue d'ensemble de l'API

FreeMaint expose une seule surface d'API pour les intégrations entre systèmes : GraphQL, sur /api/v1/graphql. Les routes REST que vous voyez dans le navigateur sont l'API de l'application elle-même, authentifiée par une session utilisateur — une clé d'API ne les atteint pas. Construisez votre intégration sur GraphQL.

API REST

Les routes REST sous /api/v1/{resource} sont celles qu'appellent les applications web et mobile de FreeMaint, authentifiées par une session utilisateur (JWT). Une clé d'API (fmk_...) ne les authentifie PAS — elle n'est acceptée que sur /api/v1/graphql et sur l'endpoint d'ingestion énergie. Pour une intégration, lisez la section GraphQL ci-dessous ; les chemins REST sont documentés ici parce que vous les verrez dans l'onglet réseau de votre navigateur, pas parce qu'une clé peut les appeler.

Exemple (session utilisateur, PAS une clé d'API — une clé fmk_ n'authentifie pas cette route) : curl -H 'Authorization: Bearer <session-token>' 'https://freemaint.com/api/v1/work-orders?status=OPEN&assigneeId=42&page=1&pageSize=20'

API GraphQL

Le point d'entrée GraphQL est POST /api/v1/graphql. Il couvre un sous-ensemble assumé du produit — ordres de travail, équipements, arrêts machine, pièces et leurs mouvements de stock, compteurs, bons de commande, emplacements, fournisseurs, clients et plans — et non l'application entière. Utilisez GraphQL quand il faudrait sinon appeler plusieurs points d'entrée pour composer un seul écran : par exemple une tuile affichant un ordre de travail avec le détail de son équipement, les pièces consommées et le coût total de main-d'œuvre. Le guide d'intégration ERP énumère ce que le schéma n'atteint pas.

Exemple de requête : query { workOrders(status: "OPEN", limit: 10) { id reference title status priority assetId dueDate } }

Authentification

Les deux API acceptent un jeton JWT dans l'en-tête Authorization, émis par POST /api/v1/auth/login et valable 2 heures (renouvelable avec le jeton de rafraîchissement). Pour les intégrations serveur à serveur, utilisez plutôt une clé API : un administrateur la crée dans Paramètres de l'entreprise > API (/company-settings/api), et une personne dont le rôle l'autorise crée les siennes sous Profil > Sécurité > Clés API (/profile/api-keys) ; envoyez Authorization: Bearer fmk_... . Une clé agit en tant que son propriétaire : elle a ses autorisations et ne voit que ce qu'il voit. IMPORTANT : une clé API authentifie l'endpoint GraphQL (POST /api/v1/graphql), l'endpoint d'ingestion énergie et /public-api/{whoami,ping} — elle n'authentifie PAS les routes REST de ressources, qui exigent un JWT utilisateur.

Disponibilité par palier

Limites de débit

Le quota est un compteur JOURNALIER par société, partagé entre GraphQL et le point d'ingestion énergie, remis à zéro à 00:00 UTC. Business autorise 5 000 appels par jour, Enterprise 100 000. Chaque réponse porte X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Il n'y a ni fenêtre par minute, ni en-tête Retry-After. Sur les surfaces REST le refus est un HTTP 403 ; sur GraphQL le statut HTTP reste 200 — GraphQL répond toujours 200 — et le refus se lit dans errors[0].extensions.code = FORBIDDEN. Ne testez pas le statut HTTP 403 sur GraphQL : lisez le tableau errors.

Format d'erreur

Chaque erreur porte un statut HTTP, un code exploitable par une machine et un message lisible. Les 4xx sont des erreurs du client (validation, permission, introuvable) ; les 5xx sont des erreurs serveur, à réessayer avec un délai exponentiel. En GraphQL le code se trouve dans extensions.code, et les valeurs sur lesquelles filtrer sont : BAD_REQUEST, UNAUTHENTICATED, FORBIDDEN, NOT_FOUND, CONFLICT, BAD_USER_INPUT et TOO_MANY_REQUESTS. Quand la validation échoue, le message nomme précisément les champs fautifs — par exemple « quantity must be a number conforming to the specified constraints » — vous n'avez donc jamais à deviner lequel votre système a mal rempli. Une recherche qui ne correspond à rien n'est pas une erreur : part(barcode:) renvoie null.

SDK officiels et outillage

Il n'existe pas de SDK client officiel à ce jour. L'endpoint GraphQL a l'introspection activée : n'importe quel client GraphQL (Apollo, graphql-codegen, Insomnia, Postman) peut donc découvrir le schéma en pointant sur POST /api/v1/graphql avec votre clé API. Nous ne publions pas actuellement de document OpenAPI statique ni de fichier SDL à une URL fixe.

Les clés d'API ne sont pas disponibles en Core ni en Starter.