Schnittstellenvorgaben für Lohnauswertungsdatenservice

Der DATEV Lohnauswertungsdatenservice ist eine DATEV online API-Lösung, die den arbeitsteiligen Prozess bei der Übertragung von Lohn- und Mandantenauswertungen in die Drittanbieter-Systemlandschaft unterstützt. Die Lohnauswertungen werden automatisiert und über eine sichere Verbindung aus dem DATEV-Rechenzentrum abgerufen. Die Daten werden mit der jeweiligen Lohnabrechnung im DATEV Rechenzentrum bereitgestellt. Voraussetzung für dieses Vorgehen ist eine Schnittstelle zwischen dem DATEV Lohnprogramm LODAS oder Lohn und Gehalt und der vom Unternehmen eingesetzten Lösung.


API WORKFLOW

  1. Prüfung der Berechtigungen für den Datenservice
  2. Abruf der Informationen über frei- & nicht freigegebenen Dokumententypen
  3. Abruf der Informationen über verfügbare Auswertungen
  4. Abruf der Informationen über neu verfügbare Auswertungen
  5. Abruf von Mandanten- & Mitarbeiterauswertungen
  6. (wiederkehrend) Überprüfung der Berechtigungen & Dokumententypen unmittelbar vor einer Übertragung
MUST: Die Abrufe sollten in einem gesunden Verhältnis sein. Auf ein erfolgreich abgerufenes 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/)

Prüfung der Berechtigungen für den Datenservice

GET https://hr-payrollreports.../clients
Hier können die Datenbestände abgefragt werden, auf die der Kunde die nötigen Berechtigungen für den Lohnauswertungsdatenservice hat. Wird dieser Endpunkt genutzt, so gibt die API alle verfügbaren Datenbestände zurück. 
MUST: Die Abfrage der Berechtigungen für einen Datenbestand muss genutzt werden. Ein Datenabruf erfolgt nur, wenn der Abgleich mit Konfigurationsdaten erfolgt ist.
Hier erwarten wir eine blätterbare Anzeige (Paging) der verfügbaren Mandantenbestände. Weiterhin muss dem Kunden der Unternehmensname und die Berater- & Mandantennummer 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 ungültige Berater- & Mandantennummer ein und fragt die Berechtigung ab.

Abruf der Informationen über frei- & nicht freigegebenen Dokumententypen

GET  https://hr-payrollreports.../clients/{client-id}
Gibt für den angeforderten Mandanten eine Liste von Auswertungen zurück, auf die zugegriffen werden kann (access_granted) oder nicht zugegriffen werden kann (access_denied). Wenn kein Zugriff auf die angegebene Client-ID möglich ist, wird der Statuscode 403 zurückgegeben. 
MUST: Die Abfrage der Dokumententypen für einen Datenbestand muss 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

Challenges:

  • Zeigen Sie uns eine Liste aller freigegebenen Dokumententypen.

Abruf der Informationen über verfügbare Auswertungen

GET  https://hr-payrollreports.../clients/{client-id}/documents-metadata
SHOULD: Es besteht die Möglichkeit über den Endpunkt  herauszufinden, welche Dokumente für den Abruf zur Verfügung stehen.


Challenges:
  • Geben Sie eine Übersicht von Auswertungen aus, die für einen Monat Ihrer Wahl zur Verfügung stehen.


ONLINE API & ENDPUNKTE für PRODUKTION

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

Prüfung der Berechtigungen für den Datenservice

GET https://hr-payrollreports.../clients
Hier können die Datenbestände abgefragt werden, auf die der Kunde die nötigen Berechtigungen für den Lohnauswertungsdatenservice hat. Wird dieser Endpunkt genutzt, so gibt die API alle verfügbaren Datenbestände zurück. 
MUST: Die Abfrage der Berechtigungen für einen Datenbestand muss genutzt werden. Ein Datenabruf erfolgt nur, wenn der Abgleich mit Konfigurationsdaten erfolgt ist.
Hier erwarten wir eine blätterbare Anzeige (Paging) der verfügbaren Mandantenbestände. Weiterhin muss dem Kunden der Unternehmensname und die Berater- & Mandantennummer 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 ungültige Berater- & Mandantennummer ein und fragt die Berechtigung ab.

Abruf der Informationen über frei- & nicht freigegebenen Dokumententypen

GET  https://hr-payrollreports.../clients/{client-id}
Gibt für den angeforderten Mandanten eine Liste von Auswertungen zurück, auf die zugegriffen werden kann (access_granted) oder nicht zugegriffen werden kann (access_denied). Wenn kein Zugriff auf die angegebene Client-ID möglich ist, wird der Statuscode 403 zurückgegeben. 
MUST: Die Abfrage der Dokumententypen für einen Datenbestand muss 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

Challenges:

  • Zeigen Sie uns eine Liste aller freigegebenen Dokumententypen.

Abruf der Informationen über verfügbare Auswertungen

GET  https://hr-payrollreports.../clients/{client-id}/documents-metadata
SHOULD: Es besteht die Möglichkeit über den Endpunkt  herauszufinden, welche Dokumente für den Abruf zur Verfügung stehen.


Challenges:
  • Geben Sie eine Übersicht von Auswertungen aus, die für einen Monat Ihrer Wahl zur Verfügung stehen.


Abruf der Informationen über neu verfügbare Auswertungen

GET  https://hr-payrollreports.../clients/{client-id}/documents-metadata
SHOULD: Es besteht die Möglichkeit über den Endpunkt  herauszufinden, welche Dokumente seit einem bestimmten Datum neu erschienen sind.


Challenges:
  • Zeigen Sie, welche neuen Dokumente seit einem bestimmten Monat Ihrer Wahl hinzugefügt wurden.

Abruf von Mandanten und- Mitarbeiterauswertungen

GET https://hr-payrollreports.../clients/{client-id}/documents/{period}
Dieser Endpunkt dient zum Abruf der Mandanten- & Mitarbeiterauswertungen für einen bestimmten Abrechnungszeitraum.      
MUST: Die Auswertungen müssen dem korrekten Mitarbeiter und Monat zugewiesen werden.
SHOULD: Die Auswertungen müssen dem korrekten Mandantenbestand, Monat und berechtigten Sachbearbeiter zugewiesen werden.

Challenges:

  • Zeigen Sie, dass die Auswertungen der richtigen Firma zugewiesen werden.
  • Zeigen Sie, dass die Mitarbeiterauswertungen (z.B. LOBN = Brutto Netto), dem richtigen Mitarbeiter (Referenz: DATEV Personalnummer) zugewiesen wird.
  • Zeigen Sie, dass die Mitarbeiterauswertung dem richtigen Monat zugewiesen wird.
  • Zeigen Sie, dass die Mitarbeiterauswertung dem richtigen Auswertungstyp zugeordnet wird.

CHANGELOG

Version

Datum

Änderungen
1.0 03.04.2023 Erstveröffentlichung