Schnittstellenvorgaben für Rechnungsdatenservice 1.0

Mit dem DATEV Rechnungsdatenservice 1.0 können digitale Belege und strukturierte Belegdaten nach DATEV Unternehmen online übermittelt werden. Aus den übertragenen Daten werden Belegsätze für DATEV Belege online (Bearbeitungsform Erweitert) oder DATEV Kassenbuch online erzeugt. Durch einen Bereitstellungsprozess der Belegsätze aus Belege/Kassenbuch online können Buchungsvorschläge für unser DATEV Rechnungswesen erzeugt werden. 

MUST: Für die strukturierten Daten (Rechnungs-/Kassendaten) ist ausschließlich die Belegsatzdatendatei zu verwenden.

API WORKFLOW

  1. Prüfung der Berechtigungen für den Datenservice bzw. DATEV Belege online
  2. Abfrage der Metadaten (z.B. Wirtschaftsjahr, Bearbeitungsform, Rechnungs-/Kassenbücher)
  3. Generierung Job-ID und Verifizierung weiterer Metadaten
  4. Übertragung der Dateien (Dokumente & Daten)
  5. Ergebnis der Übertragung prüfen
MUST: Übermittelte Jobs (POST) und lesende API-Requests (GET) sollten in einem gesunden Verhältnis sein. Auf einen  erfolgreich übermittelten Job weitere 30 GET-Requests zu produzieren, zeugt nicht von einer effizienten Integration.

ONLINE API & ENDPUNKTE für SANDBOX

Unsere Sandbox für den Rechnungsdatenservice 1.0 ist ein technischer Mockup, welcher vordefinierte Rückgabewerte liefert, die nicht im Zusammenhang mit den tatsächlich übermittelten Daten stehen.

1. Berechtigungen prüfen

GET https://accounting-dxso-jobs.../clients
GET https://accounting-dxso-jobs...clients/{client-id}

Hier können die Datenbestände abgefragt werden, auf die der Kunde die nötigen Berechtigungen hat. Wird der erste Endpunkt genutzt, so gibt die API alle verfügbaren Datenbestände zurück. Beim Abruf des zweiten Endpunktes erhalten wir eine Liste der Basisdaten, für einen bestimmten Kunden. 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.

Unsere Sandbox arbeitet grundsätzlich mit der Beraternummer 455148 und den Mandantennummern 1-6. Für den Rechnungsdatenservice 1.0 kann nur die {client-id} 455148-1 verwendet werden, da nur der Mandant 1 alle Berechtigungen für den Datenservice besitzt. 
MUST: Mindestens einer dieser Endpunkte zur Abfrage der Berechtigungen für einen Datenbestand muss genutzt werden. Zeigen sie dem Kunden nach Auswahl des Bestands den Unternehmensname und die Berater- & Mandantennummer an.
MUST: Die Berechtigungsprüfung ist vor jeder Datenübertragung zu überprüfen. Bei mehrmaliger Datenübertragung am Tag ist eine einmalige Prüfung für den Tag ausreichend.
MUST: Auf Veränderungen in den Berechtigungen muss die Integration mit einer aussagekräftigen Fehlermeldung reagieren.

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/{client-id} die korrekte Rechtevergabe bestätigt hat.

Challenges:
  • Berater erteilt ein Token mit Zugriff auf einen Testbestand mit mehreren Testbeständen
  • Berater trägt eine ungültige Berater- und Mandantennummer ein

2. Metadaten holen & prüfen

GET https://accounting-dxso-jobs.../clients/{client-id}/

Nutzen Sie diesen Endpunkt, um die konkrete Konfiguration des Datenbestands abzufragen und zu prüfen.

Für den erfolgreichen Einsatz des Rechnungsdatenservice 1.0 muss der API-User seinen Datenbestand aus DATEV Belege/Kassenbuch online in geeigneter Weise vorbereitet haben:

  • Bearbeitungsform "Erweitert" muss eingestellt sein ("basic_accounting_information" != null)
  • passendes Wirtschaftsjahr ("fiscal_year_...") angelegt:
    • bei Rechnungen für Belege online: das betreffende WJ bzw. mindestens das vorhergehende WJ muss vorhanden sein
    • bei Kassendaten für Kassenbuch online: das betreffende WJ
  • die eingestellte Kontenlänge ("account_length") muss mit der in den XML-Dateien verwendeten Kontenlänge ("accountNo" und "bpAccountNo" = "account_length"+1) übereinstimmen
  • das benötigte Hauptbuch ist für das WJ aktiviert ("ledgers")
    • Eingangsrechnnungen: "is_accounts_payable_ledger_available" = true
    • Ausgangsrechnnungen: "is_accounts_receivable_ledger_available" = true
    • Kasse: "is_cash_ledger_available" = true

