App mit Buchhaltungssoftware verbinden: CSV, Integrationen, API, MCP

Es gibt vier Wege, Daten aus Ihrer Anwendung in eine Buchhaltungssoftware zu bringen: eine CSV-Datei exportieren und importieren, eine native Integration des Anbieters nutzen, eine öffentliche API aus eigenem Code aufrufen oder einen KI-Assistenten über einen MCP-Server arbeiten lassen. Für alles, was täglich läuft, ist die API die ehrliche Wahl, und eine gute API-Anbindung läuft auf fünf Entscheidungen hinaus: was synchronisiert wird, in welche Richtung, wie Wiederholungen sicher werden (Idempotenz), wie Sie von Änderungen erfahren (Webhooks) und wo der Schlüssel liegt.

Die vier Optionen, und wann welche ausreicht

CSV reicht für eine vierteljährliche Übergabe an die Steuerberatung. Eine native Integration reicht, wenn die beiden Produkte, die Sie nutzen, zufällig die beiden Produkte sind, die der Anbieter verbunden hat. Eine API brauchen Sie, wenn die Daten in Ihrem eigenen System entstehen und vollständig, jeden Tag und ohne Mensch in der Schleife ankommen müssen. MCP ist eine fünfte Schicht über der API für Menschen, die einem Assistenten Fragen stellen, statt Code zu schreiben.

Die Optionen schließen einander nicht aus. Eine verbreitete Konstellation ist die API für den täglichen Fluss, MCP für die Gründerin, die fragt „Wer hat noch nicht bezahlt?“, und ein CSV-Export zum Jahresende für die Software der Steuerberatung.

Was synchronisiert wird: Kunden, Rechnungen, Zahlungen — in dieser Reihenfolge

Synchronisieren Sie die Objekte, die das Hauptbuch braucht, um eine korrekte Rechnung zu erzeugen und eine Zahlung zuzuordnen, und nichts darüber hinaus. In der Praxis sind das drei Objekte mit einer Abhängigkeit untereinander: Ein Kunde muss existieren, bevor eine Rechnung auf ihn verweisen kann, und eine Rechnung muss existieren, bevor eine Zahlung sie ausgleichen kann.

Kunden

Name, Adresse, Land, USt-IdNr., Unternehmen oder Verbraucher sowie Ihre eigene externe Kennung. Land und Umsatzsteuerstatus entscheiden über die steuerliche Behandlung; erfassen Sie beides korrekt beim Anlegen, nicht erst auf der Rechnung.

Rechnungen

Positionen mit Beschreibung, Menge, Einzelpreis und Art der Leistung; die Währung; das Fälligkeitsdatum; ein Verweis auf Ihre Bestellung oder Ihr Abonnement. Senden Sie keinen Steuersatz — senden Sie die Fakten und lassen Sie das Hauptbuch entscheiden, sonst implementieren Sie das Umsatzsteuerrecht in Ihrer App ein zweites Mal.

Zahlungen

Betrag, Datum, Währung und die Rechnung oder Rechnungen, die ausgeglichen werden. Ist ein Zahlungsdienstleister beteiligt, ist dessen Transaktions-ID der Schlüssel, über den später die Auszahlung abgestimmt wird.

Die Richtung ist entscheidend. Kunden und Rechnungen fließen in der Regel aus Ihrer App ins Hauptbuch. Der Zahlungsstatus fließt oft zurück — das Hauptbuch sieht den Bankfeed, Ihre App will wissen, dass die Rechnung bezahlt ist. Berichte (offene Forderungen, Gewinn und Verlust) fließen ausschließlich zurück. Legen Sie pro Objekt fest, welches System die maßgebliche Quelle ist, und schreiben Sie dasselbe Feld nie von beiden Seiten.

Was nicht synchronisiert werden sollte: die internen Ereignisse Ihres Produkts (Logins, Funktionsnutzung), Bestellentwürfe, die vielleicht nie fakturiert werden, und alles, womit das Hauptbuch nichts anfangen kann. Jedes Objekt, das Sie übertragen, müssen Sie anschließend konsistent halten.

Idempotenz: die Antwort, die nie ankommt

