DATEV Rechnungswesen anbinden: Eine Verbindung, Lesen und Schreiben

DATEV Rechnungswesen ist die Anwendung, mit der deutsche Steuerberater und Unternehmen mit eigener Buchhaltung Buchungen festhalten. Es ist das Ende der Kette und keine Station darauf, und es ist das eine DATEV-Produkt, aus dem sich ein Hauptbuch abfragen lässt. Dorthin gehören Reporting- und Abstimmungsprodukte.

Es ist zugleich kein Cloud-Produkt, für das man sich anmeldet. Unsere Dokumentation ist dabei deutlich: „Es gehört nicht zur Suite der Online-Anwendungen von DATEV, es ist also im Kern eine On-Premise-Anwendung, die bei einem Anbieter oder auf einem eigenen Server betrieben werden kann.“ Ihr Kunde betreibt es, oder jemand betreibt es für ihn.

Das hat eine unmittelbare Folge dafür, was es erreichen kann. Genau ein Dienst übergibt Daten direkt in Rechnungswesen. Alles andere, Belege und Buchungsvorschläge eingeschlossen, läuft zuerst über DATEV Unternehmen Online, wo der Steuerberater arbeitet, bevor etwas gebucht wird.

Die kaufmännische Sicht und die Abdeckung dieses Systems stehen auf der Seite zur DATEV-Rechnungswesen-Schnittstelle, und die Herstellerebene, also die ganze Liste der DATEV-Datenservices und der Status als Schnittstellenanbieter, steht auf der DATEV-Übersicht.

Die meisten Systeme in diesem Katalog haben ein Zielsystem, einige haben zwei. Rechnungswesen hat mehr, und zwei davon zählen für eine neue Integration:

• datev-rewe ist der Weg mit dem kurzen Token, und seine Aufgabe ist es, die Firmen aufzulisten, die eine Anmeldung erreicht.
• datev-rewe-longtoken ist das, worüber Sie arbeiten, sobald eine Firma gewählt ist, und zwar in beide Richtungen.

Zu wissen, dass Buchungssätze und eine Summen- und Saldenliste zurückkommen, sagt Ihnen noch nicht, welches der zwei Token Sie am Ende halten. Beide Richtungen antworten auf demselben Account-Key, in Ihrem Client gibt es also keine Verzweigung zwischen Schreib- und Lesepfad.

Weil jeder Exportaufruf eine Firma braucht, empfiehlt unsere Dokumentation hier den interaktiven Ablauf statt des manuellen Wegs: Die Firma wird während der Authentifizierung gewählt und für die folgenden Aufrufe wiederverwendet, nichts dahinter muss sie also mitführen.

Eine weitere Einzelheit von DATEVs Seite gehört in Ihr Datenmodell statt in Ihren Client-Code.

Die Datenbestandskennung von DATEV ist je API eindeutig und nicht global, derselbe Wert auf einer Rechnungswesen-API ist also nicht zwingend dieselbe Einheit wie auf einer Lohn-API. Eine eigene Zuordnung zwischen Ihren Einheiten und denen von DATEV zu führen, ist deshalb keine Kür, und DATEV bittet Sie, sie in den Freigabeterminen zu erklären.

Eine Unstimmigkeit in der Dokumentation lohnt es zu kennen, bevor sie eine Stunde kostet: Im Abschnitt zum manuellen Token lautet der dritte Schritt „Bei DATEV Unternehmen Online authentifizieren“, während die Anweisung darunter datev-rewe-longtoken nennt. Die Anweisung ist die richtige Hälfte.

Dass eine Verbindung beide Richtungen erreicht, heisst nicht, dass DATEV dahinter einen Dienst hat. Schreiben und Lesen sind zwei verschiedene DATEV-Datenservices, vom Steuerberater getrennt bestellt, und jeder läuft auf seiner eigenen Online-API. Geändert hat sich, dass beide auf derselben Authentifizierung antworten statt auf zweien.

DATEV bietet zwei Varianten des Refresh-Tokens an. Die kurze lebt elf Stunden und erreicht jeden Datenbestand, den die Identität sehen darf. Die lange lebt zwei Jahre, verlängert sich bei jedem Refresh und erreicht genau einen Datenbestand. Die lange verlangt den Scope offline_access, und sie ist das Token hinter der Verbindung oben.

