Europäische Buchhaltungs-API: USt, E-Rechnung, DSGVO, Hauptbuch

Eine Buchhaltungs-API für Europa muss acht Dinge richtig machen, die eine API für ein einzelnes Land ignorieren kann: Umsatzsteuer, die von Land und Status beider Parteien abhängt, Reverse Charge und der zugehörige Rechnungshinweis, die Prüfung der USt-IdNr. gegen VIES, strukturierte E-Rechnungen im nationalen Format, DSGVO-Pflichten bei Kundendaten, idempotente Schreibvorgänge mit signierten Webhooks, ein echtes doppisches Hauptbuch und Buchführung in mehreren Währungen. Dieser Leitfaden erklärt jede Anforderung und zeigt, wie die API von KRONENWERK darauf abbildet — einschließlich der Stelle, an der die API endet: Sie legt Kunden, Entwürfe und Transaktionen an und liest die Bücher; sie stellt keine Rechnungen, bucht keine Buchungssätze und reicht keine Erklärungen ein.

Umsatzsteuer in mehreren Ländern ist eine Funktion von Fakten, kein Steuersatzfeld

In der EU folgt die umsatzsteuerliche Behandlung eines Verkaufs aus dem Land des Verkäufers, dem Land des Käufers, der Frage, ob der Käufer Unternehmer oder Verbraucher ist, und ob es sich um eine Lieferung oder eine sonstige Leistung handelt. Die Richtlinie 2006/112/EG setzt den Rahmen: Bei B2B-Dienstleistungen liegt der Leistungsort dort, wo der Kunde ansässig ist (Artikel 44); ist der Leistende dort nicht ansässig, schuldet der Kunde die Steuer im Reverse-Charge-Verfahren (Artikel 196); innergemeinschaftliche Lieferungen an ein umsatzsteuerlich registriertes Unternehmen in einem anderen Mitgliedstaat sind bei Erfüllung der Voraussetzungen steuerfrei (Artikel 138); und Artikel 226 listet auf, was eine Rechnung enthalten muss, einschließlich des Hinweises „Steuerschuldnerschaft des Leistungsempfängers“, wo er zutrifft. Steuersätze, Schwellenwerte und Befreiungen sind national.

Die Konsequenz für ein API-Design ist, dass ein Aufrufer nie isoliert nach einem Steuersatz gefragt werden sollte. Eine gut gestaltete europäische API nimmt die Fakten entgegen und liefert ein Urteil — Regelsteuersatz, Nullsatz, steuerfrei, Reverse Charge, nicht steuerbar — mit dem daraus folgenden Satz und Rechnungshinweis, und weigert sich zu raten, wenn ein Fakt fehlt.

KRONENWERK: Jede Rechnung trägt ein Steuerurteil, das aus den Fakten der Transaktion abgeleitet wird (Land des Verkäufers, Land des Käufers, Unternehmen oder Verbraucher, Art der Leistung). Das Urteil ist eines von Regelsteuersatz, Nullsatz, steuerfrei, Reverse Charge, nicht steuerbar oder „Eingabe erforderlich“ / „fachliche Bestätigung erforderlich“, wenn die Fakten es nicht entscheiden. Es wird mit der Rechnung gespeichert und nie später aus Stammdaten hergeleitet. Über die API ist das Urteil kein Feld, das Sie setzen: Ein mit POST /invoices/drafts angelegter Entwurf erbt die Jurisdiktion des Verkäufers, und das Urteil wird festgeschrieben, wenn eine Person die Rechnung im Produkt stellt. Ob eine bestimmte Leistung für eine Befreiung in Frage kommt, ist eine Frage für eine Fachperson, und das Produkt sagt das, statt zu entscheiden.

Reverse Charge braucht beide USt-IdNrn. und den richtigen Hinweis

Eine Reverse-Charge-Rechnung unterscheidet sich an drei Stellen von einer inländischen: Es wird keine Umsatzsteuer berechnet, die USt-IdNr. des Käufers muss neben der des Verkäufers vorhanden sein, und das Dokument muss angeben, dass der Käufer die Steuer schuldet. In den Begriffen der EN 16931 ist die Steuerkategorie AE, ein Befreiungsgrund ist Pflicht, und die Regeln BR-AE-01 bis BR-AE-10 erzwingen die Aufschlüsselung und die Kennungen. Eine strukturierte E-Rechnung mit der falschen Kategorie wird vom Validator des Empfängers abgewiesen; ein PDF mit dem falschen Hinweis ist ein Compliance-Problem für beide Parteien.

