Flowyer

Externe KI-Assistenten anbinden

So verbinden Sie ChatGPT, Claude, Gemini, Grok, DeepSeek oder Cursor mit Flowyer, und was ein API-Schlüssel kann und nicht kann.

API-Referenz für Entwickler

Worum geht es?

Mit einem persönlichen API-Schlüssel kann ein externer KI-Assistent in Ihrem Namen Datensätze (Akten, Mandanten, Aufgaben, Zeiteinträge, Kosten und Dokumente) in Flowyer lesen und anlegen und, wo Sie es erlauben, auch ändern. Jede Anfrage läuft genau mit Ihren Berechtigungen, zusätzlich eingeschränkt durch die Freigaben des Schlüssels; von einem Bot angelegte Akten, Mandanten und Aufgaben tragen in den Listen eine kleine Markierung mit dem erstellenden Schlüssel, bei Zeiteinträgen, Kosten und Dokumenten wird der erstellende Schlüssel festgehalten, ist aber nur für einen Kanzlei-Administrator unter "Über die API angelegte Datensätze" sichtbar.

Was ein Schlüssel NICHT kann

Er kann niemals etwas löschen (eine DELETE-Anfrage antwortet immer mit 405).
Er kann einen Datensatz nur über die angebotenen PATCH-Operationen und -Felder ändern, unter Angabe des expected_updated_at des Datensatzes (409 bei Konflikt); sonst wird nichts überschrieben.
Er kann Dokumentinhalte nur mit der eigenen Download-Berechtigung (documents:download) über den kurzlebigen signierten Link von documents.download herunterladen; einen anderen Zugriff auf die Dateien hat er nicht.
Er sieht nie mehr als Sie: Aktensperren und Modulberechtigungen gelten unverändert.

API-Schlüssel anlegen

Ein Kanzlei-Administrator schaltet den API-Zugang unter Einstellungen > API-Schlüssel für die Kanzlei frei (standardmäßig aus).
Auf derselben Seite legen Sie einen Schlüssel an: geben Sie ihm einen Namen (z. B. "ChatGPT"), damit Sie später wissen, welcher Bot zu welchem Schlüssel gehört.
Wählen Sie, was der Bot darf (lesen, anlegen oder ändern), und setzen Sie ein Ablaufdatum. Die Berechtigungen eines Schlüssels lassen sich später nicht ändern: Wird mehr benötigt, legen Sie einen neuen Schlüssel an.
Der Schlüssel wird nur einmal angezeigt: kopieren Sie ihn in die Einstellungen des Assistenten. Sie können ihn jederzeit mit sofortiger Wirkung widerrufen.

Geben Sie jedem Bot einen eigenen Schlüssel. So lassen sie sich getrennt widerrufen, und die Akten-, Mandanten- und Aufgabenlisten zeigen, welcher einen Datensatz angelegt hat.

Verfügbare Berechtigungen

matters:read Akten lesen
matters:create Akten anlegen
matters:update Akten ändern
clients:read Mandanten lesen
clients:create Mandanten anlegen
clients:update Mandanten ändern
tasks:read Aufgaben lesen
tasks:create Aufgaben anlegen
tasks:update Aufgaben ändern
workhours:read Zeiteinträge lesen
workhours:create Zeiteintrag erfassen
workhours:update Zeiteintrag ändern
costs:read Kosten lesen
costs:create Kosten erfassen
costs:update Kosten ändern
invoices:read Rechnungen lesen
documents:read Dokumente auflisten (nur Metadaten, kein Download)
documents:download Dokumente herunterladen (vollständiger Inhalt)
documents:create Dokument hochladen
documents:update Dokument umbenennen
colleagues:read Kollegen auflisten (nur Namen)
knowledge:read Wissensdatenbank lesen
knowledge:create Wissensdatenbank-Einträge erstellen
knowledge:update Wissensdatenbank-Einträge bearbeiten
emails:read E-Mails von Akten lesen
litigation:read Prozessverlauf auflisten
litigation:create Prozessverlaufseintrag anlegen
litigation:update Prozessverlaufseintrag ändern
mail_register:read Postbuch lesen
mail_register:create Postbuch-Eintrag anlegen
mail_register:update Postbuch-Eintrag ändern
comments:read Fallkommentare lesen
comments:create Fallkommentare schreiben
comments:update Eigene Fallkommentare bearbeiten
trials:read Verhandlungen lesen
trials:create Verhandlung anlegen
trials:update Verhandlung ändern
courts:read Gerichte auflisten
hr:read Abwesenheiten lesen (nur Daten)
calendar:read Kalendereinträge lesen
calendar:create Kalendereinträge erstellen
calendar:update Kalendereinträge ändern
bookings:read Terminbuchungen ansehen
bookings:create Terminbuchung erstellen (sendet dem Mandanten eine E-Mail)
bookings:update Buchungen verschieben und bearbeiten
bookings:send Buchungen bestätigen oder stornieren (sendet dem Mandanten eine E-Mail)
tickets:read Support-Tickets lesen
tickets:reply Auf Tickets antworten (sendet eine E-Mail an den Mandanten)
tickets:update Ticketstatus ändern
portal:read Mandantenportal: Threads und Nachrichten lesen
portal:reply Mandantenportal: dem Mandanten antworten (sendet eine Nachricht und eine Benachrichtigungs-E-Mail)

