Schnittstellenvorgaben für Lohnimportdatenservice

Der Lohnimportdatenservice unterstützt vorrangig den arbeitsteiligen Prozess zwischen Kanzlei und Mandanten bei der Übertragung von Bewegungsdaten und Stammdaten aus einer Fremdsoftware in das DATEV-Lohnabrechnungsprogramm. Die vertraulichen Daten werden über eine sichere Verbindung im DATEV-Rechenzentrum für Lohn und Gehalt und LODAS bereitgestellt. Per Knopfdruck können die Daten in das Lohnabrechnungsprogramm eingespielt und für die nächste Lohnabrechnung verwendet werden. Nachfolgend wird der (reguläre) API Workflow aufgezeigt und welche Online-APIs & Endpunkte im Zusammenhang mit dem Datenservice verwendet werden müssen/sollten.

API WORKFLOW

1. Prüfung der Berechtigungen für den Datenservice
2. Übertragung einzelner Dateien - manuell (per Klick über 3rd-Party App) oder automatisiert (regelbasiert)

MUST: Übermittelte Dateien (POST) und lesende API-Requests (GET) sollten in einem gesunden Verhältnis sein. Auf ein erfolgreich übermittelte Datei 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://hr-files.../clients

GET https://hr-files.../clients/{client-id}

Hier können die Datenbestände abgefragt werden, auf die der Kunde die nötigen Berechtigungen hat. Die 3rd-Party App muss den zweiten Endpunkt nutzen. 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 muss der zweite Endpunkt genutzt werden. Hier muss der Kunde eine Eingabemöglichkeit in der 3rd-Party-App für die Berater- und Mandantennummer bekommen.

MUST: Es muss der zweite Endpunkt genutzt werden. Hier muss aufgezeigt werden, wo der Kunde seine Angaben für den Datenbestand macht. Zeigen Sie danach den Aufruf des Endpunktes mit einer Erfolgsmeldung. Ebenfalls muss ein Fehler reproduziert werden, indem eine Berater-und Mandantennummer verwendet wird, für die der Kunde keine Berechtigung hat. Hier muss eine entsprechende Fehlermeldung an der Oberfläche angezeigt werden. 

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 trägt eine korrekte Berater- und Mandantennummer ein und zeigt die Erfolgsmeldung
• Berater trägt eine ungültige Berater- und Mandantennummer ein und zeigt eine Fehlermeldung

Übertragung von Dateien

POST https://hr-files.../clients/{client-id}/files

Nutzen Sie diesen Endpunkt, um die Dateien an das DATEV Rechenzentrum zu übermitteln. Wenn die Schnittstelle für Stammdaten und Bewegungsdaten genutzt wird, muss einmal eine Stammdatendatei und eine Bewegungsdatendatei übermittelt werden. Ansonsten nur die Datei, die von der 3rd Party-App präferiert ist.     

MUST: Zeigen Sie eine erfolgreiche Übertragung der Dateien an das DATEV-Rechenzentrum.

Wichtiger Hinweis: In der Sandbox können die ASCII-Dateien nur an das DATEV-Rechenzentrum übertragen werden. Sie können danach nicht importiert werden. Diese Funktion gibt es nur in der Produktionsumgebung.

Status abfragen

GET https://hr-files.../clients/{client-id}/jobs/{job-id}

Dieser Endpunkt zeigt den jeweiligen Status der hochgeladenen Dateien an.     

SHOULD: Zeigen Sie den Status der übertragenden Dateien an der Oberfläche an.

ONLINE API & ENDPUNKTE für PRODUKTION

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

Berechtigungen prüfen

GET https://hr-files.../clients

GET https://hr-files.../clients/{client-id}

Hier können die Datenbestände abgefragt werden, auf die der Kunde die nötigen Berechtigungen hat. Die 3rd-Party App muss den zweiten Endpunkt nutzen. 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 muss der zweite Endpunkt genutzt werden. Hier muss der Kunde eine Eingabemöglichkeit in der 3rd-Party-App für die Berater- und Mandantennummer bekommen.

MUST: Es muss der zweite Endpunkt genutzt werden. Hier muss aufgezeigt werden, wo der Kunde seine Angaben für den Datenbestand macht. Zeigen Sie danach den Aufruf des Endpunktes mit einer Erfolgsmeldung. Ebenfalls muss ein Fehler reproduziert werden, indem eine Berater-und Mandantennummer verwendet wird, für die der Kunde keine Berechtigung hat. Hier muss eine entsprechende Fehlermeldung an der Oberfläche angezeigt werden. 

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 trägt eine korrekte Berater- und Mandantennummer ein und zeigt die Erfolgsmeldung
• Berater trägt eine ungültige Berater- und Mandantennummer ein und zeigt eine Fehlermeldung

Übertragung von Dateien

POST https://hr-files.../clients/{client-id}/files

Nutzen Sie diesen Endpunkt, um die Dateien an das DATEV Rechenzentrum zu übermitteln. Wenn die Schnittstelle für Stammdaten und Bewegungsdaten genutzt wird, muss einmal eine Stammdatendatei und eine Bewegungsdatendatei übermittelt werden. Ansonsten nur die Datei, die von der 3rd Party-App präferiert ist.     

MUST: Zeigen Sie eine erfolgreiche Übertragung der Dateien an das DATEV-Rechenzentrum. Danach zeigen Sie den Import in die DATEV-Lohnprogramme.

Status abfragen

GET https://hr-files.../clients/{client-id}/jobs/{job-id}

Dieser Endpunkt zeigt den jeweiligen Status der hochgeladenen Dateien an.     

SHOULD: Zeigen Sie den Status der übertragenden Dateien an der Oberfläche an.

CHANGELOG

Version	Datum	Änderungen
1.0	03.04.2023	Erstveröffentlichung