KRONENWERK: Lautet das Urteil Reverse Charge, wird die Rechnung mit 0 % USt gestellt, mit Kategorie AE im strukturierten Dokument, der USt-IdNr. des Käufers und dem gesetzlichen Hinweis in der Dokumentsprache. Die API liest das Ergebnis über GET /invoices/{number}, wo tax null ist und net gleich gross. Es gibt keinen API-Parameter, um Reverse Charge zu erzwingen; es folgt aus Land und USt-IdNr. des Kunden, die Sie mit POST /customers übergeben können:

POST https://kronenwerk.org/api/extern/v1/customers
Authorization: Bearer greif_test_XXXXXXXXXXXXXXXX
Idempotency-Key: 6f1c2f4e-3c0a-4b8f-9d61-2a7c1c2e9b10
Content-Type: application/json

{
  "name": "Atelier Dupont SARL",
  "email": "compta@example.fr",
  "street": "12 rue de la Paix",
  "postalCode": "75002",
  "city": "Paris",
  "country": "FR",
  "vatId": "FR12345678901",
  "currency": "EUR"
}

VIES-Prüfung zum richtigen Zeitpunkt

VIES ist das Mehrwertsteuer-Informationsaustauschsystem der Kommission. Sein Webdienst checkVat nimmt Ländercode und Nummer entgegen und liefert zurück, ob die Nummer am Anfragedatum gültig ist, sowie Name und Adresse, soweit der Mitgliedstaat sie offenlegt; checkVatApprox gleicht zusätzlich Unternehmensangaben ab und liefert einen requestIdentifier — die Konsultationsnummer, die die Prüfung dokumentiert. Die Kommission bietet außerdem eine REST-Schnittstelle mit derselben Semantik. Die Backends der Mitgliedstaaten sind gelegentlich nicht erreichbar; in diesem Fall meldet der Dienst einen Status wie MS_UNAVAILABLE statt einer Gültigkeit. Der Dienst existiert für innergemeinschaftliche Umsätze nach der Verordnung (EU) Nr. 904/2010 des Rates.

Daraus folgen zwei Designregeln. Prüfen Sie in dem Moment, in dem die Entscheidung davon abhängt — bei der Rechnungsstellung — und nicht nur beim Anlegen des Kunden, denn Registrierungen erlöschen. Und speichern Sie das Ergebnis beim Dokument, denn die spätere Frage lautet „War sie gültig, als wir fakturiert haben?“, nicht „Ist sie heute gültig?“.

KRONENWERK: Die USt-IdNr. eines Käufers wird bei der Rechnungsstellung gegen VIES geprüft und das Ergebnis zusammen mit dem Urteil bei der Rechnung gespeichert. Antwortet VIES oder das Backend des Mitgliedstaats nicht, wird die Prüfung auf der Rechnung als nicht erreichbar festgehalten und bei der Rechnungsstellung als Hinweis angezeigt; ein Ausfall gilt nie als gültiges Ergebnis und wird nicht zwischengespeichert, während ein echtes Ergebnis einen Tag lang gemerkt wird, damit das Register nicht bei jedem Tastendruck abgefragt wird. Die kostenlose USt-IdNr.-Prüfung führt dieselbe Prüfung für eine einzelne Nummer durch, ohne sie zu speichern. Die API stellt keinen eigenen VIES-Endpunkt bereit; sie stellt das gespeicherte Ergebnis auf der gestellten Rechnung bereit.

Strukturierte E-Rechnungen sind national, nicht europäisch

Die EU-Richtlinie zur elektronischen Rechnungsstellung (2014/55/EU) verpflichtet öffentliche Auftraggeber, Rechnungen nach EN 16931 zu empfangen; B2B-Pflichten sind national und unterscheiden sich in Format, Netzwerk und Zeitplan. Deutschland verpflichtet Unternehmen, strukturierte Rechnungen zu empfangen, und führt die Ausstellungspflicht stufenweise ein (XRechnung oder ZUGFeRD); Belgien schreibt ab dem 1. Januar 2026 Peppol BIS Billing 3.0 über das Peppol-Netzwerk für B2B vor; Polen lässt Rechnungen über KSeF im Format FA(3) freigeben; Frankreich arbeitet mit zugelassenen Plattformen (plateformes agréées), mit Factur-X als einem akzeptierten Format. Kanada und die Vereinigten Staaten haben keine Pflicht zu strukturierten Rechnungen. Siehe den Zeitplan und die Formate.

Für eine API bedeutet das: Das Format ist eine Eigenschaft des Verkäuferlandes und des Kanals des Käufers, entschieden bei der Rechnungsstellung, und das Dokument muss mit den nationalen Artefakten (dem CEN-Schematron plus den Profilregeln) validiert werden, bevor es existiert. Eine API, die beliebiges XML von Aufrufern annähme, müsste es ohnehin validieren und würde den schwierigsten Teil des Problems auf jeden Aufrufer abwälzen.

