OpenAI Assistants API an die Buchhaltung anbinden

Was Function Calling hier bedeutet

Die Assistants API orchestriert, Ihr Code führt aus. Diese Trennung ist der Kern des Ablaufs — und der Grund, warum Ihr Schlüssel nie das Haus verlässt.

Functions definieren — jede bildet einen Endpunkt ab

Eine Function-Definition ist reines JSON-Schema. Auffällig: Es gibt keinen Firmen-Parameter. Die Gesellschaft wird serverseitig aus dem Schlüssel abgeleitet, ein Schlüssel gehört zu genau einer Firma. So kann der Assistant nie versehentlich die falsche Gesellschaft ansprechen.

{
  "type": "function",
  "function": {
    "name": "saldenliste_abrufen",
    "description": "Liest die Saldenliste der Firma fuer einen Zeitraum.",
    "parameters": {
      "type": "object",
      "properties": {
        "von": { "type": "string", "description": "Startdatum JJJJ-MM-TT" },
        "bis": { "type": "string", "description": "Enddatum JJJJ-MM-TT" }
      },
      "required": ["von", "bis"]
    }
  }
}

// Ausfuehrung im eigenen Tool-Runner (Schluessel bleibt hier):
// GET /saldenliste?von=...&bis=...
// Authorization: Bearer jab_live_...

Die Run-Schleife: requires_action und submit_tool_outputs

Der Ablauf folgt dem Standard der Assistants API. Sie legen einen Thread an, hängen die Nutzerfrage als Nachricht an und starten einen Run, dem Sie Ihre Functions als Werkzeuge mitgeben. Braucht der Assistant Zahlen aus der Buchhaltung, wechselt der Run in den Status requires_action und liefert einen oder mehrere tool_calls mit Function-Namen und Argumenten zurück.

Jetzt ist Ihr Code am Zug: Er liest den tool_call saldenliste_abrufen, ruft den zugehörigen REST-Endpunkt mit dem Bearer-Schlüssel auf und schickt das Ergebnis über submit_tool_outputs in den Run zurück. Kommen mehrere tool_calls in einem einzigen requires_action, sammeln Sie alle Antworten und übergeben sie gebündelt. An OpenAI gehen dabei nur das JSON-Schema Ihrer Functions und die von Ihnen zurückgegebenen Ergebnisse — der Schlüssel selbst wird nie übertragen.

Weil jeder Aufruf synchron durch Ihren Tool-Runner läuft, behalten Sie die volle Kontrolle: Sie können schreibende Aufrufe vor dem Absenden manuell bestätigen lassen, jeden Endpunktaufruf protokollieren oder ihn auf bestimmte Konten und Zeiträume begrenzen, bevor der Assistant seine Antwort mit den echten Zahlen fortsetzt.

14 Werkzeuge, sauber auf Functions abgebildet

Die Buchhaltung stellt 14 Werkzeuge bereit — 10 lesende und 4 schreibende. Sie definieren so viele Functions, wie Ihr Anwendungsfall braucht.

• Lesend (10): Stammdaten, Saldenliste, Buchungsjournal, offene Posten, Ausgangsrechnungen, Eingangsrechnungen, Bankumsätze, Kontenrahmen, BWA und Umsatzsteuer-Kennzahlen.
• Schreibend (4): Buchung anlegen, Buchung stornieren, Ausgangsrechnung erstellen und Eingangsrechnung erfassen.
• Nur lesen gewünscht? Definieren Sie ausschließlich die zehn lesenden Functions und vergeben Sie einen Schlüssel ohne write-Scope — der Assistant kann dann strukturell nichts verändern.
• Jede Function trägt eine klare Beschreibung, damit der Assistant den richtigen Endpunkt trifft, statt einen Aufruf zu improvisieren.

Sicherheit: Scopes, ein Schlüssel je Firma, GoBD

Assistants API oder MCP-Server?

Für die Assistants API ist Function Calling gegen die REST-API der native Weg: Sie definieren die Functions, betreiben die Run-Schleife und behalten den Schlüssel in Ihrem Tool-Runner. Das ist maximal transparent und funktioniert mit jeder OpenAI-SDK-Version, die Function Calling unterstützt.

Alternativ gibt es unseren MCP-Server, der dieselben 14 Werkzeuge als Adapter über die gleiche REST-API bereitstellt — sinnvoll für MCP-native Clients wie Claude Code oder Claude Desktop. Das npm-Paket @jahresabschluss/buchhaltung-mcp ist allerdings noch nicht veröffentlicht; verlässlich ist heute die gehostete URL-Variante. Für ein Assistants-Setup bleiben Sie am besten bei REST plus Function Calling.

Häufige Fragen

Muss ich meinen API-Schlüssel an den Assistant geben?

Nein. Der Bearer-Schlüssel liegt ausschließlich in Ihrem Tool-Runner, also in dem Code, der die Function ausführt. An OpenAI gehen nur die JSON-Schemata Ihrer Functions und die Ergebnisse, die Sie über submit_tool_outputs zurückgeben. Der Schlüssel selbst wird nie an den Assistant oder in einen Prompt übertragen.

Kann der Assistant über die API einen Jahresabschluss oder eine E-Bilanz erstellen?

Nein. Die API ist reine Buchhaltung. Der Assistant kann Belege buchen, Salden und offene Posten lesen oder Rechnungen erstellen — also die Zahlen vorbereiten. Der eigentliche Jahresabschluss, die E-Bilanz oder eine Steuererklärung entstehen nicht über die API, sondern später in der Anwendung selbst, mit Ihrer Freigabe.

Wie viele Functions muss ich definieren?

So viele, wie Ihr Anwendungsfall braucht — maximal 14, passend zu den 14 Werkzeugen (10 lesend, 4 schreibend). Für eine reine Auswertungs-Assistenz genügen die lesenden Functions. Jede Function bildet genau einen festen REST-Endpunkt ab; freie Datenbankzugriffe gibt es bewusst nicht.

Wie stelle ich sicher, dass der Assistant nichts löscht?

Löschen ist gar nicht vorgesehen. Der Buchungskern erzwingt GoBD-Regeln: append-only, Festschreibung, Soll gleich Haben und Storno statt Löschen. Eine falsche Buchung wird also nur durch eine ordentliche Stornobuchung ausgeglichen. Zusätzlich können Sie einen Schlüssel ohne write-Scope vergeben, dann werden schreibende Endpunkte serverseitig komplett abgewiesen.

Woher weiß die API, für welche Firma gebucht werden soll?

Aus dem Schlüssel. Jeder jab_live_-Schlüssel gehört zu genau einer Gesellschaft. Die Firma ist deshalb kein Parameter in Ihren Function-Schemata — der Assistant kann sie weder setzen noch verwechseln. Für mehrere Mandanten legen Sie mehrere Schlüssel an und wählen den passenden im Tool-Runner.

Ist der Assistant Teil Ihrer Software?

Nein. Der Assistant ist Ihr eigenes Werkzeug und läuft in Ihrem OpenAI-Konto. Wir stellen ausschließlich die offene REST-API mit festen Endpunkten, Scopes und GoBD-Sicherheit bereit. Sie könnten dieselbe API genauso gut an einen anderen KI-Agenten anbinden — die Buchhaltung bleibt unverändert.