MUST: Der Endpunkt ist für die Validierung der Konfiguration zu nutzen. Versichern Sie sich vor jeder Datenübertragung, dass die Konfiguration zu ihren Erwartungen passt und sich zwischenzeitlich nicht verändert hat. Werden Daten mehrmals täglich übertragen, ist eine einmalige Prüfung vor der ersten Übermittlung ausreichend.
MUST: Auf Veränderungen in der Konfiguration muss die Integration in geeigneter Weise reagieren können. Entweder durch eine aussagekräftige Fehlermeldung oder durch automatische Anpassung der Integration an die geänderten Rahmenbedingungen (z.B. Kontenlänge anpassen, Name des Rechnungsbuchs anpassen, etc.)

Challenges:
  • Berater verändert die gesendeten Daten so, dass sie nicht mehr zu den vorkonfigurierten Datenbeständen passen

3. Generierung Job-ID und weitere Metadaten prüfen


POST https://accounting-dxso-jobs.../clients/{client-id}/dxso-jobs

Die Job-ID ist das API-Pendant zum ZIP-Umschlag des Dateiformats der DATEV XML-Schnittstelle online. Im HTTP-Body muss das betreffende Hauptbuch und der Buchungsmonat angegeben werden. Neben der Job-ID aus der HTTP-Response ist insbesondere auf die Bezeichnung des Hauptbuchs zu achten ("ledger_folder_names"). Die Angabe dieser Bezeichnung ist auch zu Teil der XML-Dateien. 95% der Kunden verwenden die Default-Bezeichnungen von DATEV. 5% der Kunden verändern diese Default-Bezeichnungen aber auch.

MUST: Die Bezeichung des Hauptbuchs ist zu überprüfen und ggf. in den XML-Dateien anzupassen.

4. Übertragung der Dateien (Dokumente & Daten)

In diesem Schritt werden alle Dateien einzeln per HTTP-POST-Request auf die Job-ID eingesendet und mit einem abschließendem HTTP-PUT-Request wird die Verarbeitung des Jobs angestoßen.

POST https://accounting-dxso-jobs.../clients/{client-id}/dxso-jobs/{job-id}/files

Übertragung der einzelnen Dateien zu einer Job-ID.


PUT https://accounting-dxso-jobs.../clients/{client-id}/dxso-jobs/{job-id}

Verarbeitung der Job-ID im DATEV-Rechenzentrum initiieren.

MUST: Die Dateien eines Jobs dürfen max.150 MB groß sein und eine Einzeldatei max. 20MB
MUST: Verwendung von ASCII-Zeichen für alle Dateinamen eines Jobs
SHOULD: Rechnungen und Kassendaten sollten immer gebündelt über einen Job übermittelt werden (sofern zu einem Hauptbuch & Monat zusammengehörig) um das Ratelimit nicht unnötig zu belasten.

Challenges:
  • Berater lässt mehrere Rechnungen eines Monats übertragen.

5. Ergebnis der Übertragung prüfen

Die API ermöglicht hier einerseits die Prüfung eines rudimentären Job-Status und andererseits eines ausführlicheren Verarbeitungsprotokolls nachdem der Job verarbeitet wurde.

GET https://accounting-dxso-jobs.../clients/{client-id}/dxso-jobs/{job-id}

Abfrage des Verarbeitungsstatus für einen Job.
Bitte beachten: Unsere Sandbox liefert hier ausschließlich den Verarbeitungsstatus "4" zurück.


GET https://accounting-dxso-jobs.../clients/{client-id}/dxso-jobs/{job-id}/protocol-entries

Abfrage eines detaillierten Verarbeitungsprotokolls nach Verabeitung des Jobs (entspricht dem Importprotokoll aus DATEV Belege online).

