Claude Code: einen Ordner voller Belege einliefern, prüfen und buchen

Der einfachste Weg: Claude in vier Schritten

Ohne Technikkenntnisse — die technischen Wege stehen weiter unten.

• 1. Claude installieren: Laden Sie die Claude-App für Mac oder Windows von claude.ai/download, installieren Sie sie und melden Sie sich an.
• 2. Schlüssel erstellen: In Ihrer Buchhaltung bei jahresabschluss.io: „KI-Agent & API“ → „Neuer Schlüssel“. Soll Claude buchen, setzen Sie den Haken bei „Buchen“. Erstellen und kopieren — der Schlüssel ist wie ein Passwort für Claude und gilt nur für Ihre Gesellschaft.
• 3. Buchhaltung verbinden: „Buchhaltung für Claude“ herunterladen und die Datei im Ordner „Downloads“ doppelklicken. Claude fragt nach dem Schlüssel: einfügen und auf „Installieren“ klicken. Sonst ist nichts zu installieren.
• 4. Loslegen: Schreiben Sie Claude: „Buche die neuen Belege im Belegeingang.“ Claude fragt um Erlaubnis und bucht dann in Ihrem Journal.

Claude fragt um Erlaubnis, bevor es Ihre Buchhaltung benutzt, und vor Rechnungen, Stornos und dem Festschreiben noch einmal ausdrücklich. Jede Buchung steht im echten Journal — mit denselben Prüfungen wie in der App. Für Technik-Erfahrene gehen auch Claude Code und Codex.

„Buchhaltung für Claude“ herunterladen: https://jahresabschluss.io/downloads/buchhaltung-fuer-claude.mcpb

Warum die Dateien am Modell vorbeigehen

Für einzelne Belege gibt es das Werkzeug upload_receipt. Es erwartet die Datei als Base64-Text im Werkzeugaufruf, und diesen Text schreibt das Modell selbst – bei einer zweiseitigen PDF-Rechnung sind das schnell Zehntausende bis Hunderttausende Zeichen, über den gehosteten Server höchstens rund 7 MB je Datei. Für einen Ordner mit Dutzenden Belegen ist das der umständliche Weg.

Claude Code kann aber Befehle im Terminal ausführen. Damit geht jede Datei per REST-Aufruf als multipart-Upload, bis 20 MB, direkt von Ihrer Festplatte an die Schnittstelle; Claude sieht nur die kurze Antwort je Datei. Das spart Platz im Gespräch und hält den Inhalt der Belege aus dem Verlauf heraus, solange Sie Claude nicht ausdrücklich bitten, eine Datei zu öffnen.

Vorbereitung: Schlüssel und Server-Eintrag

Den Schlüssel legen Sie in der App unter „KI-Agent & API“ → „Neuer Schlüssel“ an, mit Haken bei „Buchen“. Dann im Terminal:

# Schlüssel aus dem Passwortspeicher in die Sitzung holen
export JAB_API_KEY="jab_live_…"

# Buchhaltung als MCP-Server eintragen (nur für Ihren Benutzer)
claude mcp add --transport http buchhaltung --scope user \
  https://api.jahresabschluss.io/functions/v1/bookkeeping-mcp \
  --header "Authorization: Bearer $JAB_API_KEY"

# Prüfen, ob die Verbindung steht
claude mcp list

Die Shell setzt den Wert der Variable beim Hinzufügen ein. Laut Dokumentation von Claude Code steht ein Eintrag mit --scope user danach in ~/.claude.json, privat für Ihr Benutzerkonto und außerhalb des Projekts. Die Projektdatei .mcp.json ist dagegen zum Teilen über die Versionsverwaltung gedacht; legen Sie den Eintrag dort ab, schreiben Sie nur den Verweis ${JAB_API_KEY} in die Kopfzeile. Claude Code setzt den Wert beim Laden aus der Umgebung ein, und der Schlüssel selbst steht in keiner Datei des Projekts.

Das Skript in Etappe 1 liest den Schlüssel aus derselben Umgebungsvariable. In den Chat gehört er nie: Was im Gespräch steht, liegt im Verlauf.

Etappe 1: den Ordner einliefern

Bitten Sie Claude Code, für den Ordner ein Skript wie dieses zu schreiben und auszuführen:

