DATEV integration for expenses

The DATEV (Expense) integration is an API-based integration that uses DATEV’s Buchungsdatenservice for expenses of all types (common expenses, card transactions and travel expenses).

Once Finance has reviewed and approved the expenses, exporting the expenses from Yokoy converts the expenses into an accounting journal in CSV format that is transferred to the DATEV computation center (Rechenzentrum or RZ), together with the corresponding receipt.

Receipts are sent to DATEV and can be seen in DATEV Unternehmen Online (DUO). The DATEV-Format file can also be generated without sending it to DATEV. Within DATEV, the bookings and their linked receipts can be sourced from Rechenzentrum, modified (unless the bookings are set to locked in Yokoy), and booked.

DATEV does not expose any endpoints to get master data for Yokoy. Therefore, this integration covers the export of booking data only.

The integration uses DATEV’s accounting:documents and accounting:extf-files public APIs.

Accounting logic and booking file format

The accounting journal is prepared in the DATEV-Format:

Column	Description
Umsatz (ohne Soll/Haben-Kz)	Gross amount in original currency
Soll/Haben-Kennzeichen	“H” for credit note, else “S”
WKZ Umsatz	Original expense currency. Present only if the expense is in a foreign currency
Kurs	Exchange rate
Basis-Umsatz	Gross amount in base currency
WKZ Basis-Umsatz	Base currency
Konto	Account
Gegenkonto (ohne BU-Schlüssel)	Creditor account
BU-Schlüssel	Tax item code. Only if tax is present
Belegdatum	Configuration within Yokoy. Expense date or posting date
Belegfeld 1	Configuration within Yokoy
Buchungstext	Business purpose / description
Postensperre	0
Zinssperre	0
KOST1 - Kostenstelle	Configuration within Yokoy
KOST2 - Kostenstelle	Configuration within Yokoy
EU-Land u. UStID (Bestimmung)	Merchant tax number
Zahlweise	3
Festschreibung	Configuration within Yokoy. It can be 0 or 1.
Zusatzinformation - Art 1	“Original Yokoy ID”
Zusatzinformation - Inhalt 1	Yokoy internal expense id
Zusatzinformation - Art 2	“Name Mitarbeiter”
Zusatzinformation - Inhalt 2	First and last name of the employee

The header of the file is defined as follows:

Column	Value
Flag	“EXTF”
Version number	700
Format Category	21
Format Name	“Buchungsstapel”
Format Version	12
Created on	Time stamp
Consultant number	Depending on connection setting. Taken from the setting.
Client number	Depending on connection setting
Start of business year	Configuration within Yokoy
G/L account length	Configuration within Yokoy
Date from	Earliest `Belegdatum` of all bookings contained in the file
Date till	Latest `Belegdatum` of all bookings contained in the file
Designation	“Yokoy Expense Export”
Initials	“YY”
Record type	1
Accounting Reason	0
Locking	Configuration within Yokoy. Either 0 or 1
Currency Code	Base currency
G/L chart of accounts	Configuration within Yokoy. SKR03, SKR04, SKR07

This booking file is also stored in Yokoy and can be downloaded for inspection.

Receipt transmission

Currently Yokoy supports the following formats for transmitting the receipt to DATEV:

JPG / JPEG

The receipts are sent with the following metadata:

Field	Value
document_type	“Rechnungseingang”
note	“Beleg zu Yokoy Spese <Yokoy-ID>”
category	“Yokoy”
folder	“Spesen”
register	Expense (posting) date in YYYY/MM format (considered date depends on the `Belegdatum` configuration)

The last three entries are used to categorize the receipts in the following folder structure

Belegablage/<category>/<folder>/<register>. This means that a receipt dating from January 2022 is found under Belegablage/Yokoy/Spesen/”2022/01”.

Setup in DATEV

As a prerequisite for the integration with Yokoy, you have to activate the Buchungsdatenservice in the DATEV account.

Please refer to the following resources from DATEV:

If you cannot activate the service, please reach out to your tax consultant.

Setup in Yokoy

Setting up a new connection: authentication

✏️ Prerequisites

You need to know the client-id consisting of the consultant number and the client number. You can request this information from your tax consultant or look it up in the DATEV application.

As in DATEV all bookings a converted to the company currency (typically EUR), only the Export amounts in company currency booking currency strategy is supported.

