Accounting per API integrieren

Diese Seite richtet sich an Entwickler, die eigene Clients, Integrationen oder Prüfwerkzeuge an Accounting anbinden. Nach dem Lesen wissen Sie, welche Verträge Sie discovery-first lesen, welche Ressourcen read-only sind und wo mutierende Aktionen über Services oder Worker laufen.

Starten Sie immer mit Discovery und Ressourcen-Meta. Bauen Sie keine Pfade aus Annahmen zusammen, wenn der Server den Einstieg veröffentlicht.

Einstiegspunkte lesen

Nutzen Sie zuerst die allgemeinen Integrationsschritte aus Integration.

Für tenantgebundene Accounting-Ressourcen lesen Sie danach:

nucli --tenant <tenant> resources list
nucli --tenant <tenant> resources meta accounting-journal-entries
nucli --tenant <tenant> resources meta accounting-documents
nucli --tenant <tenant> resources meta accounting-posting-profiles

Die Ressourcen-Meta liefert URLs, Methoden, erlaubte Felder, Default-Sort, Filter und Aktionen. Ihr Client sollte diese Informationen verwenden, statt statische Tabellen oder lokale Feldlisten als Wahrheit zu pflegen.

Ressourcenfamilien

Der Grundschnitt veröffentlicht Accounting-Ressourcen unter /api/v1/accounting/.... Veröffentlicht sind unter anderem:

Behandeln Sie technische IDs als Referenzen. Zeigen Sie Nutzern in eigenen Oberflächen fachliche Labels, Belegreferenzen, Kontonummern oder Zeitraumdaten, wenn die Meta- oder Detailantwort diese Informationen liefert.

Buchungsprofile konfigurieren

Bauen Sie keine festen Kontonummern in Integrationen ein. Automatische Projektionen verwenden postingProfileId und lösen daraus zeitgültige Rollen auf. Der Resolver benötigt ein explizites Buchungsdatum. Fehlende Profile, fehlende Rollen oder fehlende Buchungsdaten sind harte Fehler und dürfen nicht clientseitig durch Ersatzkonten repariert werden.

Für den deutschen Start steht eine sichere Setup-Aktion zur Verfügung:

POST /api/v1/accounting/posting-profiles/ensure-de-skr04-starter

Der Body kann {"setDefault": true} enthalten. Die Aktion legt ein idempotentes Template DE SKR04 Starter 2026 mit Kontenrahmen, Konten, Steuerkennzeichen, Buchungsprofil und Rollen an. Behandeln Sie dieses Template als fachlich zu prüfende Vorlage, nicht als steuerliche Garantie.

Ein aktives Standardprofil ist pro Tenant, Land und Währung eindeutig. Der PostgreSQL-Vertrag erzwingt diese Invariante; Clients sollen Konflikte als Konfigurationsfehler anzeigen.

Buchungen erzeugen

Schreiben Sie Journalbuchungen nicht über rohes CRUD. Nutzen Sie die servicegebundene Aktion:

POST /api/v1/accounting/journal-entries/post

Die Aktion nutzt die Posting-Engine. Sie validiert Tenant, Journal, Periode, Konten, Decimal-Beträge und Soll-/Haben-Gleichheit. Bei Erfolg entstehen gebuchte Journal Entries und Lines. Bei Fehlern muss Ihr Client den Vorgang korrigieren, nicht lokale Fallback-Buchungen erzeugen.

Quellvorgänge projektieren

Der Grundschnitt bucht nicht jede Bestellung selbst. Er bucht die relevanten buchhalterischen Folgeereignisse über Services:

• Ausgangsrechnungen erzeugen Accounting-Beleg, Journalbuchung und Debitoren-OPOS.
• Wareneingänge erzeugen Inventory-Projektionen mit Soll Bestand und Haben WE/RE.
• Eingangsrechnungen erzeugen Kreditorenbuchung, Kreditoren-OPOS, Vorsteuerzeile, WE/RE-Ausgleich und bei Bedarf Preisabweichung. Vorhandene Wareneingangs- und vorherige Eingangsrechnungsprojektionen werden bei der WE/RE-Restermittlung berücksichtigt.
• Inventory-Cost-Events erzeugen Wareneinsatz, Rücklagerung oder Ausschuss.
• Retouren mit Gutschrift erzeugen Erlösschmälerung, Steuerkorrektur und Forderungsausgleich.

Übergeben oder speichern Sie postingProfileId in Ihren fachlichen Projektionsaufrufen. Wenn die Rolle für einen Vorgang fehlt, korrigieren Sie das Buchungsprofil und wiederholen den Servicepfad; schreiben Sie keine Journalzeilen direkt.

Trial Balance lesen

Lesen Sie die erste SuSa-/Trial-Balance-Auswertung über:

GET /api/v1/accounting/reports/trial-balance

