Prezentare generală a API-ului

FreeMaint expune o singură suprafață API pentru integrări între sisteme: GraphQL, la /api/v1/graphql. Rutele REST pe care le vezi în browser sunt API-ul aplicației însăși și se autentifică printr-o sesiune de utilizator — o cheie API nu ajunge la ele. Planifică integrarea pe GraphQL.

API REST

Rutele REST de sub /api/v1/{resource} sunt cele apelate de aplicațiile web și mobilă FreeMaint, autentificate cu sesiune de utilizator (JWT). O cheie API (fmk_...) NU le autentifică — este acceptată doar pe /api/v1/graphql și pe endpointul de preluare a datelor de energie. Pentru integrare, citește secțiunea GraphQL de mai jos.

Exemplu (sesiune de utilizator, NU o cheie API — o cheie fmk_ nu autentifică această rută): curl -H 'Authorization: Bearer <session-token>' 'https://freemaint.com/api/v1/work-orders?status=OPEN&assigneeId=42&page=1&pageSize=20'

API GraphQL

Punctul de acces GraphQL este POST /api/v1/graphql. Acoperă un subset asumat al produsului — comenzi de lucru, echipamente, opriri de mașină, piese și mișcările lor de stoc, contoare, comenzi de achiziție, amplasamente, furnizori, clienți și planuri — nu întreaga aplicație. Folosiți GraphQL când altfel ar trebui să apelați mai multe puncte de acces pentru a compune un singur ecran: de exemplu, o casetă care arată o comandă de lucru cu detaliile echipamentului, piesele consumate și costul total al manoperei. Ghidul de integrare ERP enumeră ce nu atinge schema.

Interogare exemplu: query { workOrders(status: "OPEN", limit: 10) { id reference title status priority assetId dueDate } }

Autentificare

Ambele API acceptă un token JWT în antetul Authorization, emis de POST /api/v1/auth/login și valabil 2 ore (se reînnoiește cu tokenul de reîmprospătare). Pentru integrări server-la-server folosiți în schimb o cheie API: un administrator o creează din Setări Companie > API (/company-settings/api), iar o persoană al cărei rol permite acest lucru își creează propriile chei din Profil > Securitate > Chei API (/profile/api-keys); trimiteți Authorization: Bearer fmk_... . O cheie acționează ca proprietarul ei: are permisiunile acestuia și vede doar ce vede el. IMPORTANT: o cheie API autentifică endpoint-ul GraphQL (POST /api/v1/graphql), endpoint-ul de ingestie a energiei și /public-api/{whoami,ping} — NU autentifică rutele REST de resurse, care cer un JWT de utilizator.

Disponibilitate pe niveluri

Limite de rată

Cota este un contor ZILNIC pe companie, comun pentru GraphQL și endpointul de preluare a datelor de energie, și se resetează la 00:00 UTC. Business permite 5.000 de apeluri pe zi, Enterprise 100.000. Fiecare răspuns poartă X-RateLimit-Limit, X-RateLimit-Remaining și X-RateLimit-Reset. Nu există fereastră pe minut și nici antet Retry-After. Pe suprafețele REST refuzul este un HTTP 403; pe GraphQL statusul HTTP rămâne 200 — GraphQL răspunde întotdeauna 200 — iar refuzul se află în errors[0].extensions.code = FORBIDDEN. Nu verificați statusul HTTP 403 pe GraphQL: citiți array-ul errors.

Formatul erorilor

Fiecare eroare poartă un status HTTP, un cod citibil de mașină și un mesaj citibil de om. 4xx sunt erori ale clientului (validare, permisiuni, negăsit); 5xx sunt erori de server și trebuie reîncercate cu așteptare exponențială. În GraphQL codul se află în extensions.code, iar valorile pe care le puteți filtra sunt: BAD_REQUEST, UNAUTHENTICATED, FORBIDDEN, NOT_FOUND, CONFLICT, BAD_USER_INPUT și TOO_MANY_REQUESTS. Când validarea eșuează, mesajul numește exact câmpurile greșite — de exemplu „quantity must be a number conforming to the specified constraints” — așa că nu trebuie niciodată să ghiciți pe care l-a trimis greșit sistemul dumneavoastră. O căutare care pur și simplu nu găsește nimic nu este o eroare: part(barcode:) returnează null.

SDK-uri oficiale și unelte

În prezent nu există un SDK client oficial. Endpoint-ul GraphQL are introspecția activată, așa că orice client GraphQL (Apollo, graphql-codegen, Insomnia, Postman) poate descoperi schema indicând către POST /api/v1/graphql cu cheia dvs. API. Momentan nu publicăm un document OpenAPI static și nici un fișier SDL la un URL fix.

Cheile API nu sunt disponibile pe Core sau Starter.