Anbindung

Verwenden Sie immer genau den https-Host mit www. am Anfang (eine Weiterleitung würde den Autorisierungs-Header verwerfen). Bei Verbindungen mit API-Schlüssel senden Sie den Schlüssel als "Authorization: Bearer <Schlüssel>"; MCP-Clients authentifizieren sich stattdessen per OAuth über die Anmeldung im Browser, ein Schlüssel muss nicht eingegeben werden.

Basis-URL: https://www.flowyer.de/api/agent
OpenAPI: https://www.flowyer.de/api/agent/openapi.json
MCP: https://mcp.flowyer.com/mcp

ChatGPT (Actions)

Importieren Sie in einem eigenen GPT unter Actions die untenstehende OpenAPI-Beschreibung, wählen Sie API-Schlüssel-Authentifizierung vom Typ "Bearer" und fügen Sie Ihren Flowyer-Schlüssel ein.

https://www.flowyer.de/api/agent/openapi.json

Grok

Geben Sie Grok die Adresse der OpenAPI-Beschreibung und den Schlüssel; aus der Beschreibung erfährt es, welche Operationen es gibt und welche Parameter sie erwarten.

Claude Code

Claude Code verbindet sich mit dem MCP-Server; bei der ersten Nutzung meldet es Sie im Browser an (OAuth), ein Schlüssel ist nicht nötig:

claude mcp add --transport http flowyer https://mcp.flowyer.com/mcp

Claude Desktop / Cursor / Gemini CLI / DeepSeek

Claude Desktop, Cursor, die Gemini-CLI und MCP-Clients auf DeepSeek-Basis erwarten dieselbe MCP-Adresse in ihrer Konfigurationsdatei; bei der ersten Verbindung meldet der Client Sie im Browser an (OAuth), ein Schlüssel muss nicht eingegeben werden:

{
  "mcpServers": {
    "flowyer": {
      "url": "https://mcp.flowyer.com/mcp"
    }
  }
}

REST (curl)

Beispiele für direkte REST-Aufrufe:

curl -H "Authorization: Bearer flw_..." https://www.flowyer.de/api/agent/me
curl -H "Authorization: Bearer flw_..." "https://www.flowyer.de/api/agent/matters?q=2026/0025"
curl -X POST -H "Authorization: Bearer flw_..." -H "Content-Type: application/json" \
     -H "Idempotency-Key: 7f3a9c21-1b2c-4d5e-8f90-0a1b2c3d4e5f" \
     -d '{"name":"Kovács Kft.","email":"info@kovacs.hu"}' https://www.flowyer.de/api/agent/clients

Regeln

Sichere Wiederholungen (Idempotency-Key)

Jedes Anlegen akzeptiert einen Idempotency-Key-Header (oder ein Feld idempotency_key): eine mit demselben Wert wiederholte Anfrage liefert denselben Datensatz zurück, statt einen weiteren anzulegen, und unterschiedliche Schlüssel legen immer getrennte Datensätze an. Ohne Schlüssel gilt: ein identisches Anlegen innerhalb von 120 Sekunden liefert den ersten Datensatz.

Fehler

Jeder Fehler hat dieselbe Form: ein Maschinencode (error), eine englische Meldung (message) und die Meldung in der Kanzleisprache (message_localized). Die Meldung sagt, was zu tun ist. Bei 401, 403, 404 und 422 ist es sinnlos, die unveränderte Anfrage zu wiederholen, mit zwei Ausnahmen: bei 404 upload_not_finished schließen Sie zuerst den Upload zur upload_url ab und rufen dann complete erneut auf; bei einem abgelaufenen OAuth-Zugriffstoken (401 expired_key) erneuern Sie zuerst das Token.

