Schnittstellenvorgaben für Buchungsdatenservice

Mit dem DATEV Buchungsdatenservice können Sie Bewegungs- und Stammdaten im Dateiformat "DATEV-Format" direkt per Webservice an das DATEV Rechenzentrum übertragen. Außerdem können digitale Belegbilder nach DATEV Unternehmen online übertragen werden, dieses geschieht technisch über die Online API accounting:documents. Nachfolgend wird der (reguläre) API Workflow aufgezeigt und welche Online-APIs & Endpunkte im Zusammenhang mit dem Datenservice verwendet werden müssen/sollten.

API WORKFLOW

  1. Prüfung der Berechtigungen
  2. Übertragung einzelner Dokumente
  3. Übertragung einer Bewegungs- und Stammdaten im Dateiformat "DATEV-Format"
  4. Überprüfung ob die Übertragung korrekt abgeschlossen wurde
MUST: Übermittelte Dokumente (PUT/POST) und lesende API-Requests (GET) sollten in einem gesunden Verhältnis sein. Auf ein  erfolgreich übermitteltes Dokument weitere 30 GET-Requests zu produzieren, zeugt nicht von einer effizienten Integration.

ONLINE API & ENDPUNKTE für SANDBOX

(Base URL: https://api-name.api.datev.de/platform-sandbox/)
Die Sandbox Umgebung führt nur eine grobe Prüfung der übermittelten Daten durch, anhand derer dann ggf.Fehlermeldungen zurückgemeldet werden. Es erfolgt keine wirkliche Verarbeitung der Daten und keine Speicherung der Ergebnisse. Die Ergebnisse der Verarbeitung können daher erst im Rahmen der Produktionsfreigabe betrachtet werden.

Prüfung der Berechtigungen

GET https://accounting-clients.api.datev.de/platform-sandbox/v2/clients
GET https://accounting-clients.api.datev.de/platform-sandbox/v2/clients/{client-id}
Hier können die Datenbestände abgefragt werden, auf die der Kunde die Berechtigungen hat. Die 3rd-Party App kann dabei für sich selbst festlegen, welche der beiden Endpunkte sie nutzt. Wird der erste Endpunkt genutzt, so gibt die API alle verfügbaren Datenbestände zurück. Dies kann insbesondere bei größeren Unternehmen zu hunderten oder tausenden von Datenwerten führen. Daher kann es auch sinnvoll sein nur den zweiten Endpunkt zu nutzen. Hier muss dann der Kunde aber eine Eingabemöglichkeit in der 3rd-Party-App für die Berater- und Mandantennummer bekommen. In der jeweiligen 3rd-Party-App müssen die Datenbestände selbst auf die benötigten Berechtigungen geprüft und gefiltert werden. Nur bei solchen, die "Buchungsdatenservice" zurück liefern, dürfen in der Folge Daten übertragen werden. 
MUST: Ein der beiden Endpunkte zur Abfrage der Berechtigungen für einen Datenbestand muss genutzt werden. Wird der erste Endpunkt genutzt, erwarten wir eine blätterbare Anzeige (Paging) der verfügbaren Mandantenbestände. Weiterhin muss dem Kunden der Unternehmensname und die Berater- & Mandantennummer angezeigt werden. Bei Verwendung des zweiten Endpunkts ist aufzuzeigen, wo der Kunde seine Angaben für den Datenbestand macht. Falls ein Langzeittokens genutzt wird, darf nur der zweite Endpunkt verwendet werden.
Wichtiger Hinweis: Das Erhalten des Langzeittokens für eine {client-id} bedeutet noch nicht, dass der Kunde tatsächlich Berechtigungen für die {client-id} besitzt. D.h. die 3rd-Party App holt sich das Token und spricht danach unmittelbar die GET Clients damit an. Die Authentifizierung ist erst dann dem Kunden als erfolgreich verbunden anzuzeigen, wenn der GET Clients die korrekte Rechtevergabe bestätigt hat. 
DONT: Verwendung von https://accounting-documents.../clients. Dieser Endpunkt ist dem Belegbilderservice vorbehalten
DONT: Verwendung von https://accounting-dxso-jobs.../clients. Dieser Endpunkt ist dem Rechnungsdatenservice 1.0 vorbehalten


Challenges:
  • Berater erteilt Token für eine Berater- und Mandantennummer die keine Buchungsdatenservice Berechtigung hat, z.B. BeraterNr 455148 Mandant 3
  • Berater trägt eine ungültige Berater- und Mandantennummer ein

Übertragung einzelner Dokumente

Mit einem der beiden folgenden Endpunkte sollten die Dokumente an DATEV Unternehmen Online übermittelt werden. 
PUT https://accounting-documents.api.datev.de/platform-sandbox/v2/clients/{client-id}/documents/{Guid}
Dieser Endpunkt ist im Rahmen des Buchungsdatenservice zu präferieren. Hierbei ist zunächst für jedes Dokument in der 3rd-Party App eine Guid zu generieren, welche dann übergeben wird. Hierdurch wird sichergestellt, das keine identischen Dokumente doppelt übergeben werden, da jede Guid nur einmal in DATEV Unternehmen online genutzt werden kann. 
POST https://accounting-documents.api.datev.de/platform-sandbox/v2/clients/{client-id}/documents
Dieser Endpunkt kann notfalls verwendet werden, falls die 3rd-Party App nicht in der Lage ist selbst eine eindeutige Guid zu erzeugen. Diese wird dann durch DATEV Unternehmen online bei der Nutzung des Endpunktes erzeugt und an die 3rd-Party App übergeben.
Diese Endpunkte dienen zur Übermittlung jeweils eines einzelnen Dokuments.
Wichtiger Hinweis: Die Guid muss der RFC4122 entsprechen und im 8-4-4-4-12 Format aufbereitet sein. Für jedes Dokument ist zusätzlich zwingend ein Metadaten-Objekt (JSON) Namens "metadata" zu übermitteln. Metadata enthält insgesamt fünf Datenfelder von denen die ersten beiden (document_type, note) nicht verwendet werden sollen. Die letzen drei Datenfelder (category, folder, register) sollen den Ablageort des Dokumentes angeben. category soll einen Verweis auf die 3rd-Party App darstellen, folder die Art der Dokumente und register den Kalendermonat und -jahr des Dokumentes, also z.B. (SuperERP, Belege, 2023-05). 
MUST: Zeigen Sie eine erfolgreiche Übertragung von einem Beleg.
MUST: Verwendung der drei Datenfelder category, folder und register bei jedem Dokument
Challenges:
  • Berater lässt ein bestimmtes Dokument in der 3rd-Party-App bereitstellen und stößt die Übermittlung an

Übertragung einer Bewegungs- und Stammdaten

POST https://accounting-extf-files.api.datev.de/platform-sandbox/v3/clients/{client-id}/extf-files/import
Nutzen Sie diesen Endpunkt, um eine DATEV-Format Datei für Bewegungs- oder Stammdaten an die DATEV zu übermitteln. Es empfielt sich zunächst alle verknüpften Dokumente zu übermitteln und danach die dazugehörige DATEV-Format Datei. Die Verknüpfung der Belege zu den Bewegungsdaten hat über das Feld Beleglink (Spalte 20) in der DATEV-Format Datei zu erfolgen. Die 3rd-Party-App hat sicherzustellen dass die jeweiligen Bewegungsdaten nur einmal übermittelt werden können und der Anwender im Normalfall bereits übermittelte Bewegungsdaten nicht erneut übermitteln kann. Für entsprechende Supportkonstellationen kann es jedoch nötig sein, dass eine erneute Übermittlung von bereits übermittelten Bewegungsdaten ermöglicht wird. Dieses ist in der 3rd-Party-App entsprechend umzusetzen. Wichtiger Hinweis: Dieser Endpunkt liefert i.d.R. einen 202er Code als Rückmeldung, selbst bei der Übertragung einer Virusdatei. Daher ist zwingend der Job Status abzufragen zur Überprüfung ob die Datei korrekt verarbeitet werden kann. 

GET https://accounting-extf-files.api.datev.de/platform-sandbox/v3/clients/{client-id}/extf-files/import/jobs/{jobid}
Nutzen Sie diesen Endpunkt um abzufragen ob die übertragene DATEV-Format Datei korrekt verarbeitet werden konnte. Die jobid bzw. die entsprechende URL für diese Abfrage wird Ihnen im location header bei dem entsprechenden POST direkt zurück geliefert. Auch dieser Endpunkt liefert i.d.R. 200er Code zurück. Im Falle eines Fehlers wird die entsprechende Fehlerinformation als Response zurückgeliefert. Nur wenn der Response result = success zurückliefert darf die Übermittlung in der 3rd-Party-App als erfolgreich dargestellt werden. Andernfalls sind die entsprechenden Fehlermeldungen zu visualisieren. 
SHOULD: Die Abfrage des Jobstatus sollte nicht direkt nach dem POST erfolgen, sondern erst nach der im POST als Retry-After genannte Zeit in Sekunden gestartet werden.
MUST: Es ist eine Datei mit Bewegungsdaten zu übergeben.


Challenges:
  • Test des Fehlerhandlings durch Übertragung von Daten für BeraterNr 455148 Mandant 2 (liefert generell einen Fehler).
  • Erneute Übermittlung von bereits übergebenen Bewegungsdaten.


ONLINE API & ENDPUNKTE für PRODUKTION

(Base URL: https://api-name.api.datev.de/platform/)
Voraussetzung für die Produktionsabnahme ist die Verarbeitung der Daten in ein entsprechendes Produktivsystem mit DATEV Rechnungswesen und Unternehmen Online sowie im Vorfeld eingerichteten und konfigurierten Testmandant und Zugangsberechtigungen inkl. Mandantenregistrierung für den Buchungsdatenservice.

Prüfung der Berechtigungen

GET https://accounting-clients.api.datev.de/platform/v2/clients
GET https://accounting-clients.api.datev.de/platform/v2/clients/{client-id}
Hier können die Datenbestände abgefragt werden, auf die der Kunde die Berechtigungen hat. Die 3rd-Party App kann dabei für sich selbst festlegen, welche der beiden Endpunkte sie nutzt. Wird der erste Endpunkt genutzt, so gibt die API alle verfügbaren Datenbestände zurück. Dies kann insbesondere bei größeren Unternehmen zu hunderten oder tausenden von Datenwerten führen. Daher kann es auch sinnvoll sein nur den zweiten Endpunkt zu nutzen. Hier muss dann der Kunde aber eine Eingabemöglichkeit in der 3rd-Party-App für die Berater- und Mandantennummer bekommen. In der jeweiligen 3rd-Party-App müssen die Datenbestände selbst auf die benötigten Berechtigungen geprüft und gefiltert werden. Nur bei solchen, die "Buchungsdatenservice" zurück liefern, dürfen in der Folge Daten übertragen werden. 
MUST: Ein der beiden Endpunkte zur Abfrage der Berechtigungen für einen Datenbestand muss genutzt werden. Wird der erste Endpunkt genutzt, erwarten wir eine blätterbare Anzeige (Paging) der verfügbaren Mandantenbestände. Weiterhin muss dem Kunden der Unternehmensname und die Berater- & Mandantennummer angezeigt werden. Bei Verwendung des zweiten Endpunkts ist aufzuzeigen, wo der Kunde seine Angaben für den Datenbestand macht. Falls ein Langzeittokens genutzt wird, darf nur der zweite Endpunkt verwendet werden.
Wichtiger Hinweis: Das Erhalten des Langzeittokens für eine {client-id} bedeutet noch nicht, dass der Kunde tatsächlich Berechtigungen für die {client-id} besitzt. D.h. die 3rd-Party App holt sich das Token und spricht danach unmittelbar die GET Clients damit an. Die Authentifizierung ist erst dann dem Kunden als erfolgreich verbunden anzuzeigen, wenn der GET Clients die korrekte Rechtevergabe bestätigt hat. 
DONT: Verwendung von https://accounting-documents.../clients. Dieser Endpunkt ist dem Belegbilderservice vorbehalten
DONT: Verwendung von https://accounting-dxso-jobs.../clients. Dieser Endpunkt ist dem Rechnungsdatenservice 1.0 vorbehalten


Challenges:
  • Berater erteilt ein Token mit Zugriff auf einen Testbestand mit mehreren hundert Testbeständen
  • Berater erteilt Token für eine Berater- und Mandantennummer die keine Buchungsdatenservice Berechtigung hat
  • Berater trägt eine ungültige Berater- und Mandantennummer ein

Übertragung einzelner Dokumente

Mit einem der beiden folgenden Endpunkte sollten die Dokumente an DATEV Unternehmen Online übermittelt werden. 
PUT https://accounting-documents.api.datev.de/platform/v2/clients/{client-id}/documents/{Guid}
Dieser Endpunkt ist im Rahmen des Buchungsdatenservice zu präferieren. Hierbei ist zunächst für jedes Dokument in der 3rd-Party App eine Guid zu generieren, welche dann übergeben wird. Hierdurch wird sichergestellt, das keine identischen Dokumente doppelt übergeben werden, da jede Guid nur einmal in DATEV Unternehmen online genutzt werden kann. 
POST https://accounting-documents.api.datev.de/platform/v2/clients/{client-id}/documents
Dieser Endpunkt kann notfalls verwendet werden, falls die 3rd-Party App nicht in der Lage ist selbst eine eindeutige Guid zu erzeugen. Diese wird dann durch DATEV Unternehmen online bei der Nutzung des Endpunktes erzeugt und an die 3rd-Party App übergeben.
Diese Endpunkte dienen zur Übermittlung jeweils eines einzelnen Dokuments.
Wichtiger Hinweis: Die Guid muss der RFC4122 entsprechen und im 8-4-4-4-12 Format aufbereitet sein. Für jedes Dokument ist zusätzlich zwingend ein Metadaten-Objekt (JSON) Namens "metadata" zu übermitteln. Metadata enthält insgesamt fünf Datenfelder von denen die ersten beiden (document_type, note) nicht verwendet werden sollen. Die letzen drei Datenfelder (category, folder, register) sollen den Ablageort des Dokumentes angeben. category soll einen Verweis auf die 3rd-Party App darstellen, folder die Art der Dokumente und register den Kalendermonat und -jahr des Dokumentes, also z.B. (SuperERP, Belege, 2023-05). 
MUST: Zeigen Sie eine erfolgreiche Übertragung von mindestens zwei Belegen mit jeweils unterschiedlichen Kalendermonaten.
MUST: Das Dokument muss mit einer lesbaren Qualität in Belege online ankommen. Die Kunden erwarten gut lesbare Dokument die gleichzeitig ein geringes Speichervolumen aufweisen. Höhere Speichervolumen verursachen nicht nur Kosten bei DATEV sondern kosten auch allem (Lade-)Zeit beim Aufruf der Dokument über die DATEV Apps. 
MUST: Verwendung der drei Datenfelder category, folder und register bei jedem Dokument
Challenges:
  • Berater lässt ein zu grosses Dokument übermitteln und prüft, wie die 3rd-Party App reagiert.
  • Berater lässt ein bestimmtes Dokument in der 3rd-Party-App bereitstellen und stößt die Übermittlung an
  • Berater lässt Dokument mit falscher Datei Extension übermitteln und prüft, wie die 3rd-Party App reagiert.

Übertragung einer Bewegungs- und Stammdaten

POST https://accounting-extf-files.api.datev.de/platform/v3/clients/{client-id}/extf-files/import
Nutzen Sie diesen Endpunkt, um eine DATEV-Format Datei für Bewegungs- oder Stammdaten an die DATEV zu übermitteln. Es empfielt sich zunächst alle verknüpften Dokumente zu übermitteln und danach die dazugehörige DATEV-Format Datei. Die Verknüpfung der Belege zu den Bewegungsdaten hat über das Feld Beleglink (Spalte 20) in der DATEV-Format Datei zu erfolgen. Die 3rd-Party-App hat sicherzustellen dass die jeweiligen Bewegungsdaten nur einmal übermittelt werden können und der Anwender im Normalfall bereits übermittelte Bewegungsdaten nicht erneut übermitteln kann. Für entsprechende Supportkonstellationen kann es jedoch nötig sein, dass eine erneute Übermittlung von bereits übermittelten Bewegungsdaten ermöglicht wird. Dieses ist in der 3rd-Party-App entsprechend umzusetzen. Wichtiger Hinweis: Dieser Endpunkt liefert i.d.R. einen 202er Code als Rückmeldung, selbst bei der Übertragung einer Virusdatei. Daher ist zwingend der Job Status abzufragen zur Überprüfung ob die Datei korrekt verarbeitet werden kann. 

GET https://accounting-extf-files.api.datev.de/platform/v3/clients/{client-id}/extf-files/import/jobs/{jobid}
Nutzen Sie diesen Endpunkt um abzufragen ob die übertragene DATEV-Format Datei korrekt verarbeitet werden konnte. Die jobid bzw. die entsprechende URL für diese Abfrage wird Ihnen im location header bei dem entsprechenden POST direkt zurück geliefert. Auch dieser Endpunkt liefert i.d.R. 200er Code zurück. Im Falle eines Fehlers wird die entsprechende Fehlerinformation als Response zurückgeliefert. Nur wenn der Response result = success zurückliefert darf die Übermittlung in der 3rd-Party-App als erfolgreich dargestellt werden. Andernfalls sind die entsprechenden Fehlermeldungen zu visualisieren. 
SHOULD: Die Abfrage des Jobstatus sollte nicht direkt nach dem POST erfolgen, sondern erst nach der im POST als Retry-After genannte Zeit in Sekunden gestartet werden.
MUST: Es sind Bewegungsdaten für zwei unterschiedliche Monate zu übergeben.
SHOULD: Es sind Stammdaten für Kreditoren oder Debitoren zu übergeben.
MUST: Die übergebenen Bewegungs- und Stammdaten müssen fehlerfrei in DATEV Rechnungswesen eingelesen und verarbeitet werden.
MUST: Das mit einem Rechnungssatz verknüpfte Dokument muss in DATEV Rechnungswesen angezeigt werden.


Challenges:
  • Es sind Bewegungsdaten für einen Mandanten mit abweichendem Wirtschaftsjahr zu übergeben.
  • Es sind Bewegungsdaten für Rechnungskorrekturen zu übergeben.
  • Erneute Übermittlung von bereits übergebenen Bewegungsdaten.


CHANGELOG

Version

Datum

Änderungen
1.0 03.04.2023 Erstveröffentlichung