Schnittstellenvorgaben

Jede neue Online-API Integration einer 3rd-Party App hat einen Freigabeprozess gemeinsam mit der DATEV zu durchlaufen. Die Schnittstellenvorgaben umfassen alle Anforderungen, die seitens DATEV an die Integration durch den API-Consumer gestellt werden.

Damit möchten wir sicherstellen, dass:

  • unsere DATEV-Kunden bei allen 3rd-Party Apps eine gewisse Mindestqualität der Integration erwarten können
  • die Infrastruktur für das DATEV API-Gateway verantwortungsvoll eingesetzt wird
  • ein möglichst geringes Support- & Serviceaufkommen für alle Beteiligten gewährleistet wird (Softwarehersteller, Kunde, DATEV-Mitglied, DATEV)
  • die Softwarehersteller bereits eine erste Orientierung anhand von Best Practices bekommen

Innerhalb der Schnittstellenvorgaben arbeiten wir mit folgendem Bewertungsmaßstab für die Relevanz einer Anforderung:

MUST: Diese Anforderungen sind für eine Freigabe der Integration zwingend umzusetzen.
SHOULD: DATEV empfiehlt diese Punkte aufgrund von Erfahrungen/Best Practices/Kundenerwartungen. Diese Anforderung ist nicht zwingend für eine erfolgreiche Freigabe umzusetzen, sollte aber unbedingt zur Umsetzung in Betracht gezogen werden.
DONT: Diese Punkt sind unbedingt zu vermeiden und gefährden eine erfolgreiche Freigabe der Integration.
Jeder Softwarehersteller hat hierbei die:

VORAUSSETZUNGEN & VORBEREITUNG

Jede Freigabe einer Integration umfasst mindestens zwei gemeinsame Freigabetermine. Bevor ein API-Consumer in die Freigabetermine geht, sollte er gewisse Voraussetzungen beachten und Vorbereitungen treffen.

Schritt 1: Sandbox-Freigabe


Verläuft der Freigabetermin positiv, so erhält der API-Consumer für die nächsten 3 Monate den Zugang auf die Produktionsumgebung.

Schritt 2: Produktions-Freigabe

  • API-Integration auf Produktion umgesetzt & getestet
  • Integration im Zusammenspiel mit Ihrem DATEV-Testsystem getestet (Einbezug erster Kunden ist empfehlenswert)
  • Allgemeine & spezielle Schnittstellenvorgaben beachtet
  • ggf. vorhandene Dateiformate (CSV, XML, etc.) der API-Integration sind abgenommen (Terminbuchung)
  • Vorbereitung von Testbeständen mit Testdaten (Rechnungen, Daten, Dokumente, etc.) für die beteiligten Apps
    Wichtig: Im Rahmen der technischen Prüfung dürfen keine Echtbestände oder Echtdaten verwendet werden!
  • Buchung eines Freigabetermins

Wird die Integration in der Produktion freigegeben, wird die Befristung des Zugangs entfernt und der API-Consumer kann seine Integration bei all seinen Kunden in Betrieb nehmen.

ABLAUF DER FREIGABE

Die Freigabetermine der Integration erfolgen über eine gemeinsame Videokonferenz. Der Softwarehersteller präsentiert seinen Bildschirm und zeigt dem DATEV-Berater die neue Schnittstelle in seiner App. Der Berater moderiert die Videokonferenz und führt den Softwarehersteller durch den Termin. Entlang des Termins stellt der Berater verschiedene Fragen und Challenges, die den Nachweis der Einhaltung der Schnittstellenvorgaben erbringen sollen. Parallel prüft der Berater die im DATEV API-Gateway erzeugten Log-Sätze auf Konformität. In der Produktions-Freigabe wird zusätzlich auch der erfolgreiche Datenaustausch mit den DATEV Apps geprüft.

ALLGEMEINE SCHNITTSTELLENVORGABEN

Für die Nutzung unseres DATEV API-Gateways und der dahinterliegenden Online-APIs haben wir bestimmte Anforderungen, die dem Eingangs erläutertem Zweck dienen sollen.

Ökonomie & Ökologie