Eine Verbindung bricht ab, nachdem das Hauptbuch den Kunden angelegt hat, aber bevor Ihre App die Antwort erhalten hat. Ohne Schutz verlieren Sie den Datensatz oder legen ihn doppelt an, und ein doppelter Kunde fällt Wochen später auf, wenn eine Rechnung bei der falschen Kopie landet. Die Lösung ist ein Idempotenzschlüssel: ein Wert, den Sie pro beabsichtigtem Schreibvorgang wählen und in einem Header senden, damit der Server eine Wiederholung erkennt.

Der Internet-Draft der IETF für den Header nennt den Zweck unmissverständlich: „The HTTP Idempotency-Key request header field can be used to make non-idempotent HTTP methods such as POST or PATCH fault-tolerant.“ Der Entwurf ist abgelaufen, ohne RFC zu werden, aber das Muster ist Branchenkonvention und der Header-Name ist der, den die meisten APIs verwenden. Die Regeln, die es serverseitig funktionieren lassen:

1. Die erste Anfrage unter einem Schlüssel erledigt die Arbeit und speichert das Ergebnis.
2. Eine Wiederholung mit demselben Schlüssel und demselben Body liefert das gespeicherte Ergebnis — denselben Datensatz, keinen neuen.
3. Eine Wiederholung mit demselben Schlüssel und einem anderen Body wird abgewiesen, weil ein Schlüssel für genau eine Absicht steht.
4. Schlüssel laufen nach einem Zeitfenster ab; danach zählt der Wert als neue Arbeit.

Auf der Client-Seite: Erzeugen Sie den Schlüssel, wenn die Absicht entsteht (eine UUID, die mit Ihrer eigenen Bestellzeile gespeichert wird), nicht beim Absenden der Anfrage, damit eine Wiederholung nach einem Absturz ihn wiederverwendet. Wiederholen Sie mit Backoff bei Netzwerkfehlern und bei 5xx; wiederholen Sie nicht bei 4xx, außer bei 429.

Webhooks: von Änderungen erfahren, ohne zu pollen

Ein Webhook ist eine HTTP-Anfrage, die die Buchhaltungssoftware an Ihre URL sendet, wenn etwas passiert — eine Rechnung wurde gestellt, eine Zahlung wurde erfasst. Er ersetzt das Polling, bringt aber drei Pflichten mit: die Signatur prüfen, mit Duplikaten rechnen und schnell antworten.

Die Anleitung von Stripe ist die Referenz, die die meisten Entwickler kennen, und sie gilt für jeden Anbieter: „Always verify that webhook events originate from Stripe before acting on them“; „webhook endpoints might occasionally receive the same event more than once“, wogegen man sich schützt, indem man „the event IDs you've processed“ protokolliert; und der Endpunkt „must quickly return a successful status code (2xx) before any complex logic that could cause a timeout“. Stripe weist außerdem darauf hin, dass es „doesn't guarantee the delivery of events in the order that they're generated“ — behandeln Sie jedes Ereignis also als Zeiger und holen Sie den aktuellen Zustand ab, wenn die Reihenfolge eine Rolle spielt.

Die Signaturprüfung folgt im Allgemeinen einem Muster: ein Header mit Zeitstempel und einem HMAC über timestamp.raw_body; ablehnen, wenn der Zeitstempel außerhalb eines Toleranzfensters liegt (Replay-Schutz), den HMAC mit dem Endpunkt-Secret über die Rohbytes neu berechnen und in konstanter Zeit vergleichen. Frameworks, die JSON parsen und neu serialisieren, bevor Sie den Body lesen können, brechen dieses Verfahren; lesen Sie den Roh-Body.

Den Schlüssel sicher aufbewahren

Ein API-Schlüssel für die Buchhaltung kann jeden Kunden und jede Rechnung des Unternehmens lesen und Entwürfe anlegen. Behandeln Sie ihn wie ein Datenbankpasswort: in einem Secrets-Manager oder einer Umgebungsvariable speichern, nie in der Versionsverwaltung oder in einer Mobil-App, und nur die Scopes vergeben, die die Integration nutzt.