API="https://api.jahresabschluss.io/functions/v1/bookkeeping-api/v1"
for f in belege/2026-10/*.pdf; do
  antwort=$(curl -sS -H "Authorization: Bearer $JAB_API_KEY" \
    -F "file=@$f" "$API/receipts")
  printf '%s\t%s\t%s\n' "$f" \
    "$(jq -r '.outcome // .code // .error' <<<"$antwort")" \
    "$(jq -r '.receipt.id // "-"' <<<"$antwort")"
done | tee einlieferung-2026-10.tsv

• created – neuer Beleg im Belegeingang.
• existing – genau diese Datei war schon da; die Antwort nennt den vorhandenen Beleg, ein zweiter entsteht nicht.
• duplicate – dieselbe Rechnung mit gleicher Nummer, gleichem Partner und gleichem Betrag ist bereits gebucht oder liegt schon im Belegeingang; die Kopie wurde nicht gespeichert.
• not_a_receipt – die Datei wirkt wie ein Logo, eine Signatur oder eine Newsletter-Grafik oder enthält nichts Buchbares; gespeichert wird sie nicht.
• Andere Meldungen nennen den Grund im Klartext, etwa eine Datei über 20 MB oder ein beschädigtes HEIC-Foto.

Claude Code fragt vor Befehlen im Terminal um Erlaubnis, ausgenommen einige eingebaute, nur lesende Befehle; laut Dokumentation gilt eine dauerhafte Freigabe je Projekt und Befehl. Lesen Sie den Befehl vor dem Bestätigen – er enthält die Adresse, an die Ihre Dateien gehen.

Angenommen werden PDF, PNG, JPEG, WebP, E-Rechnungen als XML und HEIC-Fotos, die der Server umwandelt. Je Gesellschaft nimmt die Schnittstelle höchstens 200 Einlieferungen in rollierenden 24 Stunden an, und jeder Schlüssel darf 120 Anfragen pro Minute stellen. Für einen Monatsordner reicht das; ein ganzes Archiv verteilen Sie auf mehrere Tage. Die zweite Spalte der Protokolldatei sagt, was mit jeder Datei geschah:

Etappe 2: Was der Autopilot erledigt hat

Die Belegerkennung braucht nach dem Einliefern einen Moment. Danach fragen Sie Claude Code: „Welche der heute eingelieferten Belege sind gebucht, welche warten auf Prüfung?“ Claude ruft list_receipts mit dem heutigen Datum auf. Jeder Beleg trägt einen Stand: received (eingegangen), processing (wird gelesen), needs_review (wartet auf Sie), booked (gebucht) oder dismissed (abgelegt, etwa eine mögliche Dublette, die die Software mit Begründung zurückgestellt hat; der Grund steht im Feld dismissal_reason).

Was der Autopilot gebucht hat, steht bereits im Journal. Ansehen können Sie es trotzdem: get_receipt nennt zu jedem Beleg die verknüpfte Buchung. Gefällt Ihnen eine Kontierung nicht, wird sie per Storno korrigiert, nicht überschrieben.

PDFs und Fotos zählen auf das monatliche Kontingent der KI-erkannten Belege, E-Rechnungen im XML-Format nicht.

Etappe 3: Vorschläge prüfen und freigeben

Ein Auftrag für alles, was noch offen ist:

Bitte alle Belege aus einlieferung-2026-10.tsv mit Stand needs_review
nehmen, für jeden get_receipt_proposal aufrufen und eine Tabelle zeigen:
Datei, Lieferant, Datum, Brutto, Soll, Haben, Steuerschlüssel,
Sicherheitsstufe, Prüfhinweis.
Nichts buchen, bevor ich Zeilen freigebe. Bei Zweifeln die PDF öffnen
und die Angaben gegenlesen. Mögliche Dubletten nur melden.

Auf Ihre Antwort hin bucht Claude Code mit confirm_receipt – mit der state_version aus dem Vorschlag und einer neuen UUID als idempotency_key, damit eine Wiederholung nach einem Netzwerkfehler nicht doppelt bucht. Korrekturen laufen über das Feld correction mit Begründung. Privates legt dismiss_receipt mit Grund ab; ein Beleg, der zu einer anderen Gesellschaft gehört, wird mit discard_receipt verworfen und bleibt aufbewahrt.

Laut Dokumentation liest Claude Code PDF-Dateien selbst, kurze ganz, längere seitenweise. Öffnet es eine Rechnung zum Gegenlesen, geht ihr Inhalt an das Modell – für einzelne Zweifelsfälle sinnvoll, für den ganzen Ordner unnötig.

Damit Sie nicht jede Leseabfrage bestätigen müssen, erlauben Sie lesende Werkzeuge dauerhaft, etwa mit den Regeln mcp__buchhaltung__list_* und mcp__buchhaltung__get_*. confirm_receipt fragt weiterhin jedes Mal.

Dubletten: was der Server erkennt

Nach dem Lauf: Ordnung im Ordner und im Archiv

Mit der Protokolldatei kann Claude Code die Dateien sortieren, etwa alles mit created, existing oder duplicate nach belege/2026-10/erledigt verschieben und not_a_receipt in einen Ordner zur Durchsicht. Löschen Sie lokale Dateien erst, wenn feststeht, dass der Beleg in der Buchhaltung angekommen ist.

Aufbewahrt wird die eingelieferte Datei in der Buchhaltung: get_receipt_file nennt den Download-Pfad des Originals, get_receipt_archive liefert für ein Geschäftsjahr das Belegarchiv samt GoBD-Datenexport. Die Aufbewahrungspflicht für Buchungsbelege folgt aus § 147 AO; wie Sie mit Papieroriginalen umgehen, klären Sie mit Ihrer Kanzlei.

Grenzen

• Dieser Weg setzt Erfahrung mit dem Terminal voraus. Ohne Technik liefern Sie Belege über den Belegeingang der App oder das E-Mail-Postfach Ihrer Gesellschaft ein.
• Die Belegerkennung schlägt vor; ob Konto und Steuerschlüssel stimmen, entscheiden Sie. Die Verantwortung für die Buchführung bleibt bei Ihrem Unternehmen.
• Bankumsätze, Bankanbindung und Einstellungen der Gesellschaft gehören nicht zu diesem Ablauf.
• Nichts aus diesem Ablauf geht an das Finanzamt; Steuermeldungen übermitteln Sie in der App mit Ihrer PIN.

Häufige Fragen

Kann Claude Code einen ganzen Ordner mit Belegen buchen?

Ja, in drei Etappen: Ein Skript liefert die Dateien per REST an den Belegeingang, der Autopilot bucht eindeutige Belege, und Claude Code bucht den Rest mit confirm_receipt nach Ihrer Freigabe. Gebucht wird im selben Journal wie in der App.

Erkennt der Server doppelte Belege, wenn die Datei anders heißt?

Ja. Maßgeblich ist der Inhalt: Dieselbe Datei hat dieselbe Prüfsumme und ergibt denselben Beleg. Eine andere Datei derselben Rechnung wird nicht gespeichert, wenn die Rechnung schon gebucht ist oder ausgelesen im Belegeingang liegt; spätestens beim Buchen meldet die Prüfung den Verdacht.

Warum nicht einfach upload_receipt für jede Datei?

Weil die Datei dabei als Base64-Text im Werkzeugaufruf steckt, den das Modell schreibt – bei vielen Dateien langsam und über den gehosteten Server auf rund 7 MB je Datei begrenzt. Für einzelne kleine Belege passt upload_receipt, für Ordner ist der REST-Aufruf aus dem Terminal direkter.

Wohin gehört der API-Schlüssel?

In eine Umgebungsvariable wie JAB_API_KEY, aus der das Skript ihn liest. Beim Eintragen mit --scope user setzt die Shell den Wert ein; er steht dann in Ihrer privaten ~/.claude.json, nicht im Projekt. Nie in den Chat und nie im Klartext in eine Datei, die mit dem Projekt geteilt wird; in einer .mcp.json steht nur der Verweis ${JAB_API_KEY}.

Wie viele Belege nimmt die Schnittstelle pro Tag an?

Höchstens 200 Einlieferungen je Gesellschaft in rollierenden 24 Stunden; zusätzlich gilt je Schlüssel eine Grenze von 120 Anfragen pro Minute. Größere Archive verteilen Sie auf mehrere Tage.

Zählen die Belege auf mein Belegkontingent?

PDFs und Fotos, die die Belegerkennung liest, zählen wie im Posteingang auf das monatliche Kontingent der KI-erkannten Belege. E-Rechnungen im XML-Format liest die Software ohne KI.