To configure the connection with DATEV:

Go to Admin > Integrations > Expense export
Click Change ERP System for the relevant expense type (Expenses/Credit card transactions/Travel expenses)
Select DATEV Buchungsdatenservice to establish a new connection.
See Reusing an existing connection if you want to reuse an existing connection.
The following credentials form appears:
Fill in the consultant number and the client number.
Make sure that the pop-up blocker is deactivated.
Click Connect to DATEV.
A pop-up window appears in which you must log in to DATEV:
Choose your appropriate login method and provide the password if required.
If the login was successful, you are asked to provide consent:
Click I agree if you agree to grant the described permissions to Yokoy.
The connection is established and tested. The results of the connection test are displayed below the ERP required configuration section:

The following outcomes are possible:

Connection status	Explanation
Updating connection status…	The connection is being tested.
The connection with DATEV is active.	The connection is active and all relevant services are available in DATEV.
Relevant services are missing in DATEV. Please verify the entries for consultant and client number and the available services in DATEV.	The connection is active, but relevant services are missing. Please make sure that the services “Buchungsdatenservice” and “Belegbilderservice” are activated in DATEV.
The client does not exist in DATEV or the access rights are missing. Please verify the entries for consultant and client number and check the access rights in DATEV.	Your user does not have the access rights to the entered client-id or the client-id does not exist. Verify that you entered the consultant number and the client number correctly.
Consultant and/or client number are missing, please connect again.	Either no previous connection attempt has been undertaken or it failed and the consultant number and/or the client number is missing. You need to connect (again).
No refresh token is available, please establish a connection to obtain a new token.	Previous connection attempts failed and no tokens were received from DATEV. Connect again and check the FAQs at the end of this documentation for potential errors.
The connection with DATEV has been revoked in Yokoy.	Some user in Yokoy has actively revoked the connection with DATEV and it needs to be re-established.
The connection with DATEV has been disconnected, please connect again.	The connection tokens are not working anymore, most likely because the connection expired (happens after 2 years) or has been revoked outside of Yokoy.
The connection status could not be determined, please contact the support.	Some unforeseen error happened. Please contact Yokoy Support.

Managing the connection to DATEV

You can disconnect the connection with DATEV at any stage by clicking Disconnect from DATEV. Alternatively, the link Manage connections in DATEV provides you with a complete overview of all your connections within DATEV and allows you to disconnect them.

In addition, you can access the availability of the DATEV data processing center and to more in-depth product information on the Buchungsdatenservice.

Configuration

Once the connection has been successfully set up, the following configuration form appears:

You need to configure these settings:

