Przegląd API

FreeMaint udostępnia jedną powierzchnię API do integracji między systemami: GraphQL pod /api/v1/graphql. Trasy REST widoczne w przeglądarce to API samej aplikacji, uwierzytelniane sesją użytkownika — klucz API do nich nie sięga. Integrację planuj na GraphQL.

REST API

Trasy REST pod /api/v1/{resource} są wywoływane przez aplikacje webową i mobilną FreeMaint, z uwierzytelnianiem sesją użytkownika (JWT). Klucz API (fmk_...) ich NIE uwierzytelnia — jest przyjmowany wyłącznie na /api/v1/graphql oraz na punkcie przyjmowania danych energetycznych. Do integracji przeczytaj sekcję GraphQL poniżej.

Przykład (sesja użytkownika, NIE klucz API — klucz fmk_ nie uwierzytelni tej trasy): curl -H 'Authorization: Bearer <session-token>' 'https://freemaint.com/api/v1/work-orders?status=OPEN&assigneeId=42&page=1&pageSize=20'

API GraphQL

Punkt końcowy GraphQL to POST /api/v1/graphql. Obejmuje świadomie wybrany podzbiór produktu — zlecenia pracy, zasoby, postoje maszyn, części wraz z ich ruchami magazynowymi, liczniki, zamówienia zakupu, lokalizacje, dostawców, klientów i plany — a nie całą aplikację. Używaj GraphQL, gdy inaczej trzeba by wywołać kilka punktów końcowych, aby złożyć jeden ekran: na przykład kafelek pokazujący zlecenie pracy wraz ze szczegółami zasobu, zużytymi częściami i łącznym kosztem robocizny. Przewodnik integracji z ERP wymienia to, czego schemat nie obejmuje.

Przykładowe zapytanie: query { workOrders(status: "OPEN", limit: 10) { id reference title status priority assetId dueDate } }

Uwierzytelnianie

Obie API przyjmują token JWT w nagłówku Authorization, wystawiany przez POST /api/v1/auth/login i ważny 2 godziny (odnawiany tokenem odświeżania). Do integracji serwer-serwer użyj zamiast tego klucza API: administrator tworzy go w Ustawienia firmy > API (/company-settings/api), a osoba, której rola na to pozwala, tworzy własne w Profil > Bezpieczeństwo > Klucze API (/profile/api-keys); wysyłaj Authorization: Bearer fmk_... . Klucz działa jako jego właściciel: ma jego uprawnienia i widzi tylko to, co widzi właściciel. WAŻNE: klucz API uwierzytelnia endpoint GraphQL (POST /api/v1/graphql), endpoint przyjmowania danych energetycznych oraz /public-api/{whoami,ping} — NIE uwierzytelnia zasobowych tras REST, które wymagają JWT użytkownika.

Dostępność w pakietach

Limity zapytań

Limit to licznik DZIENNY na firmę, wspólny dla GraphQL i endpointu przyjmowania danych energetycznych, zerowany o 00:00 UTC. Business pozwala na 5000 wywołań dziennie, Enterprise na 100 000. Każda odpowiedź niesie X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset. Nie ma okna minutowego ani nagłówka Retry-After. Na powierzchniach REST odmowa to HTTP 403; w GraphQL status HTTP pozostaje 200 — GraphQL zawsze odpowiada 200 — a odmowa jest w errors[0].extensions.code = FORBIDDEN. Nie sprawdzaj statusu HTTP 403 w GraphQL: czytaj tablicę errors.

Format błędów

Każdy błąd niesie status HTTP, kod czytelny dla maszyny i czytelny komunikat. 4xx to błędy klienta (walidacja, uprawnienia, nie znaleziono); 5xx to błędy serwera, które należy ponawiać z wykładniczym opóźnieniem. W GraphQL kod znajduje się w extensions.code, a wartości, na które można dopasowywać, to: BAD_REQUEST, UNAUTHENTICATED, FORBIDDEN, NOT_FOUND, CONFLICT, BAD_USER_INPUT i TOO_MANY_REQUESTS. Gdy walidacja się nie powiedzie, komunikat wskazuje dokładnie błędne pola — na przykład „quantity must be a number conforming to the specified constraints” — więc nigdy nie musisz zgadywać, które z nich Twój system przesłał źle. Wyszukiwanie, które po prostu niczego nie dopasowało, nie jest błędem: part(barcode:) zwraca null.

Oficjalne SDK i narzędzia

Obecnie nie ma oficjalnego SDK klienta. Endpoint GraphQL ma włączoną introspekcję, więc dowolny klient GraphQL (Apollo, graphql-codegen, Insomnia, Postman) może odkryć schemat, kierując się na POST /api/v1/graphql z Twoim kluczem API. Nie publikujemy obecnie statycznego dokumentu OpenAPI ani pliku SDL pod stałym adresem.

Klucze API nie są dostępne w planach Core i Starter.