Good to know
- The DATEV integration is write-only at the moment
- Sending data to DATEV works file based
- Update employee
- Set compensations
- Create absence
- Prepare DATEV Payroll
- Push general data to DATEV
- Push payroll data to DATEV
- Get DATEV data pushes
Creating a test integration
To develop your integration with Kombo, you must connect DATEV at least a few times. Here is everything you need to know about that.
Call our Create link endpoint. Specify the tool
datev and enter the
SANDBOX. The other parameters are up to you. This will create a link to connect a DATEV sandbox account. Find the credentials for that here:
In Kombo Connect
- Consultant ID (Berater Nummer):
- Client ID (Mandanten Nummer):
In the DATEV popup
- Select login with DATEV Benutzerkonto
Back in Kombo Connect
- Gehalt Lohnart:
- This is the salary type that will be used to create fixed compensations (Festbezüge).
You can submit all primary employee data to DATEV with our Update employee endpoint. You might ask yourself which employee ID you should use for the update operations. Unfortunately, this is a bit tricky as the DATEV integration is write-only.
Specifying the employee ID
Our “update employee” endpoint (and all other DATEV-related endpoints) supports using
remote:<id-in-datev> to reference an employee we don’t know about in our system.
Our recommendation for you is that you let your users enter the DATEV Employee ID (Personalnummer) in a field. Each ID must be numeric and
0 < X < 100000. Also, make sure that the IDs are unique in your database.
Be careful when using these IDs because it is possible to overwrite existing entries in DATEV, as we can’t read data.
DATEV does not differentiate between updates and creates. Additionally, we don’t know if you want to update an existing entry or create a new entry. Therefore, you will use the same Update employee endpoint for editing and creating employees.
DATEV allows specifying hourly and monthly compensations next to one-time payments, which are described later. You can use our Set compensations endpoint to upsert compensations for an employee. It is important to note that we will end all other compensations for the effective date that would be valid otherwise. You can only specify one monthly payment and one hourly wage. If you would like to delete it, don’t submit it. For most use cases, you might only want to specify one compensation. Setting hourly wages is only necessary if an employee is paid by the hour.
When creating a new employee, use a unique employee ID. This can turn out more tricky than expected because you also can’t read from DATEV. Our best practice solution is to specify an offset, e.g., 10000, for your ID generation. That means existing employees might have numbers from 1 to 9999, and you will create the following employees in DATEV with 10001, etc.
You might want to submit absences to DATEV for payroll calculations. Use our Create absence endpoint. Use the
remote: prefix for the employee ID. Only the absence type and the start and end date can be specified. Receive a list of all absence types available in DATEV with our Get absence types endpoint.
Use the Prepare DATEV Payroll endpoint to submit one-time payments specific to one payroll run. Our API differentiates between hourly payments and fixed payments. For example, you would submit overtime hours as
hourly_payments and a one-time-bonus as
In order to specify the Lohnart, you need to request it from your customer first because the Lohnart (compensation type) can be freely configured in DATEV. Each company might use a different Lohnart to submit, for example, hours worked.
This endpoint works as an upsert endpoint too. That means specifying the payroll data for an employee will replace all their current entries and create new ones. Kombo is also keeping track of what was already sent to DATEV and correcting that. Treat this endpoint as you would treat any regular
hourly_payments will be added with the Bearbeitungsschlüssel
fixed_payments will be added with the Bearbeitungsschlüssel
gross). DATEV has a confusing concept around Bearbeitungsschlüssel. You
need to specify a Lohnart that is compatible with the payment type.
Submitting the data to DATEV
Because DATEV uses file-based imports, you must
POST our push data endpoints to submit the data that we aggregated to be sent to DATEV. Please note that we will create one or more files that must manually be imported by the DATEV user when you call this endpoint. Don’t call it after every change, but before preparing payroll or after finishing changes.
- Call our Push General Data endpoint to submit all updates regarding employees, absences, and compensations (all not-payroll-run-related changes).
- Call our Push Payroll Data endpoint to submit all payroll-run specific changes. This will submit all the data you posted to the Prepare Payroll Endpoint.
Please note that we can’t read if the payroll run was already completed in DATEV for the specified month, so it might be possible that you submit data that can’t be taken into account anymore. In this case, your customers’ tax consultant should look into the necessary corrections.
Importing data in DATEV
Your customer tax consultant/employee might already know this, but here are the steps to import files.
First, open the
Daten Übernehmen function and select
ASCII-Import (the actual files are not in ASCII)
When the form is open, instead of selecting a file
Aus dem Rechenzentrum abrufen (Lohndatenimportservice). Now the user should be able to see all the files that were submitted.
Tracking if files were imported
Our integration tracks if files that were submitted to DATEV were imported. Call our Get data pushes endpoint to receive all recent files with their status.