Buchhaltungs-API anbinden — Schritt für Schritt

Schritt 1 – Schlüssel unter „KI-Agent & API“ erstellen

Der Schlüssel ist die Eintrittskarte. Sie erzeugen ihn selbst und sehen ihn nur einmal.

• Öffnen Sie in der Buchhaltung Einstellungen → „KI-Agent & API“. Eine Schritt-für-Schritt-Anleitung finden Sie dort unter „KI-Anbindung einrichten“.
• Erzeugen Sie einen neuen Schlüssel und bestätigen Sie das mit Ihrem zweiten Faktor; er beginnt mit jab_live_ und wird nur als Hash gespeichert — kopieren Sie ihn sofort sicher weg.
• Laufzeit wählen: 30 Tage, 90 Tage oder ein Jahr — jeder Schlüssel läuft ab. Widerrufen können Sie ihn jederzeit.
• Zum Erstellen brauchen Sie ein Buchhaltungs- oder EÜR-Abo. Hat die Gesellschaft nur das eingerichtete Steuer-Modul, gibt es den Schlüssel unter Steuern → Einstellungen; er erreicht dann nur die Steuer-Routen (prüfen, vorbereiten, Fristen) und Stammdaten, jede Buchhaltungs-Route antwortet 403. Ist das Modul nicht aktiv oder eine Rechnung überfällig, weist die API Aufrufe ab; die Schlüssel bleiben bestehen und funktionieren wieder, sobald der Zugang aktiv ist.

Schritt 2 – Scope wählen und Basis-Adresse setzen

Erst entscheiden, wie weit der Schlüssel darf, dann die Umgebung vorbereiten.

Wählen Sie read, wenn Ihr Skript nur abrufen und auswerten soll — das ist die sichere Standardwahl zum Ausprobieren. Nehmen Sie write erst dazu, wenn Sie wirklich buchen wollen. Ein read-Schlüssel kann grundsätzlich nicht schreiben.

Setzen Sie Ihre Zugangsdaten als Umgebungsvariablen, damit der Schlüssel nicht in der Befehlszeile kleben bleibt: export BASIS_URL="…" und export SCHLUESSEL="jab_live_…". Die konkrete $BASIS_URL finden Sie im selben Bereich „KI-Agent & API“.

Ein guter erster Test verändert nichts. Deshalb beginnen Sie bewusst mit einem lesenden Aufruf: Er beweist, dass Schlüssel, Header und Adresse zusammenpassen, bevor Sie eine einzige Buchung riskieren. Erst wenn dieser Schritt sauber durchläuft, schalten Sie auf Schreiben um.

Schritt 3 – der erste lesende Aufruf (GET)

Starten Sie mit einem harmlosen Abruf. Wenn hier eine saubere Antwort kommt, stehen Schlüssel und Adresse korrekt.

# Saldenliste eines Geschäftsjahres abrufen (nur read-Scope nötig)
curl -s "$BASIS_URL/saldenliste?fiscal_year_id=<id aus GET /fiscal-years>" \
  -H "Authorization: Bearer jab_live_…"

# Antwort: Konten mit Soll-/Haben-Salden inkl. HGB-Zuordnung

Schritt 4 – der erste schreibende Aufruf (POST)

Klappt der GET, folgt die erste Buchung. Für write-Aufrufe brauchen Sie einen Schlüssel mit write-Scope und den Header Content-Type.

# Ausgangsrechnung anlegen (bucht Erlös + USt + Forderung) — write-Scope
curl -s -X POST "$BASIS_URL/outgoing-invoices" \
  -H "Authorization: Bearer jab_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "fiscal_year_id": "<id aus GET /fiscal-years>",
    "idempotency_key": "<neue UUID, bei Wiederholung dieselbe>",
    "invoice_date": "2025-06-30",
    "service_date": "2025-06-30",
    "recipient": { "name": "Muster GmbH", "address": "Musterstraße 1, 10115 Berlin" },
    "line_items": [{ "description": "Beratung Juni 2025", "quantity": 1, "unit_price": 1000.00, "tax_rate": 19 }]
  }'

Häufige Stolpersteine

Was schiefgeht, geht meist an einer dieser drei Stellen schief.

• 401 Unauthorized: der Header fehlt oder ist falsch. Üblich ist Authorization: Bearer jab_live_…; die API nimmt den Schlüssel auch ohne „Bearer“ oder im Header X-API-Key an. Einen separaten apikey-Header braucht es nicht.
• 403 beim POST: der Schlüssel hat nur read-Scope. Erzeugen Sie einen zweiten Schlüssel mit write-Scope oder nutzen Sie für den ersten Test bewusst nur GET-Aufrufe.
• Storno statt Löschen: eine Buchung wird nie gelöscht. Zum Korrigieren POST /journal-entries/{id}/storno rufen, dann sauber neu buchen — append-only und Festschreibung gelten immer.

Häufige Fragen

Wo erstelle ich den Schlüssel?

In der Buchhaltung unter Einstellungen → „KI-Agent & API“. Dort erzeugen Sie den jab_live_-Schlüssel, wählen Scope und Laufzeit und sehen den Wert genau einmal. Gespeichert wird nur ein Hash.

Welchen Scope soll ich zum Start wählen?

read. Damit können Sie gefahrlos alle Abrufe testen, ohne etwas zu verändern. Erst wenn Ihr Skript wirklich buchen soll, erzeugen Sie zusätzlich einen Schlüssel mit write-Scope.

Warum bekomme ich 401 Unauthorized?

Fast immer wegen des Headers. Üblich ist Authorization: Bearer jab_live_…, ein separater apikey-Header ist nicht nötig. Prüfen Sie außerdem, ob Ihre $BASIS_URL stimmt und der Schlüssel nicht widerrufen oder abgelaufen ist.

Muss ich die Basis-Adresse fest eintragen?

Besser nicht. Legen Sie sie als Umgebungsvariable $BASIS_URL an und referenzieren Sie sie in Ihren Aufrufen. So bleibt der Code sauber und der Schlüssel landet nicht versehentlich in der Befehls-Historie.

Kann ich damit den Jahresabschluss anstoßen?

Nein. Die Endpunkte decken die Buchhaltung ab — Daten und Buchungen. Einen Jahresabschluss, eine E-Bilanz oder eine Steuererklärung erzeugt die Schnittstelle nicht; das übernimmt später das Programm.