Interface requirements for Lohnimportdatenservice

The Lohnimportdatenservice primarily supports the division of labor process between the law firm and the client when transferring transaction data and master data from third-party software to the DATEV payroll program. The confidential data is made available via a secure connection in the DATEV datacenter for Lohn und Gehalt and LODAS. At the push of a button, the data can be imported into the payroll program and used for the next payroll run. The (regular) API workflow is shown below and which online APIs & endpoints must/should be used in connection with the data service.

API WORKFLOW

1. Check permissions for the data service
2. Transfer of individual files - manually (by click via 3rd party app) or automated (rule-based)

MUST: Submitted files (POST) and read API requests (GET) should be in a healthy ratio. Producing another 30 GET requests on top of one successfully submitted file is not evidence of efficient integration.

ONLINE API & END POINTS for SANDBOX

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

Check permissions

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

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

Here you can query the datasets to which the client has the necessary permissions. The 3rd party app must use the second endpoint. If the first endpoint is used, the API returns all available datasets. This can result in hundreds or thousands of data values, especially for larger companies. Therefore, the second endpoint must be used. Here the client must get an input option in the 3rd party app for the consultant and client number.

MUST: The second endpoint must be used. This is where you need to show where the client enters their details for the dataset. After that, show the call to the endpoint with a success message. Also an error must be reproduced by using a consultant and client number for which the customer has no authorization. Here, a corresponding error message must be displayed on the interface. 

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 a correct consultant and client number and displays the success message
• Consultant enters an invalid consultant and client number and displays error message

Transferring files

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

Use this endpoint to transfer the files to the DATEV datacenter. If the interface is used for master data and transaction data, a master data file and a transaction data file must be transmitted once. Otherwise only the file that is preferred by the 3rd party app.

MUST: Show a successful transfer of the files to the DATEV datacenter.

Important note: In the sandbox, the ASCII files can only be transferred to the DATEV datacenter. They can not be imported afterwards. This function is only available in the production environment.

Query status

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

This endpoint shows the respective status of the uploaded files.

SHOULD: Display the status of the transferring files on the interface

ONLINE API & END POINTS for PRODUCTION

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

Check permissions

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

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

Here you can query the datasets to which the client has the necessary permissions. The 3rd party app must use the second endpoint. If the first endpoint is used, the API returns all available datasets. This can result in hundreds or thousands of data values, especially for larger companies. Therefore, the second endpoint must be used. Here the client must get an input option in the 3rd party app for the consultant and client number.

MUST: The second endpoint must be used. This is where you need to show where the client enters their details for the dataset. After that, show the call to the endpoint with a success message. Also an error must be reproduced by using a consultant and client number for which the customer has no authorization. Here, a corresponding error message must be displayed on the interface. 

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 a correct consultant and client number and displays the success message
• Consultant enters an invalid consultant and client number and displays error message

Transferring files

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

Use this endpoint to transfer the files to the DATEV datacenter. If the interface is used for master data and transaction data, a master data file and a transaction data file must be transmitted once. Otherwise only the file that is preferred by the 3rd party app.

MUST: Show a successful transfer of the files to the DATEV datacenter. Then show the import into the DATEV payroll programs.

Query status

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

This endpoint shows the respective status of the uploaded files.

SHOULD: Display the status of the transferring files on the interface.

CHANGELOG

version	Date	Changes
1.0	03.04.2023	First release