API und KI-Anbindung

HolidayFlow hat eine dokumentierte REST-Schnittstelle und einen MCP-Server. Damit lässt sich der Urlaubsstand aus einem KI-Assistenten heraus abfragen, ein Antrag anlegen oder ein bestehendes System anbinden – ohne Umweg über die Oberfläche.

Zugang einrichten

Einen Schlüssel erzeugst du in HolidayFlow unter Einstellungen → API-Keys. Er beginnt mit hf_, wird nur einmal angezeigt und ist fest an dein Unternehmen gebunden. Beim Anlegen entscheidest du, ob der Schlüssel nur lesen oder auch schreiben darf.

curl -H "X-API-Key: hf_dein_schluessel" \
  https://imbumkhrjgynzifhxmmr.supabase.co/functions/v1/public-api/v1/me

Anbindung an Claude, ChatGPT und Gemini

Der MCP-Server macht HolidayFlow als Werkzeug in jedem Client verfügbar, der das Model Context Protocol unterstützt. Getestet mit Claude Desktop, Claude Code, ChatGPT Desktop und der Gemini CLI.

In Claude Desktop trägst du dafür Folgendes in die Datei claude_desktop_config.json ein:

{
  "mcpServers": {
    "holidayflow": {
      "command": "npx",
      "args": ["-y", "github:altovate-GmbH/holidayflow#main:mcp-server"],
      "env": {
        "HOLIDAYFLOW_API_KEY": "hf_dein_schluessel"
      }
    }
  }
}

Der Server wird direkt aus dem Repository installiert und beim ersten Start gebaut. Node 20 oder neuer wird vorausgesetzt.

Danach beantwortet der Assistent Fragen wie „Wer ist nächste Woche Donnerstag im Standort Trier nicht da?“ oder „Wie viel Resturlaub hat Anna noch?“ direkt aus deinen Daten.

Endpunkte

Die vollständige Beschreibung mit allen Feldern, Pflichtangaben und zulässigen Werten liegt als OpenAPI-Dokument bereit:

https://imbumkhrjgynzifhxmmr.supabase.co/functions/v1/public-api/openapi.json

Methode	Pfad	Zweck
GET	/v1/me	Unternehmen, Rechte und Standorte des Zugangs
GET	/v1/employees	Mitarbeiter auflisten
GET	/v1/employees/search?q=	Namen in eine Kennung auflösen
POST	/v1/employees	Mitarbeiter anlegen
GET	/v1/availability?date=	Wer fehlt an einem Tag und warum
GET	/v1/leave-requests	Urlaubsanträge, filterbar nach Status
POST	/v1/leave-requests	Urlaubsantrag anlegen
PATCH	/v1/leave-requests/{id}	Genehmigen, ablehnen, stornieren
GET	/v1/leave-accounts	Ansprüche, geplante und verbleibende Tage
GET	/v1/sick-leave	Krankmeldungen
GET	/v1/time-entries	Erfasste Arbeitszeiten
GET	/v1/overtime	Überstunden
GET	/v1/travel-expenses	Reisekosten
GET	/v1/studios	Standorte
GET	/v1/role-types	Zulässige Werte für role_type

Was du wissen solltest

Probelauf: Der Header X-Dry-Run: true validiert eine schreibende Anfrage und gibt die Nutzlast zurück, ohne etwas zu speichern.
Blättern: limit und offset, höchstens 500 Datensätze je Anfrage. Die Gesamtzahl steht in pagination.total.
Grenzen: 300 lesende und 100 schreibende Anfragen je Minute und Schlüssel.
Fehler: immer als { error: { code, message } } mit sprechendem Code.
Standortgrenze: Ein Schlüssel erreicht ausschließlich die Standorte des eigenen Unternehmens. Der Standort eines Datensatzes lässt sich über die API nicht ändern.

Datenschutz bei KI-Anbindungen

Über die Schnittstelle fließen Personaldaten, teilweise Gesundheitsdaten. Wer einen KI-Assistenten anbindet, verarbeitet diese Daten in dessen Umgebung weiter. Das ist zulässig, verlangt aber einen eigenen Auftragsverarbeitungsvertrag mit dem Anbieter des Assistenten und gehört in das Verzeichnis der Verarbeitungstätigkeiten. Der AVV mit uns deckt diesen Teil nicht ab – er kann es nicht, weil wir nicht wissen, welchen Assistenten du einsetzt.

Praktischer Rat: Lege für Assistenten einen eigenen Schlüssel ohne Schreibrecht an. Dann ist der Zugriff jederzeit einzeln widerrufbar, ohne andere Anbindungen zu stören.