MUST: Beide GET-Requests sind zu nutzen. Dem API-User ist unmittelbar nach der Datenübertragung das Verarbeitungsergebnis transparent zu machen und in geeigneter Weise zu dokumentieren/protokollieren.
MUST: Im Protokoll der 3rd-Party App muss sowohl der Verarbeitungsstatus (GET 1) als auch das Verarbeitungsprotokoll (GET 2) längerfristig einsehbar und gespeichert werden (mind. 1 Jahr).

Challenges:
  • Berater lässt sich das Protokoll der 3rd-Party App zeigen und prüft, ob die Rückgabewerte mit den vorgefertigten Daten der Sandbox übereinstimmen.

ONLINE API & ENDPUNKTE für PRODUKTION

Für die Nutzung dieser API in Produktion wird ein echtes DATEV-Authentifzierungsmedium und ein Datenbestand für die Anwendung DATEV Belege online in Bearbeitungsform "Erweitert" benötigt. Weitere Informationen zu den kundenseitigen Voraussetzungen befinden sich hier.

1. Berechtigungen prüfen

GET https://accounting-dxso-jobs.../clients
GET https://accounting-dxso-jobs...clients/{client-id}

Hier können die Datenbestände abgefragt werden, auf die der Kunde die nötigen Berechtigungen hat. Wird der erste Endpunkt genutzt, so gibt die API alle verfügbaren Datenbestände zurück. Beim Abruf des zweiten Endpunktes erhalten wir eine Liste der Basisdaten, für einen bestimmten Kunden. 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.

Unsere Sandbox arbeitet grundsätzlich mit der Beraternummer 455148 und den Mandantennummern 1-6. Für den Rechnungsdatenservice 1.0 kann nur die {client-id} 455148-1 verwendet werden, da nur der Mandant 1 alle Berechtigungen für den Datenservice besitzt. 
MUST: Mindestens einer dieser Endpunkte zur Abfrage der Berechtigungen für einen Datenbestand muss genutzt werden. Zeigen sie dem Kunden nach Auswahl des Bestands den Unternehmensname und die Berater- & Mandantennummer an.
MUST: Die Berechtigungsprüfung ist vor jeder Datenübertragung zu überprüfen. Bei mehrmaliger Datenübertragung am Tag ist eine einmalige Prüfung für den Tag ausreichend.
MUST: Auf Veränderungen in den Berechtigungen muss die Integration mit einer aussagekräftigen Fehlermeldung reagieren.

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/{client-id} die korrekte Rechtevergabe bestätigt hat.

Challenges:
  • Berater erteilt ein Token mit Zugriff auf einen Testbestand mit mehreren Testbeständen
  • Berater trägt eine ungültige Berater- und Mandantennummer ein

2. Metadaten holen & prüfen

GET https://accounting-dxso-jobs.../clients/{client-id}/

Nutzen Sie diesen Endpunkt, um die konkrete Konfiguration des Datenbestands abzufragen und zu prüfen.

Für den erfolgreichen Einsatz des Rechnungsdatenservice 1.0 muss der API-User seinen Datenbestand aus DATEV Belege/Kassenbuch online in geeigneter Weise vorbereitet haben:

  • Bearbeitungsform "Erweitert" muss eingestellt sein ("basic_accounting_information" != null)
  • passendes Wirtschaftsjahr ("fiscal_year_...") angelegt:
    • bei Rechnungen für Belege online: das betreffende WJ bzw. mindestens das vorhergehende WJ muss vorhanden sein
    • bei Kassendaten für Kassenbuch online: das betreffende WJ
  • die eingestellte Kontenlänge ("account_length") muss mit der in den XML-Dateien verwendeten Kontenlänge ("accountNo" und "bpAccountNo" = "account_length"+1) übereinstimmen
  • das benötigte Hauptbuch ist für das WJ aktiviert ("ledgers")
    • Eingangsrechnnungen: "is_accounts_payable_ledger_available" = true
    • Ausgangsrechnnungen: "is_accounts_receivable_ledger_available" = true
    • Kasse: "is_cash_ledger_available" = true
    MUST: Der Endpunkt ist für die Validierung der Konfiguration zu nutzen. Versichern Sie sich vor jeder Datenübertragung, dass die Konfiguration zu ihren Erwartungen passt und sich zwischenzeitlich nicht verändert hat. Werden Daten mehrmals täglich übertragen, ist eine einmalige Prüfung vor der ersten Übermittlung ausreichend.