Was Sie wissen sollten, bevor Sie ein Reporting-Feature planen: Die Leseseite hängt an den Client-Credentials und nicht an irgendetwas in Ihrem Code. Die Anwendung hinter diesen Zugangsdaten muss den Export-Dienst enthalten, sonst authentifiziert die Verbindung und das Hauptbuch bleibt leer. maesn stellt Zugangsdaten mit dem vollen Satz an Diensten für neue Integrationen aus, Sie müssen das also nicht veranlassen.

Der eine Termin, den Sie einplanen, liegt zwei Jahre voraus. DATEV verlangt, dass Ihr Verbindungsbildschirm das berechnete Ablaufdatum zeigt, mindestens in der Form TT.MM.JJJJ HH:MM, dazu einen Status und den vollen Namen der Person, die das Token ausgestellt hat. Bauen Sie die Erinnerung zur Erneuerung gleich auf dieses Datum, während Sie die Verbindung bauen: Zwei Jahre sind weit genug weg, um sich anzufühlen, als käme der Tag nie, und wenn er kommt, scheitert es leise.

Auf diesem System stehen zehn Objekte bereit, und sie sortieren sich in drei Gruppen statt in zwei. Sieben sind nur lesbar, zwei nur schreibbar, und genau eines reist in beide Richtungen: die Buchung selbst.

Diese eine Überschneidung ist die nützlichste Tatsache an dieser Integration, und zugleich die, die am leichtesten verlorengeht. Sie bedeutet, dass sich eine übergebene Buchung gegen das Hauptbuch prüfen lässt statt gegen den eigenen Datensatz, und das ist der Unterschied zwischen einer Abstimmungsfunktion und einer hoffnungsvollen.

Sie bedeutet ausserdem, dass der Umlauf die zwei DATEV-Datenservices aus dem vorigen Abschnitt kreuzt: Sie schreiben über den Buchungsdatenservice und lesen über den Datenservice Export Rechnungswesen zurück, auf einem Account-Key und einem Ablaufdatum.

Dateien sind das zweite schreibbare Objekt. In den Worten von DATEV ist das der Beleg neben der Buchung, und deshalb spricht die Schreibseite dieses Systems von einem Belegsatz und einem Beleglink, der Verknüpfung von einer Buchung zu ihrem Beleg.

Diese zwei Begriffe sind DATEVs eigene, und der zweite hat eine Grenze, die man kennen sollte, bevor man darum herum entwirft. Die Verknüpfung übersteht den Umlauf, der Beleg nicht: GET /journalEntries gibt die Kennung des verknüpften Belegs in documentId zurück, sofern es einen gibt, Sie erkennen also, dass eine Buchung einen Beleg hat und welchen. Was Sie nicht können, ist die Datei selbst wieder herausziehen. Planen Sie damit, von allem, was Sie einem Nutzer zeigen wollen, eine eigene Kopie zu halten.

Acht Objekte sind über das Exportsystem lesbar, und zwei davon sind ungewöhnlich genug, um zu ändern, was ein Produkt anbieten kann.

Das erste ist der Kontenrahmen. Er ist der Lesezugriff, der aus dem Kontenmapping einen Konfigurationsbildschirm macht statt eines Tabellenaustauschs mit dem Buchhalter des Kunden. Wenn Sie irgendeine Form von Buchungsfunktion anbieten, ist er das, womit Sie Ihrem Kunden seine eigenen Konten zeigen, statt ihn Nummern eintippen zu lassen.

Das zweite ist die Summen- und Saldenliste, in DATEVs eigenem Vokabular auch SuSa. Sie gibt Salden je Konto zurück, und genau das braucht eine Reporting-Ansicht und kann ein Journalexport nicht liefern.

Und der Bericht trägt eine Voraussetzung: Der Endpunkt verlangt ein Startdatum des Wirtschaftsjahres. Dieses System gibt Wirtschaftsjahre als eigenen Lesezugriff heraus, dieses Datum kommt also aus derselben Verbindung wie der Bericht.

