API-Überblick

FreeMaint bietet eine einzige API-Oberfläche für Maschine-zu-Maschine-Integrationen: GraphQL unter /api/v1/graphql. Die REST-Routen, die Sie im Browser sehen, sind die API der Anwendung selbst und werden per Benutzersitzung authentifiziert — ein API-Schlüssel erreicht sie nicht. Planen Sie Ihre Integration auf GraphQL.

REST-API

Die REST-Routen unter /api/v1/{resource} rufen die Web- und Mobil-Apps von FreeMaint auf, authentifiziert per Benutzersitzung (JWT). Ein API-Schlüssel (fmk_...) authentifiziert sie NICHT — er wird nur auf /api/v1/graphql und beim Energie-Ingest akzeptiert. Für eine Integration lesen Sie den GraphQL-Abschnitt weiter unten.

Beispiel (Benutzersitzung, KEIN API-Schlüssel — ein fmk_-Schlüssel authentifiziert diese Route nicht): curl -H 'Authorization: Bearer <session-token>' 'https://freemaint.com/api/v1/work-orders?status=OPEN&assigneeId=42&page=1&pageSize=20'

GraphQL-API

Der GraphQL-Endpunkt ist POST /api/v1/graphql. Er deckt bewusst eine Teilmenge des Produkts ab — Arbeitsaufträge, Anlagen, Maschinenstillstände, Ersatzteile und ihre Bestandsbewegungen, Zähler, Bestellungen, Standorte, Lieferanten, Kunden und Gebäudepläne — nicht die gesamte Anwendung. Nutzen Sie GraphQL, wenn Sie sonst mehrere Endpunkte aufrufen müssten, um einen Bildschirm zusammenzusetzen: etwa eine Kachel, die einen Arbeitsauftrag mit Anlagendetails, verbrauchten Teilen und Gesamtlohnkosten zeigt. Der ERP-Integrationsleitfaden listet auf, was das Schema nicht erreicht.

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

Authentifizierung

Beide APIs akzeptieren ein JWT-Bearer-Token im Authorization-Header, ausgestellt von POST /api/v1/auth/login und 2 Stunden gültig (Erneuerung über das Refresh-Token). Für Server-zu-Server-Integrationen verwenden Sie stattdessen einen API-Schlüssel: Ein Administrator legt ihn unter Firmeneinstellungen > API (/company-settings/api) an, und eine Person, deren Rolle es erlaubt, erstellt ihre eigenen unter Profil > Sicherheit > API-Schlüssel (/profile/api-keys); senden Sie Authorization: Bearer fmk_... . Ein Schlüssel handelt als sein Eigentümer: Er hat dessen Berechtigungen und sieht nur, was dieser sieht. WICHTIG: Ein API-Schlüssel authentifiziert den GraphQL-Endpunkt (POST /api/v1/graphql), den Energie-Ingest-Endpunkt und /public-api/{whoami,ping} — er authentifiziert NICHT die REST-Ressourcenrouten, die ein Benutzer-JWT verlangen.

Verfügbarkeit nach Tarif

Ratenbegrenzungen

Das Kontingent ist ein TÄGLICHER Zähler pro Unternehmen, geteilt zwischen GraphQL und dem Energie-Ingest-Endpunkt, und wird um 00:00 UTC zurückgesetzt. Business erlaubt 5.000 Aufrufe pro Tag, Enterprise 100.000. Jede Antwort trägt X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset. Es gibt kein Minutenfenster und keinen Retry-After-Header. Auf den REST-Oberflächen ist die Ablehnung ein HTTP 403; bei GraphQL bleibt der HTTP-Status 200 — GraphQL antwortet immer mit 200 — und die Ablehnung steht in errors[0].extensions.code = FORBIDDEN. Prüfen Sie bei GraphQL nicht auf HTTP 403, sondern lesen Sie das errors-Array.

Fehlerformat

Jeder Fehler trägt einen HTTP-Status, einen maschinenlesbaren Code und eine lesbare Meldung. 4xx sind Client-Fehler (Validierung, Berechtigung, nicht gefunden); 5xx sind Serverfehler und sollten mit exponentiellem Backoff wiederholt werden. In GraphQL steht der Code in extensions.code; die Werte, auf die Sie prüfen können, sind: BAD_REQUEST, UNAUTHENTICATED, FORBIDDEN, NOT_FOUND, CONFLICT, BAD_USER_INPUT und TOO_MANY_REQUESTS. Schlägt die Validierung fehl, benennt die Meldung genau die fehlerhaften Felder – etwa „quantity must be a number conforming to the specified constraints“ –, Sie müssen also nie raten, welches Ihr System falsch gesendet hat. Eine Suche ohne Treffer ist kein Fehler: part(barcode:) liefert null.

Offizielle SDKs und Werkzeuge

Ein offizielles Client-SDK gibt es derzeit nicht. Der GraphQL-Endpunkt hat Introspection aktiviert, sodass jeder GraphQL-Client (Apollo, graphql-codegen, Insomnia, Postman) das Schema ermitteln kann, indem er mit Ihrem API-Schlüssel auf POST /api/v1/graphql zeigt. Ein statisches OpenAPI-Dokument oder eine SDL-Datei unter einer festen URL veröffentlichen wir aktuell nicht.

API-Schlüssel sind in Core und Starter nicht verfügbar.