Jede Kommunikation über unser DATEV API-Gateway verbraucht Ressourcen (Strom, Infrastruktur, usw.). Die Nutzung unseres Gateways ist für API-Consumer (Softwarehersteller) derzeit kostenfrei. Wir legen aber trotzdem Wert auf einen achtsamen, verhältnismäßigen Umgang mit unserem API-Gateway. Integrationen, die 24/7 (rund um die Uhr) pauschal API-Calls absetzen ohne konkretes Kundeninteresse, sind grundsätzlich nicht gestattet. Bauen Sie Ihre DATEV-Schnittstelle so auf, dass nur solche API-Calls abgesetzt werden, die der Kunde unmittelbar vorher angefordert hat (z.B. manuell per Klick oder regelbasiert). Ausnahmen hiervon können im Rahmen der Freigabegespräche individuell besprochen werden.

DONT: Integration von 24/7 (rund um die Uhr) Pollings.


Support

Wir unterscheiden hier in Support, welcher durch den API Consumer gegenüber dem API User erbracht wird und dem Support, welcher seitens DATEV gegenüber dem API Consumer erbracht wird.

Der API-Consumer hat seinen API Usern einen First Level Support für seine DATEV-Schnittstellen anzubieten. DATEV erwartet, dass sich der Softwarehersteller mit den gemeldeten Problemen seiner API User auseinander setzt und in die Analyse geht. Sollte sich bei der Analyse rausstellen, dass keine unmittelbare Abhilfe durch den API Consumer selbst möglich ist, dann sind dem API User gezielte Selbsthilfemedien der DATEV zu präsentieren (z.B. Allgemein aus DATEV Hilfe-Center oder zur Ersteinrichtung DATEV-Datenservices).

Damit es erst gar nicht zum Support-Fall beim API User kommt, erwarten wir ein solides Fehlermanagement in der 3rd-Party App. DATEV gibt bei allen Fehlercodes im HTTP 4XXer-Bereich zusätzlich eine standardisierte Error-Messages im Response-Body mit URLs zur Fehlerabhilfe an. Diese URLs lösen bestenfalls direkt das Problem des API Users oder zeigen ihm zumindest auf, wer der richtige Ansprechpartner ist (3rd-Party App/DATEV/DATEV-Mitglied). Welche HTTP-Codes eine API alles wirft, ist über die API-Dokumentation ersichtlich.

Der API-Consumer kann sich bei technischen Problemen mit dem DATEV API-Gateway ein Ticket bei DATEV eröffnen: https://www.terminland.de/datev_schnittstellenberatung/online/ticket (30min)

Weiterhin können bei komplexen Fragen oder zur gemeinsamen Fehleranalyse jederzeit Beratungen via Videokonferenz gebucht werden: https://www.terminland.de/datev_schnittstellenberatung/ (60min)

MUST: 4XXer Fehlercodes sind zu behandeln. Mindestens die Hilfs-URL ist im UI anzuzeigen oder ein andere Hilfestellung zu leisten. Uns ist bewusst, dass ein solides Fehlermanagement nicht an einem Tag entsteht. Wir möchten eine gewisse Basis sehen und erwarten nach Freigabe die kontinuierliche Verbesserung des Fehlermanagements.
MUST: Der API Consumer nutzt für seinen Supportbedarf das Ticketsystem der DATEV und kommt seinen Mitwirkungspflichten nach.
DONT: Direkte verweise auf DATEV oder die DATEV-Mitglieder bei Problemen mit der Integration. Sollte ein Softwarehersteller hier mehrfach bei DATEV auffällig werden, wird die Freigabe überprüft.


Technischer Log

Um bei Problemen während der Implementierung oder im Live Betrieb bestmöglich unterstützen zu können, muss der API-Consumer ein technischen Log für HTTP-Requests & -Responses integrieren. Treten unerwartete Fehler oder Fragen für einen HTTP-Request auf, dann werden diese Logs für die Eröffnung eines Tickets und die weitere Analyse bei DATEV benötigt. Die Logs für HTTP-Fehlercodes (4XXer/5XXer) müssen mind. 14 Tage vom API-Consumer aufbewahrt werden. Das Log muss mind. folgende Werte aufzeichnen:

