Interface requirements for Lohnauswertungsdatenservice

The DATEV Lohnauswertungsdatenservice is a DATEV online API solution that supports the division of labor process when transferring wage and client evaluations to the third-party system landscape. The wage evaluations are retrieved automatically and via a secure connection from the DATEV datacenter. The data is made available with the respective payroll in the DATEV datacenter. The prerequisite for this procedure is an interface between the DATEV payroll program LODAS or Lohn und Gehalt and the solution used by the company.


API WORKFLOW

  1. Checking permissions for the data service
  2. Retrieval of information about released & non-released document types
  3. Retrieval of information about available evaluations
  4. Recall of information about newly available evaluations
  5. Recall of client & employee evaluations
  6. (Recurring) Review of permissions & document types immediately before a transfer
MUST: Retrievals should be in a healthy ratio. Producing another 30 GET requests on top of one successfully retrieved document is not evidence of efficient integration.

ONLINE API & END POINTS for SANDBOX

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

Check permissions for data service

GET https://hr-payrollreports.../clients
This can be used to query the datasets to which the customer has the necessary permissions for the Lohnauswertungsdatenservice. If this endpoint is used, the API will return all available datasets. 
MUST: The query of permissions for a dataset must be used. A data retrieval will only be done if the match with configuration data has been done.
Here we expect a scrollable display (paging) of the available client databases. Furthermore, the customer must be displayed the company name and the consultant & client number.
Important note: Getting the long term token for a {client-id} does not yet mean that the customer actually has permissions for the {client-id}. That is, the 3rd party app gets the token and then immediately addresses the GET clients with it. Authentication is not to be indicated to the client as successfully connected until the GET Clients has confirmed the correct assignment of permissions.

Challenges:
  • Consultant enters an invalid consultant & client number and queries authorization.

Retrieval of information about shared & non-shared document types

GET https://hr-payrollreports.../clients/{client-id}
Returns a list of reports that can be accessed (access_granted) or not accessed (access_denied) for the requested client. If no access is possible to the specified client ID, the status code 403 is returned. 
MUST: The document type query for a dataset must be used. Here it must be shown where the customer makes his specifications for the dataset. After that, show the endpoint call with a success message

Challenges:

  • Show us a list of all released document types

Retrieve information about available evaluations

GET https://hr-payrollreports.../clients/{client-id}/documents-metadata
SHOULD: It is possible to find out which documents are available for retrieval via the  endpoint


Challenges:
  • Give out an overview of evaluations available for a month of your choice.


ONLINE API & END POINTS for PRODUCTION

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

Check permissions for data service

GET https://hr-payrollreports.../clients
This can be used to query the datasets to which the customer has the necessary permissions for the Lohnauswertungsdatenservice. If this endpoint is used, the API will return all available datasets. 
MUST: The query of permissions for a dataset must be used. A data retrieval will only be done if the match with configuration data has been done.
Here we expect a scrollable display (paging) of the available client databases. Furthermore, the customer must be displayed the company name and the consultant & client number.
Important note: Getting the long term token for a {client-id} does not yet mean that the customer actually has permissions for the {client-id}. That is, the 3rd party app gets the token and then immediately addresses the GET clients with it. Authentication is not to be indicated to the client as successfully connected until the GET Clients has confirmed the correct assignment of permissions.

Challenges:
  • Consultant enters an invalid consultant & client number and queries authorization.

Retrieval of information about shared & non-shared document types

GET https://hr-payrollreports.../clients/{client-id}
Returns a list of reports that can be accessed (access_granted) or not accessed (access_denied) for the requested client. If no access is possible to the specified client ID, the status code 403 is returned. 
MUST: The document type query for a dataset must be used. Here it must be shown where the customer makes his specifications for the dataset. After that, show the endpoint call with a success message

Challenges:

  • Show us a list of all released document types

Retrieve information about available evaluations

GET https://hr-payrollreports.../clients/{client-id}/documents-metadata
SHOULD: It is possible to find out which documents are available for retrieval via the  endpoint


Challenges:
  • Give out an overview of evaluations available for a month of your choice.


Retrieve information about newly available evaluations

GET https://hr-payrollreports.../clients/{client-id}/documents-metadata
SHOULD: It is possible to find out which documents have been newly published since a certain date via the  endpoint.


Challenges:
  • Show which new documents have been added since a certain month of your choice.

Retrieve client and employee evaluations

GET https://hr-payrollreports.../clients/{client-id}/documents/{period}
This endpoint is used to retrieve client & employee reports for a specific payroll period. 
MUST: The evaluations must be assigned to the correct employee and month
SHOULD: The evaluations must be assigned to the correct client base, month, and authorized clerk.

Challenges:

  • Show that the evaluations are assigned to the correct company
  • Show that the employee evaluations (e.g. LOBN = gross net), are assigned to the correct Employee (reference: DATEV personnel number) is assigned.
  • Display that the employee evaluation is assigned to the correct month.
  • Display that the employee evaluation is assigned to the correct evaluation type.

CHANGELOG

version

Date

Changes
1.0 03.04.2023 First release