Schnittstellenvorgaben für Belegbilderservice Rechnungswesen

Mit dem DATEV Belegbilderservice Rechnungswesen können Sie digitale Belegbilder nach DATEV Unternehmen online übertragen. Nachfolgend wird der (reguläre) API Workflow aufgezeigt und welche Online-APIs & Endpunkte im Zusammenhang mit dem Datenservice verwendet werden müssen/sollten. Die Schnittstellenvorgaben werden getrennt nach Ebene Sandbox und Produktion aufgeführt.

API WORKFLOW

  1. Prüfung der Berechtigungen für den Datenservice
  2. Abfrage der Metadaten (z.B. angelegte Dokumenttypen) aus DATEV Belege online
  3. Übertragung einzelner Dateien/Dokumente - manuell (per Klick über 3rd-Party App) oder automatisiert (regelbasiert)
  4. (wiederkehrend) Überprüfung der Berechtigungen & Metadaten unmittelbar vor einer Übertragung
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/)

Berechtigungen prüfen

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

Hier können die Datenbestände abgefragt werden, auf die der Kunde die nötigen 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.

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.

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.


Challenges:

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


Metadaten holen

GET https://accounting-documents.../clients/{client-id}/document-types

Nutzen Sie diesen Endpunkt, um die verfügbaren Dokument-Typen aus dem Mandantenbestand abzufragen. Dokument-Typen können vom Anwender gelöscht oder umbenannt werden. Das Verwenden gelöschter/umbenannter Dokument-Typen führt bei der Übermittlung zu einem 400er-Fehler.

MUST: Der Endpunkt ist zu nutzen und die Informationen sind dem Kunden transparent anzuzeigen. Versichern Sie sich vor jeder Datenübertragung, dass die Dokument-Typen unverändert bestehen. Ein einmaliges Abfragen am Tag der Datenübertragung ist ausreichend.
MUST: Zeigen Sie im Review auf, wie die Überleitung zwischen den Dokument-Typen aus Ihrer App und Belege online erfolgt.
DONT: Vor jeder einzelnen Übertragung eines Belegs die Dokument-Typen prüfen.


Dokument(e) übertragen

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

Dieser Endpunkt dient der einzelnen Übermittlung eines Dokuments. Für jedes Dokument ist zusätzlich ein Metadaten-Objekt (JSON) Namens "metadata" zu übermitteln. Metadata enthält insgesamt 5 Datenfelder von denen 2 (document_type, note) für den Belegbilderservice Rechnungswesen relevant sind.

MUST: Zeigen Sie eine erfolgreiche Übertragung von mindestens zwei Belegen mit jeweils unterschiedlichem Dokument-Typ. Das Datenfeld "document_type" aus dem Objekt "metadata" ist für jedes Dokument zu übertragen.
MUST: Das Dokument muss mit einer gut lesbaren Qualität in Belege online ankommen. Die OCR aus Belege online muss alle Werte aus den Dokumenten sicher erkennen. Die Kunden erwarten gut lesbare Dokument die gleichzeitig ein geringes Speichervolumen aufweisen. Höhere Speichervolumen verursachen nicht nur Kosten bei DATEV sondern kosten vor allem (Lade-)Zeit beim Aufruf der Dokument über die DATEV Apps. Zeigen Sie auf, welche Komprimierungsverfahren für Dokument in Ihrer 3rd-Party App angewendet werden.
SHOULD: Das Datenfeld "note" kann für die Übermittlung einer Notiz genutzt werden
DONT: Verwendung 'hardgecodeter' Dokument-Typen in Metadaten-Objekt
DONT: Verwendung einer der anderen 3 Datenfelder (category, folder, register)


Challenges:

  • Berater verändert Dokument-Typ im Belege online und prüft, wie die 3rd-Party App darauf reagiert.
  • Berater lässt ein bestimmtes Dokument in der 3rd-Party-App bereitstellen und stößt die Übermittlung an


PUT https://accounting-documents.../clients/{client-id}/documents/stapled

Dieser Endpunkt dient der Übermittlung von mehreren, einzelnen Dokumenten, welche in Belege online als ein zusammengehörendes Dokument angezeigt werden sollen. Hierbei erfolgt pro PUT-Request dann eine logische Verknüpfung (heften, klammern) aller Einzeldokumente.


Grundsätzlich kann man als 3rd-Party-App selbst entscheiden, ob man mehrseitige Dokumente physisch zu einem einzelnen Dokument verschmilzt (d.h. zu einer Datei) und dann den POST nutzt oder stattdessen alle Einzeldokumente über diesen PUT übermittelt. Der Vorteil vom PUT ist, dass der Kunde die logische Verknüpfung eines Dokuments in Belege online jederzeit lösen und neu verbinden kann. Kommt es bspw. zu einem maschinengesteuerten Scan-Fehler, wo der Rechnungsumbruch nicht korrekt erkannt wird, dann kann die Verwendung vom PUT dem Kunden den Aufwand zum erneuten Einscannen ersparen.
Ein weiterer Anwendungsfall für diesen Endpunkt sind Dokumente, welche einzeln mehr als 20MByte (= Max. Größe pro Dokument in Belege online) groß sind. In diesem Fall könnte das Dokument aufgeteilt und logisch verknüpft übermittelt werden.

