Buchhaltungs-API anbinden — Schritt für Schritt

Schritt 1 – Schlüssel im API-Zugang erstellen

Der Schlüssel ist die Eintrittskarte. Du erzeugst ihn selbst und siehst ihn nur einmal.

• Öffne in der Buchhaltung den Bereich API-Zugang (Route /buchhaltung/:entityId/api).
• Erzeuge einen neuen Schlüssel; er beginnt mit jab_live_ und wird nur als Hash gespeichert — kopiere ihn sofort sicher weg.
• Optional die Laufzeit begrenzen: etwa 90 Tage, ein Jahr oder unbefristet. Widerrufen kannst du jederzeit.
• Zum Erstellen brauchst du das gebuchte Buchhaltungs-Modul; bestehende Schlüssel arbeiten weiter, falls ein Abonnement ausläuft.

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

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

Wähle read, wenn dein Skript nur abrufen und auswerten soll — das ist die sichere Standardwahl zum Ausprobieren. Wähle read + write erst, wenn du wirklich buchen willst. Ein read-Schlüssel kann grundsätzlich nicht schreiben.

Setze deine 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 findest du im selben API-Zugang.

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

Schritt 3 – der erste lesende Aufruf (GET)

Starte 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=2025" \
  -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 brauchst du 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 '{
    "kunde": "Muster GmbH",
    "rechnungsdatum": "2025-06-30",
    "netto": 1000.00,
    "steuersatz": 19,
    "leistung": "Beratung Juni 2025"
  }'

Häufige Stolpersteine

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

• 401 Unauthorized: der Header fehlt oder ist falsch. Er muss exakt Authorization: Bearer jab_live_… lauten — kein zusätzlicher apikey-Header.
• 403 beim POST: der Schlüssel hat nur read-Scope. Erzeuge einen zweiten Schlüssel mit write-Scope oder nutze 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 API-Zugang (Route /buchhaltung/:entityId/api). Dort erzeugst du den jab_live_-Schlüssel, wählst Scope und Laufzeit und siehst den Wert genau einmal. Gespeichert wird nur ein Hash.

Welchen Scope soll ich zum Start wählen?

read. Damit kannst du gefahrlos alle Abrufe testen, ohne etwas zu verändern. Erst wenn dein Skript wirklich buchen soll, erzeugst du zusätzlich einen Schlüssel mit read + write.

Warum bekomme ich 401 Unauthorized?

Fast immer wegen des Headers. Er muss Authorization: Bearer jab_live_… lauten, ohne separaten apikey-Header. Prüfe außerdem, ob deine $BASIS_URL stimmt und der Schlüssel nicht widerrufen oder abgelaufen ist.

Muss ich die Basis-Adresse fest eintragen?

Besser nicht. Leg sie als Umgebungsvariable $BASIS_URL an und referenziere sie in deinen 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.