KRONENWERK: Die strukturierte Datei wird bei der Rechnungsstellung für das Land des Verkäufers erzeugt und validiert — XRechnung und ZUGFeRD (KoSIT-Schematron, gegengeprüft mit Mustang), Factur-X, Peppol BIS UBL, FA(3). Die API legt den Entwurf an; Format, Validierung und Versand sind Sache des Produkts. Das ist die größte ehrliche Lücke für Entwickler, die erwartet hatten, eine Rechnung per POST zu senden und XML zu erhalten: Es gibt keinen „issue“-Endpunkt und kein XML in der API. Die Seite zur E-Rechnungs-API legt genau dar, was verfügbar ist, und der EN-16931-Entwicklerleitfaden behandelt die Regeln, falls Sie Dokumente selbst erzeugen.

DSGVO: Kundendaten sind personenbezogene Daten

Name, Adresse, E-Mail und USt-IdNr. eines Einzelunternehmers sind personenbezogene Daten, also ist eine Buchhaltungsintegration eine Verarbeitungstätigkeit. Die DSGVO verlangt einen Vertrag zwischen Verantwortlichem und Auftragsverarbeiter, der Gegenstand, Dauer, Art, Zweck und Datenkategorien festlegt (Artikel 28 Absatz 3); ein Verzeichnis von Verarbeitungstätigkeiten (Artikel 30); dem Risiko angemessene Sicherheit, gegebenenfalls einschließlich Verschlüsselung (Artikel 32); und für Übermittlungen außerhalb der EU/des EWR einen gültigen Übermittlungsmechanismus (Kapitel V, ab Artikel 44). Was ein Entwickler von einem Buchhaltungsanbieter braucht, ist deshalb konkret: einen Auftragsverarbeitungsvertrag, eine Aussage darüber, wo Daten gespeichert sind und welche Unterauftragsverarbeiter eingesetzt werden, und einen Weg, die Datensätze einer betroffenen Person zu löschen oder zu exportieren.

KRONENWERK: Die Verarbeitungsbedingungen und Hosting-Regelungen sind auf der Datenschutzseite und der Sicherheitsseite dargelegt; lesen Sie diese statt dieses Leitfadens für die verbindliche Aussage. KRONENWERK besitzt keine Sicherheitszertifizierung und erhebt keinen Anspruch „DSGVO-zertifiziert“, weil eine solche Zertifizierung nicht existiert. Über die API sind Schlüssel so gescopt, dass eine Integration, die nur reports:read braucht, überhaupt keine Kundendatensätze erhält, und jeder Schlüssel ist an ein Unternehmen gebunden.

Idempotenz und Webhooks

Netzwerkfehler machen jeden Schreibvorgang mehrdeutig: Ein POST, der in einen Timeout läuft, hat den Datensatz vielleicht angelegt, vielleicht auch nicht. Die Standardantwort ist ein Idempotenzschlüssel — ein vom Client gewählter eindeutiger Wert pro logischer Operation, den der Server mit dem Ergebnis speichert, sodass eine Wiederholung mit demselben Schlüssel dasselbe Ergebnis statt eines Duplikats zurückgibt. Auf der ausgehenden Seite müssen Webhooks signiert sein, damit der Empfänger die Herkunft prüfen kann, eine Ereigniskennung tragen, damit Duplikate verworfen werden können, und bei Fehlern wiederholt werden.

KRONENWERK: Jeder POST verlangt einen Idempotency-Key-Header; eine Wiederholung mit demselben Schlüssel und Body liefert das ursprüngliche Ergebnis, eine Wiederholung mit anderem Body antwortet mit 409 IDEMPOTENZ_KONFLIKT. Fehler sind JSON mit einem Maschinencode und einem Satz: UNAUTHENTICATED, ANFRAGE, PLAN_ERFORDERLICH, KEINE_BERECHTIGUNG, NICHT_GEFUNDEN, IDEMPOTENZ_KONFLIKT, FALSCHER_ZUSTAND, ABGELEHNT, ZU_VIELE_ANFRAGEN. Das Rate-Limit ist ein Budget von 240 Anfragen pro Schlüssel, das kontinuierlich mit etwa zwei pro Sekunde nachgefüllt wird, beantwortet mit 429 und Retry-After. Ausgehende Webhooks sind signiert (KRONENWERK-Signature) und tragen KRONENWERK-Event-Id, KRONENWERK-Event, KRONENWERK-Delivery, KRONENWERK-Attempt und einen Idempotency-Key; Ereignisse sind invoice.issued, invoice.paid, invoice.cancelled, purchase.recorded und payment.recorded; die Zustellung erfolgt nur über HTTPS, wird wiederholt und folgt nie Weiterleitungen. Details: Idempotenz, Webhooks, Fehler, Grenzen.

