Panoramica delle API

FreeMaint espone una sola superficie API per le integrazioni tra sistemi: GraphQL, su /api/v1/graphql. Le rotte REST che vedi nel browser sono l'API dell'applicazione stessa, autenticata con una sessione utente — una chiave API non le raggiunge. Progetta l'integrazione su GraphQL.

API REST

Le rotte REST sotto /api/v1/{resource} sono quelle chiamate dalle app web e mobile di FreeMaint, autenticate con sessione utente (JWT). Una chiave API (fmk_...) NON le autentica — è accettata solo su /api/v1/graphql e sull'endpoint di ingest energia. Per un'integrazione leggi la sezione GraphQL più sotto.

Esempio (sessione utente, NON una chiave API — una chiave fmk_ non autentica questa rotta): curl -H 'Authorization: Bearer <session-token>' 'https://freemaint.com/api/v1/work-orders?status=OPEN&assigneeId=42&page=1&pageSize=20'

API GraphQL

L'endpoint GraphQL è POST /api/v1/graphql. Copre un sottoinsieme deliberato del prodotto — ordini di lavoro, asset, fermi macchina, ricambi e relativi movimenti di magazzino, contatori, ordini di acquisto, ubicazioni, fornitori, clienti e planimetrie — non l'intera applicazione. Usa GraphQL quando altrimenti dovresti chiamare più endpoint per comporre una sola schermata: per esempio un riquadro che mostra un ordine di lavoro con il dettaglio del suo asset, i ricambi consumati e il costo totale di manodopera. La guida all'integrazione ERP elenca ciò che lo schema non raggiunge.

Query di esempio: query { workOrders(status: "OPEN", limit: 10) { id reference title status priority assetId dueDate } }

Autenticazione

Entrambe le API accettano un token JWT nell'header Authorization, emesso da POST /api/v1/auth/login e valido 2 ore (si rinnova con il refresh token). Per integrazioni server-to-server usa invece una chiave API: un amministratore la crea in Impostazioni Azienda > API (/company-settings/api), e una persona il cui ruolo lo consente crea le proprie in Profilo > Sicurezza > Chiavi API (/profile/api-keys); invia Authorization: Bearer fmk_... . Una chiave agisce come il suo proprietario: ha i suoi permessi e vede solo ciò che vede lui. IMPORTANTE: una chiave API autentica l'endpoint GraphQL (POST /api/v1/graphql), l'endpoint di ingestione energia e /public-api/{whoami,ping} — NON autentica le rotte REST delle risorse, che richiedono un JWT utente.

Disponibilità per tier

Limiti di frequenza

La quota è un contatore GIORNALIERO per azienda, condiviso tra GraphQL e l'endpoint di ingest energia, e riparte alle 00:00 UTC. Business consente 5.000 chiamate al giorno, Enterprise 100.000. Ogni risposta porta X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Non esiste una finestra al minuto né un header Retry-After. Sulle superfici REST il rifiuto è un HTTP 403; su GraphQL lo stato HTTP resta 200 — GraphQL risponde sempre 200 — e il rifiuto è in errors[0].extensions.code = FORBIDDEN. Non controllare lo stato HTTP 403 su GraphQL: leggi l'array errors.

Formato degli errori

Ogni errore porta uno stato HTTP, un codice leggibile da una macchina e un messaggio leggibile da una persona. I 4xx sono errori del client (validazione, permessi, non trovato); i 5xx sono errori del server e vanno ritentati con backoff esponenziale. In GraphQL il codice si trova in extensions.code e i valori su cui filtrare sono: BAD_REQUEST, UNAUTHENTICATED, FORBIDDEN, NOT_FOUND, CONFLICT, BAD_USER_INPUT e TOO_MANY_REQUESTS. Quando la validazione fallisce, il messaggio indica esattamente i campi errati — per esempio «quantity must be a number conforming to the specified constraints» — così non dovrà mai indovinare quale il suo sistema ha sbagliato. Una ricerca che semplicemente non trova nulla non è un errore: part(barcode:) restituisce null.

SDK ufficiali e strumenti

Al momento non esiste un SDK client ufficiale. L'endpoint GraphQL ha l'introspezione attiva, quindi qualsiasi client GraphQL (Apollo, graphql-codegen, Insomnia, Postman) può scoprire lo schema puntando a POST /api/v1/graphql con la tua chiave API. Al momento non pubblichiamo un documento OpenAPI statico né un file SDL a un URL fisso.

Le chiavi API non sono disponibili su Core né su Starter.