Der Aufruf benötigt den Scope accounting_reports:read. Verwenden Sie dateFrom, dateTo, fiscalYearId, periodId und accountId als optionale Filter. Die Antwort enthält Summen und Kontozeilen aus dem Journal; posted und reversed bleiben sichtbar, damit Storno und Gegenbuchung gemeinsam nachvollziehbar sind.

Dashboard lesen

Lesen Sie die operative Accounting-Übersicht über:

GET /api/v1/accounting/reports/dashboard

Der Aufruf benötigt den Scope accounting_reports:read. Die Antwort enthält Dokument-, OPOS-, Bank-, Perioden- und Exportkennzahlen sowie stabile Task-Codes wie accounting.documents.pending. Lokalisieren Sie diese Codes im Client und behandeln Sie die Zahlen als abgeleitete Read-only-Sicht, nicht als eigene fachliche Wahrheit.

Belege und Dateien

Accounting-Belege und Belegdateien sind im Grundschnitt read-only. Ein Client darf nicht versuchen, StorageObject-IDs direkt in Accounting-Dateizeilen zu schreiben. Archivierung, Hashing, Scanstatus, Retention und Kontextbindung bleiben Serviceverantwortung.

Prüfen Sie bei Belegintegrationen:

• Der Upload oder die Dokumenterzeugung liefert ein StorageObject.
• Der fachliche Prozess bindet dieses Objekt über den DocumentService.
• Der Beleg zeigt danach Quelle, Typ, Betrag, Retention und Immutable-Zeitpunkt.
• Die Belegdatei zeigt Rolle, MIME-Typ, Größe und Hash.

Worker starten und überwachen

DATEV, GoBD, Steuerreports, Bankmatching und Drift-Checks laufen über Taskstream. Wenn ein Client solche Läufe starten soll, muss er den vorgesehenen Taskstream- oder Servicevertrag verwenden. Erzeugen Sie keine Exportläufe durch direkte Tabellenmanipulation.

Bekannte Runnables:

• accounting.bank.match_open_items
• accounting.datev.export
• accounting.gobd.export
• accounting.tax_report.prepare
• accounting.drift.check

Verwenden Sie Discovery und Taskstream-Verträge, statt Runnable-Namen lokal abzuleiten.

Payloads müssen tenantgebunden sein. Ein Tenant-Mismatch ist ein harter Fehler. Clients sollten Jobstatus, Fehler und Artefaktreferenzen anzeigen, aber keine rohen Payload-Bytes als Nutzertext rendern.

Steuerprofile international halten

Deutschland ist das erste Steuerreport-Profil. Integrieren Sie trotzdem nicht gegen deutsche Annahmen wie feste UStVA-Felder als einzigen Vertrag. Lesen Sie bei Steuerreport-Läufen immer:

• reportType,
• jurisdictionCountry,
• profileVersion,
• Zeitraum und Geschäftsjahr,
• Hash und Drilldown-Referenzen.

So bleibt Ihr Client für spätere EU- oder Nicht-EU-Profile erweiterbar.

Steuerreports freigeben

Geben Sie vorbereitete Steuerreports über POST /api/v1/accounting/tax-report-runs/{id}/approve frei. Der Aufruf benötigt den Scope accounting_tax_report_runs:approve. Die Antwort enthält den aktualisierten Run mit Status approved, approvedAt und approvedBy.

Behandeln Sie 409 ERR_ACCOUNTING_TAX_REPORT_DRIFT als fachlichen Konflikt. In diesem Fall stimmt der gespeicherte Snapshot nicht mehr mit seinem Hash überein. Bereiten Sie den Steuerreport neu vor, statt die Periode trotzdem zu sperren.

Fehler behandeln

Behandeln Sie Validierungsfehler explizit:

• 400 für ungültige Payloads oder Decimal-Werte,
• 403 für fehlende Scopes,
• 404 für nicht sichtbare oder tenantfremde Referenzen,
• 409 für fachliche Konflikte wie gesperrte Perioden oder doppelte Quellbuchungen.

Zeigen Sie keine rohen SQL- oder Treibertexte an. Nutzen Sie stabile Fehlercodes und eigene i18n-Texte im Client.

Erfolg erkennen

Eine Integration ist belastbar, wenn sie:

• Ressourcen-Meta vor Nutzung liest,
• read-only Ressourcen nicht mutiert,
• Buchungen nur über die Posting-Engine erzeugt,
• Export- und Reportläufe über Worker verfolgt,
• Belege nur über Servicepfade bindet,
• Steuerreports nicht auf ein deutsches Einzelformat verengt.

Nächste Schritte

• Lesen Sie OpenAPI-Grundlagen in OpenAPI verwenden.
• Prüfen Sie Accounting-Betrieb mit Accounting-Betrieb und Compliance.
• Prüfen Sie die Nutzeransicht in Accounting verstehen.