• Minimaler Scope. Ein Dashboard, das nur Forderungen liest, braucht einen Lese-Scope, keinen Schreib-Scope. Lesen und Schreiben sind getrennte Berechtigungen.
• Ein Schlüssel pro Integration. Damit einer widerrufen werden kann, ohne die anderen zu brechen, und damit der Prüfpfad zeigt, welches System was getan hat.
• Testschlüssel im Test, Live-Schlüssel in der Produktion. Das Präfix des Schlüssels sollte die Umgebung in einer Log-Zeile sofort erkennbar machen.
• Rotation. Ein Anbieter, der nur einen Hash des Schlüssels speichert, kann ihn Ihnen nicht erneut anzeigen — und das ist das richtige Design. Planen Sie die Rotation von Anfang an: neuen Schlüssel ausstellen, umschalten, alten widerrufen.
• Webhook-Secrets sind ebenfalls Schlüssel. Gleiche Aufbewahrung, gleiche Rotation.

Die MCP-Spezifikation ergänzt einen Punkt zu Assistenten: „Hosts must obtain explicit user consent before invoking any tool“, und Tools „represent arbitrary code execution and must be treated with appropriate caution“. Ein MCP-Server vor einem Buchhaltungs-Hauptbuch sollte deshalb Lesezugriffe und Vorbereitung bereitstellen, keine unumkehrbaren Aktionen, und die Person an der Tastatur bleibt verantwortlich.

Wie KRONENWERK damit umgeht

KRONENWERK bietet alle vier Wege; API, Webhooks, MCP-Server und Integrationsverzeichnis sind Teil des Enterprise-Plans (siehe Pläne). Mit Einschränkungen unterstützt

• API. https://kronenwerk.org/api/extern/v1, Bearer-API-Schlüssel mit Präfix greif_live_ oder greif_test_, Scopes wie customers:write, invoices:write, transactions:write und reports:read. Endpunkte für Kunden (GET/POST /customers), Rechnungen (GET /invoices, POST /invoices/drafts), Transaktionen (GET/POST /transactions) und GET /reports/outstanding. Ein Unternehmen pro Schlüssel; GET /me nennt es. KRONENWERK speichert nur einen Hash des Schlüssels; Schlüssel werden auf der Entwicklerseite widerrufen oder rotiert.
• Idempotenz. Idempotency-Key ist bei jedem POST Pflicht. Gleicher Schlüssel und Body: derselbe Datensatz kommt zurück; gleicher Schlüssel und anderer Body: abgewiesen; Schlüssel gelten 24 Stunden. Details unter Idempotenz.
• Webhooks. Ereignisse invoice.issued, invoice.paid, invoice.cancelled, purchase.recorded, payment.recorded. Jede Zustellung trägt KRONENWERK-Signature (t=<unix seconds>,v1=<hex HMAC-SHA256 over t.raw_body>, 5 Minuten Toleranz), KRONENWERK-Event-Id, KRONENWERK-Event, KRONENWERK-Delivery, KRONENWERK-Attempt und einen Idempotency-Key zur Deduplizierung. Nur HTTPS, Wiederholungen bis zur Annahme, Weiterleitungen werden nicht gefolgt. Siehe Webhooks.
• MCP. Ein Server unter /api/extern/mcp (Streamable HTTP, gleicher Schlüssel) mit Lese-Tools wie list_receivables und get_profit_and_loss sowie Entwurfs-Tools create_invoice_draft, create_transaction, add_transaction_note. Kein Tool stellt eine Rechnung, versendet E-Mails, bewegt Geld oder ändert Einstellungen.
• Rate-Limit. Ein Budget von 240 Anfragen pro Schlüssel, das kontinuierlich nachgefüllt wird (etwa zwei pro Sekunde); 429 mit Retry-After bei Überschreitung.

POST /api/extern/v1/customers HTTP/1.1
Host: kronenwerk.org
Authorization: Bearer greif_test_…
Idempotency-Key: 6f1c2a8e-4b3d-4a21-9d77-0c5e1f9b2a44
Content-Type: application/json

{"name": "Example SRL", "country": "BE", "vatId": "BE0123456789", "email": "ap@example.be"}

Ein durchgerechnetes Beispiel der drei Flüsse finden Sie unter SaaS an die Buchhaltung anbinden; die vollständige Oberfläche beschreibt die Seite Buchhaltungs-API und die Referenz.