Die Schreibzeile trägt eine Einzelheit, die erklärt, wie viel hinter den Worten „DATEV-Format“ steckt. Für den Buchungsdatenservice veröffentlicht DATEV zwei getrennte Sätze an Anforderungen: einen für den Datenservice und einen für das DATEV-Dateiformat selbst.

Den ersten zu erfüllen heisst nicht, den zweiten erfüllt zu haben. Über maesn übergeben Sie eine normalisierte Buchung, und die Übersetzung in dieses Format passiert bei uns, was der grösste Teil des Grundes ist, warum sich diese Integration überhaupt auslagern lässt.

Zwei kleinere Lesezugriffe runden die Liste ab. Zahlungsbedingungen stehen bereit und sind nützlich, ohne entscheidend zu sein. Offene Posten sind in der Beta und nicht allgemein verfügbar, wenn Ihr Produkt also daran hängt, fragen Sie uns, bevor Sie darum herum entwerfen.

Die Lesezugriffe werden gefiltert und paginiert wie auf jedem anderen System der Plattform, und das zählt hier mehr als auf einem System, in das Sie nur schreiben: Ein Hauptbuch lohnt es, durchzublättern.

Wie das über Systeme hinweg normalisiert ist, die sich jeweils eigene Parameter ausgedacht haben, ist das Thema von Unified Pagination & Filtering, und ein Reporting-Produkt auf diesen Lesezugriffen hat die Form, die unter Finanzanalyse und Finanzplanung beschrieben ist.

Kontakte sind das zweite nur schreibbare Objekt, und sie verhalten sich auf eine Weise, die in diesem Katalog keine Entsprechung hat. Sie können einen Kontakt anlegen. Sie können ihn an Ort und Stelle aktualisieren. Zurücklesen können Sie ihn nicht.

Es liegt nahe, einen zweiten Weg zu vermuten, weil es ihn auf den meisten Systemen gibt: Wo Kontakte nicht verfügbar sind, erreicht man denselben Datensatz gewöhnlich über Kunden oder Lieferanten. Hier nicht. Beide sind auf diesem System nicht verfügbar, und damit sind Kontakte das Objekt, auf das ein Geschäftspartner abgebildet wird, und zugleich das, das sich nicht prüfen lässt.

Eines sollte man nicht hineinlesen. Unsere eigene Dokumentation beschreibt, dass sich „Buchungssätze, Lieferanten und Kunden“ direkt in diesem System anlegen lassen, und die Objektzustände sagen etwas anderes: Lieferanten und Kunden sind nicht verfügbar, Kontakte sind das schreibbare Objekt.

Wo die beiden sich widersprechen, sind die Abdeckungsdaten das, was die Plattform tatsächlich freischaltet, und das gilt hier. Auf welches Objekt ein Geschäftspartner über Systeme hinweg abgebildet wird, die ihn alle anders nennen, gehört zum Common Data Model.

Kein Objekt auf diesem System hat Löschen freigeschaltet, und das passt dazu, wie ein buchhalterischer Kontext Korrekturen erwartet. Korrekturen und Stornierungen sollen neue Belege sein statt Entfernungen, ein Entwurf, der eine Gegenbuchung übergibt, ist also zugleich richtiger und näher daran, wie ein Buchhalter das Ergebnis liest.

Drei Anforderungen von DATEV prägen den Entwurf einer leselastigen Integration, und keine davon ist eine API-Einzelheit. Es sind Bedingungen der Produktivfreigabe, und sie werden geprüft.

Änderungserkennung kann keine Schleife sein. Getrennt gezählt, weil die drei Zustände dieser Spalte drei verschiedene Dinge bedeuten: Kein Objekt auf diesem System trägt ein natives Event, acht Kombinationen sind als auf Anfrage markiert und jede davon ist ein Webhook, und die übrigen 29 sind nicht verfügbar.