{
  "error": "scope_missing",
  "message": "This API key does not have the \"clients:create\" permission. ...",
  "message_localized": "Ehhez az API-kulcshoz nem tartozik \"clients:create\" jogosultság. ...",
  "locale": "hu",
  "details": { "required_scope": "clients:create" }
}

HTTP	error	Bedeutung
400	invalid_json, use_www_host, bad_request	Fehlerhafte Anfrage: ungültiger JSON-Text, falscher Host (verwenden Sie den www.-Host) oder eine nicht lesbare Anfrage.
401	missing_key, invalid_key, revoked_key, expired_key, user_inactive, office_not_found	Der Schlüssel fehlt, ist ungültig, widerrufen oder abgelaufen, sein Inhaber ist nicht mehr aktiv, oder die Kanzlei des Schlüssels wurde nicht gefunden.
403	scope_missing, module_forbidden, forbidden, office_api_disabled, licence_expired, office_archived	Eine Berechtigung fehlt beim Schlüssel oder beim Benutzer, oder die Kanzlei hat die API nicht freigeschaltet.
404	not_found, matter_not_visible, unknown_endpoint, upload_not_finished, replay_not_visible	Der Datensatz existiert nicht oder der Benutzer darf ihn nicht sehen; unbekannter Endpunkt; die hochgeladene Datei ist noch nicht im Speicher angekommen (upload_not_finished: laden Sie sie zur upload_url hoch und rufen Sie dann complete erneut auf); oder eine wiederholte Anlage, deren Datensatz bereits angelegt, inzwischen aber gelöscht oder verborgen wurde (replay_not_visible: es wurde nichts Neues angelegt, legen Sie ihn nicht erneut an).
405	delete_not_allowed, update_not_allowed, method_not_allowed	Löschen ist über die API nicht möglich; Ändern nur dort, wo die Beschreibung eine PATCH-Operation anbietet.
409	client_exists, client_exists_generic, idempotency_key_reused, duplicate_in_progress, record_conflict, record_locked, duplicate_name	Ein Mandant mit diesem Namen existiert bereits; im Ordner existiert bereits ein Dokument mit diesem Namen (duplicate_name); der Datensatz wurde seit dem Lesen geändert (record_conflict: lesen Sie ihn erneut und senden Sie die Änderung mit dem neuen updated_at erneut); der Datensatz ist abgerechnet oder gesperrt (record_locked: nehmen Sie die Änderung in Flowyer vor); der Idempotency-Key wurde für eine andere Ressource verwendet; oder eine identische Anfrage wird gerade verarbeitet.
413	request_too_large, file_too_large	Der Anfragetext ist zu groß (request_too_large), oder die hochzuladende Datei überschreitet die Grenze (file_too_large; details.max nennt die Grenze in Byte).
422	validation_failed, unknown_client, unknown_colleague, blocked_file_type, upload_token_invalid, folder_not_in_matter, document_name_too_long	Ein ungültiges oder fehlendes Feld (details.fields zeigt welches); ein ungültiges, bereits verwendetes oder abgelaufenes Upload-Token (upload_token_invalid: starten Sie den Upload erneut); oder ein Ordner, der nicht zur Akte gehört (folder_not_in_matter).
429	rate_limited, auth_rate_limited	Zu viele Anfragen (300 pro Minute und Schlüssel); der Retry-After-Header sagt, wann Sie es erneut versuchen können.
500	server_error	Unerwarteter Fehler. Die Anfrage wurde unter ihrer request_id protokolliert; versuchen Sie es später erneut und nennen Sie bei Wiederholung diese ID dem Flowyer-Support.
503	office_maintenance, office_setup_incomplete, temporarily_unavailable	Die Kanzlei ist vorübergehend nicht verfügbar (Wartung oder laufende Einrichtung); der Retry-After-Header sagt, wann Sie es erneut versuchen können.

Datenschutz

Der Anbieter des Assistenten (z. B. OpenAI, Anthropic, xAI) sieht alle Daten, die der Schlüssel zurückgibt. Geben Sie nur einem Bot einen Schlüssel, dessen Datenverarbeitung die Kanzlei akzeptiert hat, und nur mit den wirklich nötigen Berechtigungen.