Configuration	Description
Consultant number	Consultant number as defined when establishing the connection. It needs to stay aligned with the corresponding connection parameter and therefore cannot be modified in the configurations. If the consultant number needs to be updated, a new connection needs to be established.
Client number	Client number as defined when establishing the connection. It needs to stay aligned with the corresponding connection parameter and therefore cannot be modified in the configurations. If the consultant number needs to be updated, a new connection needs to be established.
G/L account length	Account length (Sachkontenlänge), needs to be consistent with DATEV. It can be found within DATEV under Stammdaten > Mandantendaten Rechnungswesen > Grunddaten Rechnungswesen.
Chart of accounts	Chart of accounts (Standardkontenrahmen), needs to be consistent with DATEV. It can be found within DATEV under Stammdaten > Mandantendaten Rechnungswesen > Grunddaten Rechnungswesen.
Method for the column ‘Belegfeld 1’	The column ‘Belegfeld 1’ provides automatic reconciliation (depending on the setting, bookings with a value that zeroes out are not displayed). Yokoy currently offers several options for setting the value in the ‘Belegfeld 1’: Use the “expense ID” Use the “trip ID” (expense ID if no trip ID is available) Use a “constant value” (see next field) “Map the month of the expense” to predefined values (see next field)
Value / mapping for the column ‘Belegfeld 1’	This configuration field complements the previous one. If you choose the method “constant value”, you have to enter the desired value in this field. If you chose the method “map month of the expense”, the mapping is specified in JSON notation, for example: {“1”: “first value”, “2”: “second value”, “3”: “third value” …}
Value for the field ‘KOST1 - Kostenstelle’	Yokoy currently offers three options for setting the value of the field ‘KOST1 - Kostenstelle’: Use the cost center (code) Use the tag (code) Keep the field empty
Value for the field ‘KOST2 - Kostenstelle’	Yokoy currently offers three options for setting the value of the field ‘KOST2 - Kostenstelle’: Use the cost center (code) Use the tag (code) Keep the field empty
Tag dimension for the field ‘KOSTx - Kostenstelle’	In case you choose the tag option for one of the KOST fields, this field allows for the specification of the tag dimension to be used.
Start of business year (DD-MM)	Day and month of the start of the business year (in DD-MM format). Please note that only expenses from the same business year can be exported together.
Lock exported postings	Whether or not to lock bookings (Festschreibung).
Date for the column `Belegdatum`	Date to export in the column `Belegdatum`. The following options exist: Use the posting date Use the expense/payment date By default, the posting date is considered.
Chose the document handling	Whether or not to send the receipts to DATEV, the following options are available: Don’t export documents Only export the original receipts Export original receipt if available, else export the generated PDF Always export the generated PDF The generated PDF refers to Yokoy’s standard expense summary PDF. If the expense has a receipt, the receipt is embedded in this PDF. If documents are transmitted to DATEV (all but the first option), the Belegbilderservice needs to be available (usually automatically activated when activating the Buchungsdatenservice).
Export pdf summary for trips	If checked, a trip summary in pdf form is transmitted as receipt for expenses that are part of a trip.
Ignore zero amount bookings in the export	If checked, zero amount expenses are not transmitted to DATEV, but still set to the status “exported” .
Per diem rates to be excluded from the export	Select the per diem rates that should not be transmitted to DATEV, but still set to the status “exported” .
Mileage rates to be excluded from the export	Select mileage rates that should not be transmitted to DATEV, but still set to the status “exported” .

All configuration parameters are required with the following exceptions:

“Value / mapping for the ‘Belegfeld 1’” can remain empty if you are using the “expense ID” method.

“Tag dimension for the field ‘KOSTx - Kostenstelle’’ can remain empty if the tag is not used for any of the two KOST fields.

Reusing an existing connection

Yokoy offers the option to use different ERP systems for common expenses, credit card transactions and travel expenses. However, often the bookings for these three types of expenses are exported to the same ERP system.

In this case, you can reuse the connection established for common expenses with the same configurations by selecting DATEV Buchungsdatenservice with existing connection” from the ERP system field.

Booking in DATEV

The booking data exported from Yokoy is sent as a transaction batch (“Buchungsstapel”) to DATEV’s data center (“Rechenzentrum”, “RZ”). For the procedure to source the booking data from the data center and post the bookings in DATEV, refer to DATEV documentation.

Frequently Asked Questions (FAQ)

After clicking Connect with DATEV, nothing happens.

Check whether your browser blocks pop-ups. The authentication flow opens a pop-up window to log in to DATEV. Depending on your browser settings, pop-up windows may be blocked.

After clicking Connect with DATEV, an empty window appears.

Most likely the password for the mIDentity is requested in a window that may be hidden behind other windows.

After establishing the connection with DATEV, the connection status is shown as Missing Service.

Not all required services have been activated in DATEV. Check with DATEV and your tax consultant.

How can I check whether I can connect to DATEV?

Below the connection status there is a link to Manage connections in DATEV. If you can log into DATEV’s connection overview (“Verbundene Anwendungen”), you can also connect with DATEV. However, this does not provide any information on the availability of the required DATEV services, nor on the permissions to a specific client ID.

Can I connect several legal entities with the same client id in DATEV?

Yes, this is possible. Please consider the next bullet.

I want to connect several legal entities with DATEV (potentially using the same client ID). When trying to connect the second legal entity, I am no longer asked for authentication and the connection attempt fails. What should I do?

DATEV seems to remember previous connection attempts from the browser and does not ask for authentication again. Sometimes this can lead to failing connection attempts. Please restart the browser (or open a new window) between successive connection attempts.

Can I use Yokoy’s DATEV integration also with on-premise systems?

Yes you can, the only requirement is a connection to DATEV’s data center (“Rechenzentrum”, RZ). In the vast majority of cases such a connection already exists for other topics like “USt-Übermittlung” or “Bezug von Kontoauszugsdaten”.