Auf der anderen Seite führt DATEV das Dauerpolling als DONT und bittet darum, dass Aufrufe etwas folgen, das der Kunde gerade angefordert hat, von Hand oder durch eine Regel. Was bleibt, ist also ein Lesezugriff, der durch eine Handlung oder einen begründbaren Zeitplan ausgelöst wird. Das Intervall gehört Ihnen; „immer“ gehört nicht zu den Möglichkeiten. Was ein System ohne Events an einem Abgleich ändert, ist das Thema des Unified-Webhook-Modells.

Ein technisches Protokoll ist Pflicht. DATEV verlangt ein HTTP-Protokoll von Anfragen und Antworten, mindestens 14 Tage aufbewahrt, aus dem sich die zeitliche Reihenfolge der Aufrufe rekonstruieren lässt.

Das Minimum ist genau benannt: Zeitstempel, die Methode und die vollständige URL einschliesslich Query-Parameter, die Header ohne den Authorization-Header, und auf der Antwortseite mindestens die Header X-Global-Transaction-ID und V-Cap-Request-ID. Für Ihre Kunden sichtbar sein muss es nicht. Vorhanden sein muss es, wenn Sie ein Ticket eröffnen.

Die Fehlerquote ist eine Zahl mit einem Preis. Nach der Produktivfreigabe erwartet DATEV, dass weniger als zehn Prozent der Anfragen mit 4xx oder 5xx antworten, überwacht das, und eine Überschreitung löst eine kostenpflichtige Nachprüfung aus. Bei einer leselastigen Integration an einer Verbindung, die nach zwei Jahren abläuft, ist der naheliegende Weg dorthin ein geplanter Lesezugriff, der weiterläuft, nachdem die Authentifizierung abgelaufen ist.

Vier Dinge hören auf, Ihre zu sein:

• Die Verbindung und ihre Laufzeit. Eine Einwilligung, ein Zwei-Jahres-Token und ein Ablaufdatum liegen je Mandant, und Ihre Aufrufstellen sehen eine Form von Account-Key.
• Das Buchungsformat. Sie übergeben das Common Data Model; die CSV im DATEV-Format, der Beleglink und die Dateiformat-Anforderungen dahinter werden hier erledigt.
• Die Wahl des Wegs. Ob eine Nutzlast direkt nach Rechnungswesen gehen kann oder über Unternehmen Online laufen muss, ist ein Parameter, den Sie setzen.
• Zugang zu DATEV ohne das Partnerverfahren vorab. Sie bauen auf dem Client von maesn, es muss also nichts beantragt, bezahlt oder abgewartet werden, bevor Ihr erster Aufruf läuft. Wollen Sie später offizieller DATEV Schnittstellenanbieter im eigenen Namen werden, begleiten wir dieses Verfahren mit Ihnen und Sie ziehen auf Ihren eigenen Client um; die DATEV-Gebühren dafür sind Ihre, und Sie bauen in der Zwischenzeit weiter.

Vier Dinge bewegen sich nicht:

• Ihr Datensatz zu jedem geschriebenen Kontakt. Das Objekt lässt sich nicht zurücklesen, keine Schicht kann es also rekonstruieren. Das ist auf diesem System der klarste Fall einer Lücke, die eine Tatsache ist und kein Feature-Wunsch.
• Die Erinnerung zur Erneuerung. Die Verbindung nach zwei Jahren neu zu bestätigen, ist die Handlung Ihres Kunden, und ihn daran zu erinnern, ist die Aufgabe Ihres Produkts.
• Das Protokoll und das Fehlerbudget. Beides läuft auf Ihrer Infrastruktur und wird gegen Ihren Client gemessen, beides lässt sich also nicht abgeben.
• Was der Berater geändert hat. Wo Daten über Unternehmen Online laufen, darf der Berater sie ändern, bevor sie gebucht werden. Das Hauptbuch zurückzulesen sagt Ihnen, was passiert ist; die Änderung verhindert nichts.

Eine Anmerkung zu den Objekten. Acht Kombinationen sind hier als auf Anfrage markiert, alle davon Webhooks, und diese Spalte bedeutet ein Gespräch mit uns. Unsere eigenen Daten stützen in keine Richtung eine Aussage über native Events, wenn Events auf diesem System also für Ihren Fahrplan zählen, ist die nützliche Handlung, uns zu fragen.