Das Hauptbuch ist doppisch, und die API liest es

Ein Buchhaltungssystem ist keine Rechnungsliste. Jede Rechnung, Zahlung und Ausgabe erzeugt ausgeglichene Buchungssätze — Forderungen an Umsatzerlöse und Umsatzsteuer; Bank an Forderungen — und die Berichte sind Summen über Konten, nicht über Dokumente. Eine API, die auf einem solchen Hauptbuch aufbaut, kann zusagen, dass „offene Forderungen“ mit dem Forderungskonto abstimmbar ist und dass eine GuV-Zahl erst endgültig ist, wenn die dahinterliegenden Perioden abgeschlossen sind. Eine API auf Basis einer Dokumentliste kann das nicht.

KRONENWERK: Das Hauptbuch ist doppisch mit Perioden, die abgeschlossen werden. Die REST-API liest die offenen Posten mit GET /reports/outstanding; der MCP-Server stellt zusätzlich get_profit_and_loss, get_balance_sheet, list_receivables und list_payables aus demselben Hauptbuch bereit, mit einem is_final-Flag auf der GuV. Nichts in der API bucht einen Buchungssatz; Buchungen entstehen aus Handlungen, die eine Person im Produkt vornimmt — Rechnung stellen, Zahlung erfassen, Eingangsrechnung freigeben. Eine Antwort des Berichts über offene Posten, gekürzt:

{
  "asOf": "2026-09-03",
  "currency": "EUR",
  "booksOpen": true,
  "receivables": { "outstanding": { "minor": 1284050, "currency": "EUR" },
                   "due":         { "minor": 412000,  "currency": "EUR" },
                   "overdue":     { "minor": 105910,  "currency": "EUR" },
                   "count": 9 },
  "payables":    { "outstanding": { "minor": 336000,  "currency": "EUR" },
                   "due":         { "minor": 0,       "currency": "EUR" },
                   "overdue":     { "minor": 0,       "currency": "EUR" },
                   "count": 3 }
}

Währung: kleinste Einheiten, eine Buchwährung, gespeicherte Kurse

Beträge als Gleitkommazahlen verlieren Cents; Beträge als formatierte Zeichenketten sind über Gebietsschemata hinweg mehrdeutig („1.059,10“ gegenüber „1,059.10“). Die robuste Darstellung ist eine ganzzahlige Anzahl kleinster Einheiten mit einem ISO-4217-Code. Ein Unternehmen mit mehreren Währungen fakturiert in der Währung des Kunden, führt seine Bücher in einer Buchwährung und muss den bei jedem Dokument verwendeten Kurs speichern, damit spätere Berichte nicht mit dem heutigen Kurs abdriften.

KRONENWERK: Jeder Betrag in der API ist {"minor": 105910, "currency": "EUR"}, nie eine Dezimalzahl oder eine Zeichenkette. Ein Unternehmen hat eine Buchwährung; Kunden können eine bevorzugte Rechnungswährung haben; die auf einer gestellten Rechnung eingefrorenen Zahlen sind diejenigen, die die API zurückgibt, nicht die heutigen Stammdaten. Konstellationen mit mehreren Unternehmen verwenden einen Schlüssel pro Unternehmen. Siehe mehrere Firmen, mehrere Währungen und die Produktseite zu mehreren Firmen.

Wie KRONENWERK damit umgeht

Mit Einschränkungen unterstützt Die öffentliche API unter https://kronenwerk.org/api/extern/v1 umfasst GET /me, Kunden (GET, GET /{id}, POST), Rechnungen (GET, GET /{number}, POST /invoices/drafts), Transaktionen (GET, POST) und GET /reports/outstanding, mit gescopten Schlüsseln, verpflichtender Idempotenz bei Schreibvorgängen, einem Anfragebudget pro Schlüssel, JSON-Fehlern mit Maschinencodes, signierten Webhooks und einem MCP-Server mit demselben Schlüssel. Die Einschränkungen sind bewusst gewählt und sollten eingeplant werden: Die API legt nur Entwürfe und Transaktionen an — sie stellt keine Rechnungen, erzeugt oder akzeptiert kein strukturiertes XML, bucht keine Buchungssätze, erfasst keine Zahlungen, führt keine VIES-Prüfungen auf Abruf durch und reicht keine Steuer ein oder führt sie ab. Diese Handlungen geschehen im Produkt, wo die Ländermodule sie validieren, und API und Webhooks melden die Ergebnisse. All das ist Teil des Enterprise-Plans; siehe Preise, die Übersicht zur Buchhaltungs-API, den Schnellstart und den Leitfaden zur SaaS-Anbindung.