MUST: Auf Veränderungen in der Konfiguration muss die Integration in geeigneter Weise reagieren können. Entweder durch eine aussagekräftige Fehlermeldung oder durch automatische Anpassung der Integration an die geänderten Rahmenbedingungen (z.B. Kontenlänge anpassen, Name des Rechnungsbuchs anpassen, etc.)

    Challenges:
    • Berater verändert die gesendeten Daten so, dass sie nicht mehr zu den vorkonfigurierten Datenbeständen passen

    3. Generierung Job-ID und weitere Metadaten prüfen


    POST https://accounting-dxso-jobs.../clients/{client-id}/dxso-jobs

    Die Job-ID ist das API-Pendant zum ZIP-Umschlag des Dateiformats der DATEV XML-Schnittstelle online. Im HTTP-Body muss das betreffende Hauptbuch und der Buchungsmonat angegeben werden. Neben der Job-ID aus der HTTP-Response ist insbesondere auf die Bezeichnung des Hauptbuchs zu achten ("ledger_folder_names"). Die Angabe dieser Bezeichnung ist auch zu Teil der XML-Dateien. 95% der Kunden verwenden die Default-Bezeichnungen von DATEV. 5% der Kunden verändern diese Default-Bezeichnungen aber auch.


    MUST: Die Bezeichung des Hauptbuchs ist zu überprüfen und ggf. in den XML-Dateien anzupassen.

    4. Übertragung der Dateien (Dokumente & Daten)

    In diesem Schritt werden alle Dateien einzeln per HTTP-POST-Request auf die Job-ID eingesendet und mit einem abschließendem HTTP-PUT-Request wird die Verarbeitung des Jobs angestoßen.

    POST https://accounting-dxso-jobs.../clients/{client-id}/dxso-jobs/{job-id}/files

    Übertragung der einzelnen Dateien zu einer Job-ID.


    PUT https://accounting-dxso-jobs.../clients/{client-id}/dxso-jobs/{job-id}

    Verarbeitung der Job-ID im DATEV-Rechenzentrum initiieren.

    MUST: Die Dateien eines Jobs dürfen max.150 MB groß sein und eine Einzeldatei max. 20MB
MUST: Verwendung von ASCII-Zeichen für alle Dateinamen eines Jobs
SHOULD: Rechnungen und Kassendaten sollten immer gebündelt über einen Job übermittelt werden (sofern zu einem Hauptbuch & Monat zusammengehörig) um das Ratelimit nicht unnötig zu belasten.

    Challenges:
    • Berater lässt mehrere Rechnungen eines Monats übertragen.

    5. Ergebnis der Übertragung prüfen

    Die API ermöglicht hier einerseits die Prüfung eines rudimentären Job-Status und andererseits eines ausführlicheren Verarbeitungsprotokolls nachdem der Job verarbeitet wurde.

    GET https://accounting-dxso-jobs.../clients/{client-id}/dxso-jobs/{job-id}

    Abfrage des Verarbeitungsstatus für einen Job.
    Bitte beachten: Unsere Sandbox liefert hier ausschließlich den Verarbeitungsstatus "4" zurück.


    GET https://accounting-dxso-jobs.../clients/{client-id}/dxso-jobs/{job-id}/protocol-entries

    Abfrage eines detaillierten Verarbeitungsprotokolls nach Verabeitung des Jobs (entspricht dem Importprotokoll aus DATEV Belege online).

    MUST: Beide GET-Requests sind zu nutzen. Dem API-User ist unmittelbar nach der Datenübertragung das Verarbeitungsergebnis transparent zu machen und in geeigneter Weise zu dokumentieren/protokollieren.
MUST: Im Protokoll der 3rd-Party App muss sowohl der Verarbeitungsstatus (GET 1) als auch das Verarbeitungsprotokoll (GET 2) längerfristig einsehbar und gespeichert werden (mind. 1 Jahr).

    Challenges:
    • Berater lässt sich das Protokoll der 3rd-Party App zeigen und prüft, ob die Rückgabewerte mit den vorgefertigten Daten der Sandbox übereinstimmen.


    CHANGELOG

    Version

    Datum

    Änderungen
    1.1 19.10.2023 MUST für Bündelung mehrerer Rechnungen zu einem Job auf SHOULD geändert
    1.0 03.04.2023 Erstveröffentlichung