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
nucli --tenant <tenant> resources meta accounting-export-profiles
nucli --tenant <tenant> resources meta accounting-account-export-mappings
nucli --tenant <tenant> resources meta accounting-commerce-invoice-projections

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 Commerce-Rechnungen bleibt commerceInvoicePostingMode=manual der Standard. automatic benötigt commerceInvoiceAutomaticFrom. Behandeln Sie diesen Zeitstempel als Cutover: Nur danach finalisierte Rechnungen erzeugen einen persistenten Automatiklauf; Integrationen dürfen ältere Rechnungen nicht selbst als Automatikbestand nachliefern.

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.

Exportprofile und externe Kontonummern konfigurieren

Speichern Sie keine providerbezogene oder allgemeine externe Kontonummer am Accounting-Konto. Der Ressourcenvertrag accounts enthält bewusst weder datevAccountNo noch ein Ersatzfeld wie externalAccount. Verwenden Sie stattdessen:

/api/v1/accounting/export-profiles
/api/v1/accounting/account-export-mappings

Ein Exportprofil benennt mit adapterKey den code-owned Adapter und legt jurisdictionCountry, profileVersion, Gültigkeit und accountMappingPolicy fest. Derzeit ist datev als Adapter implementiert. Der Server akzeptiert nur Kombinationen aus Adapter, Rechtsraum und Version, die in der code-owned Jurisdiction Profile Registry registriert sind; initial ist das datev/DE/2026. Die Policy internal_account_number verwendet ausdrücklich die interne Kontonummer. Die Policy explicit_mapping verlangt für jedes exportierte Konto genau eine gültige Zuordnung mit exportProfileId, accountId, externalAccountNumber, validFrom und optional validTo.

Konto, Profil und Zuordnung müssen demselben Tenant gehören. Der Server lehnt überlappende Intervalle ab und löst Zuordnungen anhand des Buchungsdatums auf. validFrom und validTo sind inklusive Date-only-Grenzen. Senden Sie sie als UTC-normalisierte Datumswerte; Uhrzeitanteile werden nicht als Teil des fachlichen Vertrags gespeichert. Adapterregeln gelten schon beim Schreiben einer Zuordnung, für DATEV insbesondere die Höchstlänge von 40 Zeichen. Clients dürfen fehlende oder mehrdeutige Zuordnungen nicht durch eine lokale Kontonummer ersetzen.

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.

Commerce-Ausgangsrechnungen

Für Commerce-Ausgangsrechnungen veröffentlicht Accounting einen geschützten Projektionsvertrag:

GET /api/v1/accounting/commerce-invoice-projections/-/readiness?invoiceId=<uuid>
POST /api/v1/accounting/commerce-invoice-projections/project
POST /api/v1/accounting/commerce-invoice-projections/{id}/reverse

Der Readiness-Endpunkt benötigt accounting_commerce_invoice_projections:read und verändert keine Daten. project benötigt accounting_commerce_invoice_projections:project; reverse benötigt accounting_commerce_invoice_projections:reverse.

project erwartet mindestens invoiceId. Optional kann der Client postingProfileId, fiscalYearId, periodId und journalId übergeben. Ohne explizite Ziele löst der Server nur eindeutige Defaults auf: genau ein aktives Standard-Buchungsprofil für Land, Währung und Rechnungsdatum, eine Forderungsrolle, passende Steuerbehandlungs-Mappings, ein offenes Geschäftsjahr, eine offene Periode und ein Journal. Mehrdeutige oder fehlende Konfiguration liefert 409 ERR_ACCOUNTING_COMMERCE_INVOICE_PROJECTION_NOT_READY mit stabilen Readiness-Codes.

Der Vertrag ist idempotent. Ist eine Rechnung bereits projiziert, liefert der Server die vorhandene Projektion und erzeugt keine zweite Buchung. Clients sollen reasonKey und code lokalisieren und keine rohen Fehlertexte, SQL-Details oder Tabellennamen anzeigen.

Jede neue Rechnungsposition benötigt einen Bestellpositionsbezug und genau einen vollständigen Steuer-Snapshot mit taxCode, taxRate, taxType, taxRegimeKey, taxLiability und amount. Der Server prüft Snapshot und Rechnungssummen beim Finalisieren. Clients dürfen fehlende Steuerfelder nicht mit DOMESTIC, standard oder anderen Defaults ergänzen.

Automatikläufe lesen und wiederholen Sie über:

GET  /api/v1/accounting/commerce-invoice-automation-runs
GET  /api/v1/accounting/commerce-invoice-automation-runs/{id}
POST /api/v1/accounting/commerce-invoice-automation-runs/{id}/retry

Eine fachlich blockierte Rechnung behält ihren finalisierten Commerce-Status. Nutzen Sie reasonKey und detailKeys, korrigieren Sie die Accounting- Konfiguration und rufen Sie erst danach retry auf. Technische Fehler enden nach begrenzten Wiederholungen als failed.

Für geeignete Rechnungen vor dem Cutover steht der getrennte Prüfvertrag zur Verfügung:

POST /api/v1/accounting/commerce-invoice-reviews/create
POST /api/v1/accounting/commerce-invoice-reviews/new-revision
GET  /api/v1/accounting/commerce-invoice-reviews/{id}/lines
POST /api/v1/accounting/commerce-invoice-reviews/{id}/submit
POST /api/v1/accounting/commerce-invoice-reviews/{id}/reject
POST /api/v1/accounting/commerce-invoice-reviews/{id}/approve-and-project

Übergeben Sie beim Anlegen je Rechnungsposition invoiceItemId und taxTreatmentMappingId sowie eine Begründung. Der Server speichert Source-Fingerprint und Mapping-Snapshot. Nach dem Einreichen bleibt die Revision unveränderlich; Korrekturen verwenden new-revision. Der Freigeber muss sich von Ersteller und Einreicher unterscheiden. approve-and-project prüft den Fingerprint erneut und schreibt Freigabe und Projektion atomar.

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.

Der DATEV-Startvertrag verlangt zusätzlich exportProfileId:

POST /api/v1/accounting/datev-exports/start

Das Profil muss für den gesamten angefragten Zeitraum aktiv und gültig sein und adapterKey=datev verwenden. Der erzeugte Lauf snapshottet Profil-ID, Profilcode, Adapter-Key, Profilversion und Zuordnungsregel. Bei expliziter Zuordnung speichert die materialisierte Exportzeile außerdem die verwendete Mapping-ID; spätere Konfigurationsänderungen schreiben vorhandene Läufe nicht um.

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.