Migration auf neues API-Management - Informationen für bestehende API-Integrationen

DATEV hat damit begonnen, die Infrastruktur für ein neues API-Management in Betrieb zu nehmen. Da es dabei zu mehreren Breaking Changes kommt und eine automatische Migration der bestehenden Integrationen nicht möglich ist, haben wir auf dieser Seite alle Informationen und Unterstützungsangebote für bestehende API-Integrationen zusammengestellt.
 

Allgemeine Informationen

  • Die Migration der Integrationen auf das neue API-Gateway kann für Online-APIs
    • im Bereich Accounting und Human Ressource ab 03.04.2023 starten
    • im Bereich My Tax werden wir Sie bei einer bestehenden API-Integration direkt kontaktieren
    • im Bereich Cash Register werden wir Sie bei einer bestehenden API-Integration direkt kontaktieren
       
  • Alle Migrationen müssen bis 31.03.2024 abgeschlossen & von DATEV abgenommen sein. Ab dem 01.04.2024 wird nur noch das neue API-Gateway zur Verfügung stehen. Integrationen auf dem alten API-Gateway werden ab diesem Zeitpunkt nicht mehr funktionieren.
     
  • Die wichtigsten Änderungen haben wir weiter unten auf dieser Seite zusammengestellt:
    Migration auf neues API-Management - Changes
     

Ablauf & Unterstützungsangebote

Als DATEV-Partner können Sie ab dem 03.04.2023 mit der Migration beginnen.

 

WICHTIG: DATEV bietet nun auch allen anderen Softwareherstellern (d.h. Nicht-Partnern) die Möglichkeit an, die DATEV-Datenservices über das neue API-Gateway anzubinden. Für diese Softwarehersteller hat DATEV ein neues Registrierungsformular für die API-Integration geschaffen und an verschiedenen Stellen im DATEV Developer Portal verlinkt. Als DATEV Marktplatz-Partner ist für Sie keine Registrierung erforderlich!

 

Als Partner sieht der Ablauf der Migration wie folgt aus:

  1. Selbststudium der bereitgestellten Informationen:
    Leiten sie die nötigen Anpassungen in ihrer Integration aufgrund folgender Änderungen bei DATEV ab:
  2. Erstberatung zur Migration:
    Wir legen gemeinsam mit Ihnen im Developer Portal Ihren API-Client an und konfigurieren diesen passend für Ihre API-Integration. Der DATEV-Berater gibt Ihnen dann einen aktuellen Überblick, worauf Sie bei der Migration achten müssen. Abschließend können noch Ihre individuellen Fragen geklärt werden.
    Zur Buchung der Erstberatung (Dauer: 1 Stunde, kostenfrei)
     
  3. Umsetzung aller relevanten Änderungen:
    Sie setzen die relevanten Änderungen in Ihrer API-Integration um. Bei Bedarf können Sie weitere Zusatzberatungen buchen.
     
  4. Termin(e) für Technische Prüfung(en) buchen:
    Nach der Erstberatung erhalten sie eine Zusammenfassung von DATEV, welche Technische Prüfung(en) für sie noch erforderlich sind. Beachten sie, dass mindestens die Technische Prüfung Produktion auf Basis des neuen API-Gateways und der aktualisierten DATEV-Schnittstellenvorgaben zu wiederholen ist.
     
  5. Integration bis 31.03.2024 auf neues API-Gateway umstellen:
    Nachdem sie die unbefristete Freigabe für die Produktion erhalten haben, können sie damit beginnen alle Kunden auf die neue Integration umzuziehen. Beachten sie hierbei insbesondere, dass alle "umzuziehenden" Kunden auch neue Tokens für ihre Software ausstellen müssen.

Migration auf neues API-Management - Changes

Breaking Changes

  • Änderung von Client-ID & Client-Secret inkl. Token-Reset

    Alle Softwarehersteller müssen sich mit Freigabe der neuen Funktionen im DATEV Developer Portal einen API-Client per Self-Service selbst erzeugen. Dieser API-Client funktioniert dann ausschließlich für das neue API-Gateway und ersetzt die alten Credentials (Client-ID + Client-Secret)

    Wichtig i.V.m. Langzeittoken: Für die Nutzung des neuen API-Clients müssen die Anwender erneut die Authentifizierung durchlaufen. Eine erneute Registrierung und Rechtefreischaltung ist nicht erforderlich.

     

  • Neues URL-Konzept

    Bei allen Online-APIs ändern sich die URLs. Statt wie bisher https://(sandbox-)api.datev.de/<api-domain>/<version>... werden die APIs zukünftig auf URLs gem. dem Schema https://<api-domain>.api.datev.de/platform(-sandbox)/<version>... zu finden sein.

     

  • Neuer Default-Header

    Es ist immer der Header-Parameter "X-Datev-Client-Id" anzugeben. Einzutragen ist hier die Client-Id vom API-Client.

 

Non-Breaking Changes

  • Neues Rate-Limit

    Das bisherige Rate-Limit ist an die Access-Tokens gekoppelt. Das Rate Limit im alten Gateway beträgt pauschal 500 Requests/Minute/Token. Im neuen Gateway ist das Rate-Limit an den API-Client und dessen abonnierte Online-APIs gekoppelt. Somit kann ein API-Client auch unterschiedliche Rate-Limits pro Online-API haben und dies über alle Anwender des API-Clients hinweg. Diese geänderte Logik führt evtl. zu nötigen Anpassungen in ihrer Schnittstellen-Integration.

     

  • Validierung auf YAML-Specification

    Die neue API-Infrastruktur führt automatisch bei eingehenden APIs-Call eine Validierung auf Basis der publizierten YAML-Dateien durch. Dies war in der bestehenden API-Infrastruktur nicht durchgehend der Fall weswegen das Verhalten der tatsächlichen API im Backend und der API im Frondend (YAML) abweichen konnten. Unter Umständen ist also damit zu rechnen, dass der bisherige Code trotz Berücksichtigung der zuvor genannten Breakings nicht funktioniert. In diesem Fall sollte die neue YAML-Datei noch einmal genauestens geprüft werden.

     

  • Effizienz der Integration

    Das neue API-Gateway ist auch die Basis für eine nutzungsgerechte Verrechnung der Kosten, die der jeweilige Softwarehersteller verursacht. Von daher sollte bei dieser Gelegenheit direkt überprüft werden, ob das Call-Verhalten der Online-API-Integration auch wirtschaftlich ist. Die Inbetriebnahme der nutzungsgerechten Verrechnung ist allerdings erst zu einem späteren Zeitpunkt angedacht.