HTTP-REQUEST
  • Zeitstempel (mind. hh:mm:ss)
  • HTTP-Verb/Methode + vollständige URL/angesprochener Endpoint (z.B. GET https://<domain+path>/clients)
  • HTTP-Header (ohne Authorization Header!)
  • HTTP-Body inkl. Payload (Datei muss nicht extra geloggt werden aber bei Bedarf verfügbar sein)

HTTP-RESPONSE

  • HTTP-Header insb. "Global-Transaction-ID"
  • HTTP-Code + Message
  • HTTP-Body, wenn vorhanden
MUST: Der API-Consumer muss einen technischen Log implementieren. HTTP-Fehlercodes (4XXer/5XXer) sind mind. 14 Tage aufzubewahren.


Sicherheit

Für die Authentifizierung und Autorisierung in unserem API-Gateway haben wir die Web Standards OAuth 2.0 (inkl. PKCE) und OIDC Hybrid Flow implementiert. Diese Standards bieten diverse Sicherheitsmechanismen an, welche vom Softwarehersteller zu nutzen sind. Für diese Web Standards existieren diverse öffentliche SDKs/Librarys (z.B. https://openid.net/developers/libraries/) für so ziemlich alle Programmiersprachen. Nutzen Sie diese Möglichkeit, da eine Eigenentwicklung hier ansonsten sehr aufwändig und ggf. nicht allen Sicherheitsaspekten gerecht werden wird.
MUST: Validieren Sie das id_token gegen die bereitgestellten Zertifikate
MUST: Body-Parameter code_challenge, code_verifier und nonce sind bei jedem Request neu zu generieren/berechnen


Sensible Daten

Die Kommunikation mit dem DATEV Rechenzentrum erfordert verschiedene Authentifizierungs- und Autorisierungsvorgänge. Behandeln Sie die hier ausgetauschten Daten streng vertraulich. Dabei handelt es sich um:
  • Client-ID für den API Client (niedriger Schutzbedarf, da bei Webservice Kommunikation in URL lesbar)
  • Client-Secret für den API Client (hoher Schutzbedarf)
  • Access-& Refresh-Token (höchster Schutzbedarf)
MUST: Daten mit höherem Schutzbedarf sind immer auf Basis aktueller Techniken zu verschlüsseln.
DONT: Daten mit höherem Schutzbedarf dürfen zu keiner Zeit im UI des API-Users angezeigt oder mit geloggt werden


Authentifizierung & Autorisierung

Für unsere DATEV-Datenservices haben wir einen OAuth 2.0 & OpenID connect Hybrid Flow implementiert. Das Access-Token (AT) hat eine Standard-Haltbarkeit von 15 Minuten. Beim Refresh-Token (RT) unterstützen wir zwei Varianten:
  • Kurzzeit-RT:
    - Haltbarkeit von 11 Stunden
    - Keine Verlängerung der Haltbarkeit bei Token-Refresh
    - Unbegrenzte Anzahl an Token-Refreshs pro RT
    - Immer nur 1 gültiges AT pro RT, d.h. Token-Refresh invalidiert letztes AT & RT
    - Zugriff auf alle Datenbestände, die für die DATEV-Identität freigegeben sind

  • Langzeit-RT:
    - Haltbarkeit von 2 Jahren
    - Verlängerung der Haltbarkeit bei Token-Refresh auf erneut 2 Jahre
    - Unbegrenzte Anzahl an Token-Refreshs pro RT
    - Immer nur 1 gültiges AT pro RT, d.h. Token-Refresh invalidiert letztes AT & RT
    - Zugriff auf einen Datenbestand, die für die DATEV-Identität freigegeben ist

Je nachdem, welches Refresh-Token seitens des API-Consumers unterstützt wird, müssen auch verschiedene Erwartungen erfüllt werden.

Generell erwarten wir eine konsequente Trennung zwischen Verbindungsaufbau und Datenaustausch in der Benutzeroberfläche der 3rd-Party App. Die Benutzeroberfläche muss dabei bestimmte Anforderungen erfüllen.

MUST: Richten Sie einen eigenen Bereich in der Benutzeroberfläche für den Verbindungsaufbau, -abbau und -status ein, die alle nachfolgenden Punkte erfüllt.
MUST: Authentifizierungsprozess wird über eine separate Schaltfläche gestartet (z.B. "Mit DATEV verbinden")
MUST: errechnetes Haltbarkeitsdatum (mind. Format TT.MM.JJJJ HH:MM) vom RT ist ersichtlich
MUST: Verbindungsstatus auf Basis der errechneten Haltbarkeit vom Refresh-Token ist über eine Ampel oder bestimmte Schlagworte schnell ersichtlich (z.B. grüne/rote Ampel, "verbunden/getrennt", "Verbindung aktiv/inaktiv")
MUST: RT lässt sich über eine Schaltfläche löschen (z.B. "Verbindung trennen"), d.h. Löschung in der 3rd-Party App und Revoke-Call beim DATEV API-Gateway
MUST: Person (vollständiger Name), die das Token ausgestellt hat ist ersichtlich (via Userinfo-Endpoint)
MUST: DATEV App "Verbundene Anwendungen" (https://apps.datev.de/tokrevui) verlinkt
MUST: Nutzung des Token-Refreshs solange ein gültiges RT für den API-User vorhanden ist. Für einen API-User darf somit nie mehr als ein gültiges RT bei DATEV ausgestellt sein.
SHOULD: Token-Revoke (AT) unmittelbar nach dem Datenaustausch.

KURZZEIT - REFRESH TOKEN

MUST: Token-Revoke (RT) bei Logout in der 3rd-Party-App.

LANGZEIT - REFRESH TOKEN

MUST: Anzeige im Verbindungsstatus, für welchen Ordnungsbegriff/Datenbestand (= Parameter {client-id}) die Verbindung gilt
MUST: Zusätzliche Prüfroutine für den Verbindungsaufbau. Hier darf erst dann eine erfolgreiche Verbindung angezeigt werden, wenn die Online-API die Zugriffsrechte auf den Ordnungsbegriff/Datenbestand bestätigt hat. Hierzu wird üblicherweise eine GET /clients/{client-id} für jede API angeboten.


Zugriffsbereiche (Scopes)

Jede Online API kann ein oder mehrere Scopes besitzen. Ein Scope bildet einen bestimmten Use Case einer API ab, welcher aus Sicht des API Providers (DATEV) für den API User steuerungsrelevant ist. Umfasst eine API bspw. lesende und schreibende Use Cases, dann kann ein API User durchaus wünschen, dass ein API Consumer Daten für ihn an DATEV überträgt aber keine lesenden Zugriffe auf seine Daten im DATEV Rechenzentrum durchführt. Der API User bekommt die von der 3rd-Party App angeforderten technischen Scopes in einer übersetzten Form (Beschreibung des Use Cases inkl. Verb lesen/schreiben) in der Consent-Page angezeigt. Der API User kann hier aber keine einzelnen Scopes ablehnen. Er kann nur der Summe der angeforderten Scopes zustimmen oder ablehnen.

MUST: Beim Holen der Tokens dürfen immer nur jene Scopes angefordert werden, welche der Endkunde für eine Nutzung des Datenservices benötigt. Hat ein API Consumer mehrere Datenservices implementiert, dürfen nicht pauschal alle Scopes für alle Datenservices angefordert werden.


Rechte- & Rollenkonzept

Bei DATEV werden bestandsbezogene APIs über den URL-Parameter "…/{client-id}/…" angesprochen. Eine {client-id} (z.B. 123456-12345-123) kann unterschiedliche Entitäten darstellen (z.B. ein Mandat eines Steuerberaters, ein Mitarbeiter eines Mandats, etc.) und ist nur für die jeweilige API eineindeutig. Z.B. steckt hinter der {client-id} "123-456" bei einer Rechnungswesen-API nicht unbedingt die gleiche Entität wie bei {client-id} "123-456" für eine Personalwirtschafts-API (möglich wäre es aber). Die {client-id} ist für unsere APIs auch die Basis um zu prüfen, ob der API User, welcher das Token ausgestellt hat, alle nötigen Berechtigungen für die Nutzung der API und der angesprochenen Entität besitzt.

Die 3rd-Party App hat in der Regel eigene Entitäten und ein dahinterliegendes Rechte & Rollenkonzept. Es liegt in der Verantwortung des API Consumers dafür zu sorgen, dass er seine Entitäten den DATEV Entitäten eindeutig zu schlüsselt und die ausgestellten Tokens dementsprechend sorgfältig ablegt. Insbesondere bei der Verwendung des Langzeittoken (2 Jahre) ist darauf zu achten, dass einmal ausgestellte Tokens nicht unbedingt von jedem Benutzer der Entität (in der 3rd Party App) auch genutzt werden können. Gerade bei hochsensiblen APIs wie dem Zugriff auf Gehaltsdaten, sollte die 3rd-Party App selbst eine neue Rolle/Berechtigung für solche Zugriffe einführen.

MUST: Bei den Freigabeterminen ist darzulegen, wie die Entitäten mit den DATEV Entitäten zusammenspielen und wie der Umgang mit den Tokens geregelt ist.


Design

Grundsätzlich gelten zur Verwendung von DATEV-Logos/Wortmarken alle Regelungen aus den Nutzungsbedingungen des DATEV Developer Portals und zusätzlich die Regelungen aus den Schnittstellen-Verträgen. Die hier befindlichen Vorgaben sind teilweise zusätzlich aber auch teilweise redundant (und in o.g. Vereinbarungen bereits enthalten).

Die Wortmarke ist in der 3rd-Party App immer in Großbuchstaben abzubilden. Gegenüber den API Usern sind die Begriffe der DATEV Datenservices zu verwenden (keine Online APIs). Welche DATEV Datenservices verfügbar sind, muss dem API User in der 3rd-Party App klar ersichtlich gemacht werden. Je nachdem, welche DATEV Datenservices in der 3rd-Party App umgesetzt sind, müssen auch die Bezeichnungen der entsprechenden Datenservices korrekt wiedergegeben werden. Die korrekte Schreibweise lässt sich über unsere Übersicht der freigegebenen DATEV Datenservices ermitteln: DATEV-Datenservices.

Je nachdem, in welcher Form ein Softwarehersteller mit DATEV kooperiert, sind verschiedene Logos zugänglich. Jegliche Verwendung von DATEV-Logos muss mit DATEV vertraglich geregelt werden.

MUST: Die Vorgaben zu Wortmarke und Logos sind zwingend einzuhalten.

Architektur

Der über das DATEV Developer Portal generierte API-Client kann in verschiedenen Formen zur Kommunikation mit dem DATEV API-Gateway genutzt werden. Einen produktiven API-Client kann sich aber nicht jeder beliebige API-User generieren. Hier wären immer gemeinsame Freigabetermine mit DATEV erforderlich. Von daher muss sich der API-Consumer ein Konzept machen, wie er den API-Client sicher(!) für alle seine API-User zugänglich machen kann. Wird ein ungewöhnliche Nutzung durch einen API-Client am Gateway festgestellt, so wird mindestens der API-Client für die weitere Kommunikation mit dem DATEV API-Gateway gesperrt.

  • Webserver-Integration:
    Der API-Consumer betreibt selbst einen Webserver (oder nutzt einen Dienstleister) mit der App und dem integrierten API-Client. Jegliche Kommunikation mit dem DATEV API-Gateway wird über diesen zentralen Webserver gesteuert. Der API-Consumer benötigt für den OAuth-Flow i.d.R. nur eine Redirect URL (HTTPS). Der Parameter "state" vom Authorization-Call kann dazu verwendet werden um den API-User zu identifizieren und einen Redirect von DATEV dem korrekten Kunden zuzuordnen. Der Datenaustausch erfolgt ebenfalls zentrale über die IP des Webservers.

  • Hybrid-Integration (Webserver + Desktop/Mobil):
    Der API-Consumer betreibt selbst einen Webserver (oder lässt betreiben) mit einer App und dem integrierten API-Client. Die Kommunikation für die Tokens läuft zentral über diesen Webserver. Der API-Consumer benötigt für den OAuth-Flow i.d.R. nur eine Redirect URL (HTTPS). Der Webserver hat wiederum eine sichere Kommunikationsverbindung zu den einzelnen API-Usern mit einer Desktop-/Mobile App. Der Datenaustausch erfolgt entweder zentral über die IP des Webservers oder über die IP der Desktop-/Mobile App.

  • Desktop/Mobil-Integration:
    Der API-Consumer liefert die App an seine Kunden aus (App Stores, Download, DVD, etc.). Jegliche Kommunikation mit dem DATEV API-Gateway erfolgt von der Hardware und IP aus, wo der Kunde die App betreibt.


MUST: Bei den Freigabeterminen ist die gewählte Architektur darzulegen. Gehen Sie auf alle beteiligten Komponenten ein, die mit dem DATEV API-Gateway kommunizieren.



SPEZIELLE SCHNITTSTELLENVORGABEN

Unsere Online-APIs können für verschiedene DATEV-Datenservices verwendet werden. Ein DATEV-Datenservice kann die Integration ein oder mehrerer Online-APIs umfassen. Unsere Schnittstellenvorgaben für eine Online API sind abhängig vom jeweiligen DATEV-Datenservices, in dem sie verwendet werden.

Datenservices Rechnungswesen


Belegbilderservice

Mit dem DATEV Belegbilderservice Rechnungswesen können Sie digitale Belegbilder nach DATEV Unternehmen online übertragen.

Schnittstellenvorgaben

Dazugehörige Online-APIs:
  • accounting:documents
  • accounting:clients (optional)

Buchungsdatenservice

Mit dem DATEV Buchungsdatenservice können Sie strukturierte Stamm- und Bewegungsdaten (CSV) inkl. digitaler Belegbildverknüpfung nach DATEV Rechnungswesen übertragen. Für diesen Datenservice sind einerseits die Vorgaben für den Datenservice und andererseits die Vorgaben für das Dateiformat zu beachten.

Schnittstellenvorgaben für Buchungsdatenservice

Schnittstellenvorgaben für DTVF-Format

Dazugehörige Online-APIs:

  • accounting:extf-files
  • accounting:documents
  • accounting:clients

Rechnungsdatenservice 1.0

Mit dem DATEV Rechnungsdatenservice 1.0 können Sie digitale Belegbilder inkl. strukturierter Daten (XML) nach DATEV Unternehmen online übertragen. Für diesen Datenservice sind einerseits die Vorgaben für den Datenservice und andererseits die Vorgaben für das Dateiformat zu beachten.

Schnittstellenvorgaben Rechnungsdatenservice 1.0

Schnittstellenvorgaben für DXSO-Format

Dazugehörige Online-APIs:

  • accounting:dxso-jobs

Datenservices Personalwirtschaft


Lohnimportdatenservice

Der Lohnimportdatenservice unterstützt vorrangig den arbeitsteiligen Prozess zwischen Kanzlei und Mandanten bei der Übertragung von Bewegungsdaten und Stammdaten aus einer 3rd-Party App. Für diesen Datenservice sind einerseits die Vorgaben für den Datenservice und andererseits die Vorgaben für das Dateiformat zu beachten.

Schnittstellenvorgaben für Lohnimportdatenservice

Schnittstellenvorgaben für ASCII-Format

Dazugehörige Online-APIs:

  • hr:import

Lohnauswertungsdatenservice

Mit dem DATEV Lohnauswertungsdatenservice können Sie bereitgestellte Lohn-Auswertungen als PDF abrufen.

Schnittstellenvorgaben

Dazugehörige Online-APIs:

  • hr:payrollreports

Datenservices Steuern


Belegbilderservice

Mit dem DATEV Belegbilderservice Steuern können Sie Dokumente in die App DATEV Meine Steuern übermitteln.

Schnittstellenvorgaben

Dazugehörige Online-APIs:

  • my-tax:income-tax-documents


Login mit DATEV

"Login mit DATEV" ermöglicht es Softwareherstellern bei sich in der App einen Login auf Basis der DATEV Identität (inkl. Zwei-Faktor-Authentifizierung) anzubieten.

Schnittstellenvorgaben

Dazugehörige Online-APIs:

  • Userinfo-Endpoint