Leitfaden für Entwickler - Umstellung der Datev Connect API von V2 auf V3.1

Disclaimer

Ursprünglich sollten Entwickler der Datev Connect API V2 direkt auf die nächste Version V3.0 umstellen. Da es leider zu einigen Fehlerkonstellationen in der API V3.0 kam, wurde eine Verwendung dieser Version nicht empfohlen. Für die API V3.0 wird daher kein Support geleistet und alle Nutzer der Schnittstelle sollen auf die Version 3.1 umstellen.

Dadurch haben sich manche Punkte im Changelog V3.0 zur V3.1 wieder geändert. So gab es z.B. ursprünglich in V3.0 keine POST Batch-Endpunkte mehr für Bewegungsdaten, welche zur V3.1 leicht verändert wieder aufgenommen wurden. Dieser Leitfaden soll dazu dienen, die wichtigsten Änderungen von V2 auf V3.1 darzustellen und Entwicklern die Umstellung auf die neue API-Version zu erleichtern. Die detaillierte Übersicht der Änderungen finden Sie weiterhin im Changelog.

Wichtigste Änderungen von V2 zu V3.1

Typsicherheit erhöht

Einige Datentypen von Feldern der API wurden typsicherer angepasst und dass entsprechend der Erfassung an der Oberfläche in Lohn und Gehalt. So wurde z.B. das Feld id der Ressource salary-type von string auf integer angepasst, da das Feld immer einem Zahlenwert entspricht. Das führt dazu, dass insgesamt mehr Client-Validierungen der Daten möglich sind und nicht erst durch die Schnittstelle in Lohn und Gehalt abgelehnt werden. Dadurch kann es notwendig sein, in manchen Teilen der Client-Implementierung Datentypen anzupassen.

Bewegungsdaten POST Batch-Endpunkte

Um die Dopplung der Ressourcen calendar-records und month-records in den POST Batch-Endpunkten zu vermeiden, wurden die Ressourcen calendar-reords-batch und month-records-batch entfernt. Das Payload unterscheidet sich nicht mehr zwischen Batch und Single-Endpunkt. Daher wurde der Aufruf der POST Batch-Endpunkte verschoben: Aufruf mit Endung /batch, z.B. /clients/{client-id}/calendar-records/batch. Diese Änderungen können zu Anpassungen der Implementierung führen.

Ressource gross-payment

Das Feld payment_months wurde entfernt und das Feld payment_intervalhinzugefügt. Diese Änderung war notwendig, um die API weiter an die interne Logik von Lohn und Gehalt anzupassen. Die Verwendung der API soll sich weitestgehend an der Bedienung der Oberfläche von Lohn und Gehalt orientieren. Da intern nur Abrechnungsintervalle bekannt sind, wurde hier auch die API-Logik angepasst. Das kann zu Änderungen der fachlichen Logik in der Client-Implementierung führen.

Ressource individual-data

Die Ressource wurde zur Verkürzung der URI direkt unterhalb der Ressource employee anstatt personal-data aufgehangen. Der Aufruf des Endpunkts muss daher möglicherweise angepasst werden.

Mitarbeiterneuanlage

Um die Dopplung der Ressourcen employee und new-employee zu vermeiden, wurde letztere Ressource entfernt. Für die Anlage eines neuen Mitarbeiters wurde ein POST auf die Ressource employee möglich gemacht. Dies kann zu kleinen Anpassungen in der Client-Implementierung führen.

Ressource processing-key

Die Ressource wurde alternativlos entfernt, da diese nur in Verwendung mit dem Lohnprodukt Lodas möglich war und die Payroll-API ausschließlich für das Produkt Lohn und Gehalt entwickelt wird.

Ressource accountable-employee

Das Feld personnel_number wurde entfernt, da es identisch zu dem Feld id ist. Eine Umstellung auf das Feld id kann daher notwendig sein.

Ressource personal-data

Die Behebung des Rechtschreibfehlers von martial_status zu marital_status kann eine kleine Umstellung der Client-Implementierung benötigen.

Addendum

Dieser Leitfaden soll als Unterstützung bei der Umstellung auf die neue API-Version 3.1 dienen. Möglicherweise ist dieser nicht ganz komplett. Außerdem werden hier nur Änderungen aber nicht neu hinzugefügte Features aufgeführt. Daher ist ein Blick in die Changelogs der Versionen 3.0 und 3.1 dringend zu empfehlen. Insgesamt wurde die technische Basis ab API V3.0 erneuert, was außer neuen Features auch zu Performanceverbesserungen, Möglichkeiten der Optimierung der Client-Implementierung und verbessertem Fehlerhandling führt.