PUT https://accounting-documents.../clients/{client-id}/documents/{id}

Kein Endpunkt zum Updaten von Dokumenten! Wird hauptsächlich für andere DATEV Datenservice verwendet. Kann aber optional als Alternative zum POST genutzt werden. Einziger Unterschied zum POST: man kann mit dem PUT selbst festlegen, mit welcher GUID das Dokument in Belege online gespeichert wird.


ONLINE API & ENDPUNKTE für PRODUKTION

(Base URL: https://api-name.api.datev.de/platform/)

Berechtigungen prüfen

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

Hier können die Datenbestände abgefragt werden, auf die der Kunde die nötigen 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.

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.

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.


Challenges:

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



Metadaten holen

GET https://accounting-documents.../clients/{client-id}/document-types

Nutzen Sie diesen Endpunkt, um die verfügbaren Dokument-Typen aus dem Mandantenbestand abzufragen. Dokument-Typen können vom Anwender gelöscht oder umbenannt werden. Das Verwenden gelöschter/umbenannter Dokument-Typen führt bei der Übermittlung zu einem 400er-Fehler.

MUST: Der Endpunkt ist zu nutzen und die Informationen sind dem Kunden transparent anzuzeigen. Versichern Sie sich vor jeder Datenübertragung, dass die Dokument-Typen unverändert bestehen. Ein einmaliges Abfragen am Tag der Datenübertragung ist ausreichend.
MUST: Zeigen Sie im Review auf, wie die Überleitung zwischen den Dokument-Typen aus Ihrer App und Belege online erfolgt.
DONT: Vor jeder einzelnen Übertragung eines Belegs die Dokument-Typen prüfen.


Dokument(e) übertragen

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

Dieser Endpunkt dient der einzelnen Übermittlung eines Dokuments. Für jedes Dokument ist zusätzlich ein Metadaten-Objekt (JSON) Namens "metadata" zu übermitteln. Metadata enthält insgesamt 5 Datenfelder von denen 2 (document_type, note) für den Belegbilderservice Rechnungswesen relevant sind.

MUST: Zeigen Sie eine erfolgreiche Übertragung von mindestens zwei Belegen mit jeweils unterschiedlichem Dokument-Typ. Das Datenfeld "document_type" aus dem Objekt "metadata" ist für jedes Dokument zu übertragen.
MUST: Das Dokument muss mit einer gut lesbaren Qualität in Belege online ankommen. Die OCR aus Belege online muss alle Werte aus den Dokumenten sicher erkennen. Die Kunden erwarten gut lesbare Dokument die gleichzeitig ein geringes Speichervolumen aufweisen. Höhere Speichervolumen verursachen nicht nur Kosten bei DATEV sondern kosten vor allem (Lade-)Zeit beim Aufruf der Dokument über die DATEV Apps. Zeigen Sie auf, welche Komprimierungsverfahren für Dokument in Ihrer 3rd-Party App angewendet werden.
SHOULD: Das Datenfeld "note" kann für die Übermittlung einer Notiz genutzt werden
DONT: Verwendung 'hardgecodeter' Dokument-Typen in Metadaten-Objekt
DONT: Verwendung einer der anderen 3 Datenfelder (category, folder, register)


Challenges:

  • Berater verändert Dokument-Typ im Belege online und prüft, wie die 3rd-Party App darauf reagiert.
  • Berater lässt ein bestimmtes Dokument in der 3rd-Party-App bereitstellen und stößt die Übermittlung an


PUT https://accounting-documents.../clients/{client-id}/documents/stapled

Dieser Endpunkt dient der Übermittlung von mehreren, einzelnen Dokumenten, welche in Belege online als ein zusammengehörendes Dokument angezeigt werden sollen. Hierbei erfolgt pro PUT-Request dann eine logische Verknüpfung (heften, klammern) aller Einzeldokumente.


Grundsätzlich kann man als 3rd-Party-App selbst entscheiden, ob man mehrseitige Dokumente physisch zu einem einzelnen Dokument verschmilzt (d.h. zu einer Datei) und dann den POST nutzt oder stattdessen alle Einzeldokumente über diesen PUT übermittelt. Der Vorteil vom PUT ist, dass der Kunde die logische Verknüpfung eines Dokuments in Belege online jederzeit lösen und neu verbinden kann. Kommt es bspw. zu einem maschinengesteuerten Scan-Fehler, wo der Rechnungsumbruch nicht korrekt erkannt wird, dann kann die Verwendung vom PUT dem Kunden den Aufwand zum erneuten Einscannen ersparen.
Ein weiterer Anwendungsfall für diesen Endpunkt sind Dokumente, welche einzeln mehr als 20MByte (= Max. Größe pro Dokument in Belege online) groß sind. In diesem Fall könnte das Dokument aufgeteilt und logisch verknüpft übermittelt werden.


PUT https://accounting-documents.../clients/{client-id}/documents/{id}

Kein Endpunkt zum Updaten von Dokumenten! Wird hauptsächlich für andere DATEV Datenservice verwendet. Kann aber optional als Alternative zum POST genutzt werden. Einziger Unterschied zum POST: man kann mit dem PUT selbst festlegen, mit welcher GUID das Dokument in Belege online gespeichert wird.



CHANGELOG

Version

Datum

Änderungen
1.0 03.04.2023 Erstveröffentlichung