> For the complete documentation index, see [llms.txt](https://docs.younium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.younium.com/erp-and-accounting-integrations/datev.md).

# DATEV

## Synchronisation scope

| Synchronisation                                                                  | Direction       | When it runs                                                  |
| -------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------- |
| Accounts (debtor master data)                                                    | Younium → DATEV | On demand, as a downloaded export file                        |
| Invoice journals                                                                 | Younium → DATEV | On demand for a selected journal, as a downloaded export file |
| Other journals (revenue recognition, payments, payouts, orders, contract assets) | Younium → DATEV | On demand for a selected journal, as a downloaded export file |

Not in scope: products, recurring bookings, imports from DATEV into Younium.

***

## Overview

The DATEV integration lets a German finance team move Younium's customer and booking data into DATEV without retyping it. Younium produces files in DATEV's standard import format (the *EXTF* format, version 700), which your accountant or tax adviser reads into DATEV Rechnungswesen or another DATEV accounting product.

There are two exports. The **customer export** turns your Younium accounts into DATEV debtor master data (*Debitoren/Kreditoren*), so every customer exists in DATEV with the same debtor number, name, address and VAT ID. The **journal export** turns a Younium journal into a DATEV booking batch (*Buchungsstapel*): invoice journals become one booking per invoice and revenue account against the customer's debtor account, and revenue recognition and payment journals become bookings between the general ledger accounts Younium has already posted to.

Nothing is sent to DATEV automatically. Posting an invoice in Younium does not create anything in DATEV; you export a file when you need one, typically once per accounting period, and import it into DATEV yourself.

***

## Core concepts

### Debtor account number (Konto)

DATEV identifies each customer by a numeric debtor account. Younium fills it from the account, in this order:

1. The account's **datevAccountNumber** custom field, when it has a value. Younium uses it exactly as entered.
2. Otherwise the Younium account number, keeping only its digits, with a trailing zero added if **Append trailing zero to debitor account number** is on. An account number with no digits at all becomes `10000`.

The same number is used in the customer export and in the invoice journal export, so the customer's master data and their bookings always meet on the same DATEV debtor.

### Booking batch

A booking batch (*Buchungsstapel*) is DATEV's file of postings for one period. Each Younium journal exports as one batch, dated from the first to the last day of the journal's accounting period.

### Debit/credit indicator (Soll/Haben)

DATEV expresses every amount as a positive number and gives its direction separately: `S` (*Soll*, debit) or `H` (*Haben*, credit). Younium never exports negative amounts; credit notes and reversals show up as `H` bookings instead.

### BU-Schlüssel

The BU-Schlüssel is DATEV's posting key, which tells DATEV how to treat VAT on a booking. Younium can fill it from the external code of the invoice's tax category (see **Invoice journal export**), and always uses `40` on revenue recognition and payment bookings.

***

## Authentication

There is nothing to connect. DATEV is a file-based integration: Younium has no connection to DATEV, needs no DATEV credentials, and stores none. The exports are built from your Younium data when you ask for them and downloaded by your browser.

***

## Activation and setup

The **DATEV** page under integration settings is available once DATEV is enabled for the legal entity, and opening it requires the **View DATEV settings** permission. The page holds two on/off settings, both off by default, plus your DATEV header numbers and the booking text templates described below. Changes take effect on the next export; files already downloaded are not affected.

The export actions themselves are not tied to this page. **Export as Datev** is available on the accounts list and on every journal, whether or not the settings have been saved.

### Settings

| Setting                                                    | Description                                                                                                                                                                                                                   | Default |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| **Map taxcode to deferred revenue account to buSchlüssel** | Fills the BU-Schlüssel on invoice journal bookings from the external code of the invoice's tax category, when the invoice uses exactly one tax category. When off, the BU-Schlüssel on invoice bookings is left blank.        | Off     |
| **Append trailing zero to debitor account number**         | Adds a `0` to the end of the debtor number Younium builds from the account number, in both the customer export and the invoice journal export. Has no effect on accounts whose **datevAccountNumber** custom field is filled. | Off     |

### Consultant and client numbers

Each legal entity can store the **Beraternummer** (consultant number) and **Mandantennummer** (client number) that DATEV expects in the header of every export file. The Beraternummer must be between 1001 and 9999999 and the Mandantennummer between 1 and 99999. Either can be left empty, and Younium rejects a value outside its range when you save the settings.

When a number is not set, Younium exports the placeholder `9999999` for the Beraternummer or `99999` for the Mandantennummer and raises warning HDR-001 or HDR-002. The warning never blocks the export, but DATEV is likely to reject a file that carries a placeholder, so enter your own numbers before importing.

### Booking text templates

A booking text template controls the *Buchungstext* of the bookings in a journal export. You can set one template for each journal type: invoice, revenue recognition and payment. A template can be up to 200 characters and can contain the following placeholders, which Younium replaces for each booking. Placeholders are not case-sensitive.

| Placeholder          | Replaced with                                                                                                                                                  |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{AccountName}`      | The customer's account name                                                                                                                                    |
| `{AccountNumber}`    | The customer's Younium account number                                                                                                                          |
| `{InvoiceNumber}`    | The invoice number                                                                                                                                             |
| `{OrderNumber}`      | The order number of the invoice. Blank when the invoice covers more than one order. For revenue recognition bookings with no invoice, the order of the charge. |
| `{Period}`           | The start of the journal's accounting period, as `MM/yyyy`                                                                                                     |
| `{PaymentReference}` | The payment reference of the payment                                                                                                                           |

Younium rejects a template that contains any other placeholder when you save the settings. A placeholder with no value for a booking, such as an order number on a multi-order invoice, resolves to nothing. Younium then removes the double spaces this leaves, strips quotation marks, semicolons and line breaks (which would break the DATEV file), and cuts the text to DATEV's limit of 60 characters. A template that resolves to nothing exports a blank booking text.

Where no template is set for a journal type, the booking text is unchanged: the description of the accounts receivable posting on invoice bookings, the description of the single posting on revenue recognition bookings, and `Payment {customer}, {invoice}` on payment bookings. Revenue recognition bookings that Younium combines (see **Combined and skipped bookings**) share the same invoice and therefore the same text.

***

## Using your own DATEV debtor numbers

If your debtor numbers in DATEV differ from your Younium account numbers, create a text custom field on **Account** with the internal name `datevAccountNumber` and enter each customer's DATEV debtor number there. The integration looks the field up by that internal name, so renaming it breaks the link; its label can be anything.

When the field is filled, Younium exports the value as entered, with only surrounding spaces removed: no digits are stripped and the trailing-zero setting does not apply. An empty field counts as not set, and the account exports with its Younium account number as usual. Younium also checks the value against DATEV's rules. A value that contains anything other than digits, or that is longer than your general ledger account length plus one digit, is still exported but raises a warning (ACC-001 or ACC-002), because DATEV is likely to reject it on import. The general ledger account length is taken from the length of your financial account codes in Younium, or four digits if there are none.

Several Younium accounts can share one DATEV debtor number — for example, separate locations of one customer that are booked on a single debtor. Their invoices are all booked to that debtor in the journal export. In the customer export, however, there is no single account to take the name and address from, and exporting one location's address would overwrite the debtor in DATEV. So every account sharing the number is left out and Younium raises warning ACC-003 naming the debtor number and up to five of the accounts. Maintain that debtor's master data directly in DATEV.

Revenue recognition and payment journals book between general ledger accounts, not customer debtors, so the field has no effect on them.

***

## Customer export

**Export as Datev** on the accounts list exports every active Younium account as a DATEV debtor. Inactive accounts are not included, and the export always covers all active accounts rather than the rows currently filtered in the list.

The file is a semicolon-separated DATEV *Debitoren/Kreditoren* file (format category 16, format version 5) whose name starts with `EXTF_Accounts`. Every customer is exported as a company (*Adressatentyp* `2`, salutation *Firma*) with a street address.

### Field mapping

| Younium field                                                      | DATEV field                  |
| ------------------------------------------------------------------ | ---------------------------- |
| Debtor account number (see **Core concepts**)                      | `Konto`                      |
| `Account.Name`, first 50 characters                                | `NameAdressattypUnternehmen` |
| First two characters of `Account.TaxRegistrationNumber`            | `EULand`                     |
| `Account.TaxRegistrationNumber`, reformatted for DATEV (see below) | `EUUStID`                    |
| Default invoice address: street, first 36 characters               | `Strasse`                    |
| Default invoice address: postal code, first 10 characters          | `Postleitzahl`               |
| Default invoice address: city, first 30 characters                 | `Ort`                        |
| Default invoice address: country, two-letter code                  | `Land`                       |
| — (always `2`, company)                                            | `Adressatentyp`              |
| — (always `Firma`)                                                 | `Anrede`                     |
| — (always `STR`, street address)                                   | `Adressart`                  |

Empty fields are exported as a single space, as DATEV requires. Fields Younium does not hold, such as a short name or a PO box, are always blank.

### VAT ID formatting

DATEV expects the VAT ID without its country prefix and in each country's own format. Younium takes the country from the first two letters of the account's tax registration number, removes spaces and the country prefix, and reformats the rest:

| Country                                                | Accepted VAT ID                                 | Exported as                                            |
| ------------------------------------------------------ | ----------------------------------------------- | ------------------------------------------------------ |
| Germany, Estonia, Greece, Portugal, United Kingdom     | 9 digits                                        | The digits                                             |
| Denmark, Finland, Hungary, Luxembourg, Malta, Slovenia | 8 digits                                        | The digits                                             |
| Croatia, Italy, Latvia                                 | 11 digits                                       | The digits                                             |
| Poland, Romania, Slovakia                              | 10 digits                                       | The digits                                             |
| Sweden                                                 | 12 digits                                       | The digits                                             |
| Bulgaria                                               | 9 or 10 digits                                  | The digits                                             |
| Lithuania                                              | 9 or 12 digits                                  | The digits                                             |
| Austria                                                | `U` followed by 8 digits                        | `U` and the digits                                     |
| Belgium                                                | 9 or 10 digits                                  | 10 digits, with a leading `0` added to 9-digit numbers |
| Netherlands                                            | 9 digits followed by `B01` or `B02`             | As entered                                             |
| Switzerland                                            | 9 digits followed by `MWST`, `TVA` or `IVA`     | The digits and the suffix                              |
| Norway                                                 | 9 digits                                        | The digits followed by `MVA`                           |
| Cyprus                                                 | 9 characters ending in a letter                 | As entered                                             |
| Czech Republic                                         | 8, 9 or 10 characters                           | As entered                                             |
| Spain                                                  | 9 characters, starting or ending with a letter  | As entered, in capitals                                |
| France                                                 | 11 characters, without the letters `O` or `I`   | As entered, in capitals                                |
| Ireland                                                | 8 or 9 characters, ending in one or two letters | As entered, in capitals                                |

Accounts with no tax registration number are exported with `EULand` and `EUUStID` blank.

### Accounts that cannot be exported

An account whose VAT ID does not match its country's format, or whose VAT ID starts with a country that is neither an EU member state nor Switzerland, Norway or the United Kingdom, is left out of the export rather than stopping it. Younium then downloads a second file, whose name starts with `EXTF_Accounts_errors`, listing each such account with its account number, name, tax registration number and the reason. Correct the tax registration numbers in Younium and export again.

***

## Journal export

**Export as Datev** on a journal's transactions exports that journal as a DATEV booking batch. It is available for **invoice**, **revenue recognition** and **payment** journals; for any other journal type the action is disabled.

The file is a semicolon-separated DATEV *Buchungsstapel* (format category 21, format version 12) whose name starts with `EXTF_Transactions`. How the bookings are built depends on the journal type, described in the next two sections.

### Batch header

The first line of every booking batch is DATEV's header. Younium fills it as follows:

| Header field                      | Value                                                                                           |
| --------------------------------- | ----------------------------------------------------------------------------------------------- |
| Date from / Date to               | First and last day of the journal's accounting period                                           |
| Start of business year            | 1 January of the accounting period's calendar year                                              |
| General ledger account length     | The length of the account codes in the journal, or 4 if it has none                             |
| Currency                          | `EUR`                                                                                           |
| Chart of accounts                 | SKR03                                                                                           |
| Designation                       | `Buchungsstapel`                                                                                |
| Initials                          | `YO`                                                                                            |
| Consultant number / Client number | The Beraternummer and Mandantennummer from the DATEV settings; `9999999` / `99999` when not set |
| Booking lock                      | Unlocked                                                                                        |

The second line holds the column names, and bookings start on line 3. Row numbers in validation messages count from the top of the file, so the first booking is row 3.

***

## Invoice journal export

An invoice journal exports as **one booking per invoice and revenue account**, against the customer's debtor account. Younium finds the invoice through its accounts receivable posting in the journal: the posting to the invoice's own accounts receivable account, or to the account's accounts receivable account when the invoice has none. Postings with a zero amount are ignored.

### Revenue account split

For each invoice line, Younium takes the revenue account that Younium posted the line to (the *Gegenkonto*). This is the largest posting that is neither the accounts receivable posting nor a tax posting. It is not always the deferred revenue account configured on the charge: a charge recognised in full when it is invoiced, for example, is posted directly to a revenue account, and an on-account invoice has no charge at all. When a line has no such posting, Younium falls back to the deferred revenue account of the charge the posting relates to, and otherwise to the accounts receivable account.

Younium then groups the invoice's lines by that account:

| Invoice                           | Bookings exported                                                                                                                                                                                                                                                                     |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| All lines on one revenue account  | One booking for the invoice total, with the tax items of all lines.                                                                                                                                                                                                                   |
| Lines on several revenue accounts | One booking per account, ordered by account code. The amount is the accounts receivable amount of that account's lines, in the invoice currency and the base currency, and the BU-Schlüssel comes from the tax items of those lines only. Accounts whose amount is zero are left out. |

Each booking's debit/credit indicator follows its own amount, so a discount line on its own account exports as `H` even when the invoice itself is a debit.

An invoice that is rounded gets its own booking for the rounding account, with a blank BU-Schlüssel, because the rounding is posted to its own account.

Lines that Younium books on the order event, under order-based revenue recognition, credit the customer's unbilled accounts receivable account. The matching booking is in the order journal, which cannot be exported to DATEV, so these lines keep the deferred revenue account.

If an invoice has no accounts receivable account at either level, the export fails and no file is produced.

### Field mapping

| Younium field                                                                                                                                                         | DATEV field              |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| `Invoice.TotalAmount` for an invoice booked on one revenue account; otherwise the accounts receivable amount of the revenue account's lines. Always a positive amount | `Umsatz`                 |
| `S` for a positive amount, `H` for a credit note or other negative amount                                                                                             | `SollOrHabenKennzeichen` |
| Invoice currency                                                                                                                                                      | `WKZUmsatz`              |
| The same amount in the legal entity's base currency, as a positive amount                                                                                             | `BasisUmsatz`            |
| Base currency                                                                                                                                                         | `WKZBasicUmsatz`         |
| Exchange rate: invoice amount ÷ base amount, six decimals; `1` when the currencies are the same                                                                       | `Kurs`                   |
| Debtor account number of the invoice's account (see **Core concepts**)                                                                                                | `Konto`                  |
| Revenue account the line was posted to (see **Revenue account split**)                                                                                                | `Gegenkonto`             |
| `Invoice.InvoiceDate`, as `ddMM`                                                                                                                                      | `Belegdatum`             |
| `Invoice.InvoiceNumber`                                                                                                                                               | `Belegfeld1`             |
| Description of the accounts receivable posting, or the invoice booking text template when set                                                                         | `Buchungstext`           |
| `Account.TaxRegistrationNumber`, as entered                                                                                                                           | `EULandUStID`            |
| Tax category external code of the booking's lines, when **Map taxcode to deferred revenue account to buSchlüssel** is on                                              | `BUSchlussel`            |

### BU-Schlüssel on invoice bookings

With **Map taxcode to deferred revenue account to buSchlüssel** on, Younium looks at the tax items on the lines in each booking (all of the invoice's lines when it has one booking) and matches them by name to your tax categories. When they match exactly one tax category, its external code becomes the BU-Schlüssel. When the booking matches no tax category, or more than one, or the category has no external code, the BU-Schlüssel is left blank. With the setting off, it is always blank.

> **Note on invoice bookings:** The invoice journal export books each invoice, or each revenue account of it, as a total against the customer's debtor. It does not export individual invoice lines or separate VAT lines, so VAT is left to DATEV's automatic accounts and the BU-Schlüssel.

***

## Revenue recognition and payment journal export

Revenue recognition and payment journals contain no customer debtor; they move amounts between general ledger accounts. Younium exports them by reading each transaction's postings, ignoring postings with a zero amount or without a financial account.

In each transaction, one side — debit or credit — must consist of a single posting carrying the full amount. That posting becomes the booking's `Konto`, and each posting on the other side becomes one booking with its own `Gegenkonto` and amount. A transaction with a single debit and a single credit therefore exports as one booking, and a transaction that releases one deferred revenue amount to three revenue accounts exports as three.

### Field mapping

| Younium field                                                                                                                                                   | DATEV field              |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| Amount of the posting on the split side, as a positive amount                                                                                                   | `Umsatz`                 |
| `S` when the single posting is a debit, `H` when it is a credit                                                                                                 | `SollOrHabenKennzeichen` |
| Posting currency                                                                                                                                                | `WKZUmsatz`              |
| Posting amount in the base currency, as a positive amount                                                                                                       | `BasisUmsatz`            |
| Base currency                                                                                                                                                   | `WKZBasicUmsatz`         |
| Exchange rate: posting amount ÷ base amount, six decimals; `1` when the currencies are the same                                                                 | `Kurs`                   |
| Financial account code of the single posting                                                                                                                    | `Konto`                  |
| Financial account code of the split-side posting                                                                                                                | `Gegenkonto`             |
| — (always `40`)                                                                                                                                                 | `BUSchlussel`            |
| Effective date of the transaction, as `ddMM`: the payment date for payment journals and the first day of the accounting period for revenue recognition journals | `Belegdatum`             |
| Invoice number of the related invoice; otherwise the single posting's description; otherwise the transaction number                                             | `Belegfeld1`             |
| Description of the single posting, or the booking text template for the journal type when set                                                                   | `Buchungstext`           |

### Combined and skipped bookings

Bookings that agree on `Konto`, `Gegenkonto`, debit/credit indicator, currencies, exchange rate, `Belegfeld1` and `Belegdatum` are combined into one booking with the amounts added together. In practice, several postings for the same invoice number, date and pair of accounts appear in DATEV as a single line.

A booking whose `Konto` and `Gegenkonto` are the same account is left out of the file and reported as error RB-005. A booking whose amount is zero or less is left out and reported as error RB-006.

> **Note on transactions that cannot be split:** The export stops, and no file is produced, if any transaction in the journal has postings on only one side, has more than one posting on both sides, or has debit and credit sides that do not balance in the base currency. The error message names the transaction number.

***

## Validation

Every export is checked against DATEV's rules before the file is downloaded. When the check finds anything, Younium shows a notification headed *DATEV validation* with the number of errors and warnings and one line per finding, each starting with its code. The file still downloads, so you can decide whether to correct the data in Younium and export again, or fix the booking in DATEV.

The one exception is a journal with no bookings to export: Younium shows *No DATEV rows to export for this journal* and no file is downloaded.

| Code         | Severity | Meaning                                                                                                  |
| ------------ | -------- | -------------------------------------------------------------------------------------------------------- |
| GEN-007      | Error    | The export contains no bookings                                                                          |
| HDR-001      | Warning  | No Beraternummer is set in the DATEV settings, so the placeholder `9999999` is exported                  |
| HDR-002      | Warning  | No Mandantennummer is set in the DATEV settings, so the placeholder `99999` is exported                  |
| ACC-001      | Warning  | A **datevAccountNumber** value contains characters other than digits                                     |
| ACC-002      | Warning  | A **datevAccountNumber** value is longer than the general ledger account length plus one digit           |
| ACC-003      | Warning  | A **datevAccountNumber** value is shared by several accounts, which were left out of the customer export |
| BS-003       | Error    | A booking has no `Konto` or no `Gegenkonto`                                                              |
| BS-004       | Error    | A booking's debit/credit indicator is not `S` or `H`                                                     |
| BS-005       | Error    | A booking's `Konto` and `Gegenkonto` are the same account                                                |
| BS-006       | Error    | A booking's amount is zero or negative                                                                   |
| BS-007\_CURR | Error    | A booking's currency is not a three-letter code                                                          |
| BS-007\_SAME | Warning  | A booking in the base currency has an exchange rate other than `1`                                       |
| BS-007\_FX   | Error    | A booking in a foreign currency has no exchange rate                                                     |
| BS-008       | Error    | A booking's document date is not in `ddMM` form                                                          |
| RB-005       | Error    | A revenue recognition or payment booking had the same `Konto` and `Gegenkonto` and was left out          |
| RB-006       | Error    | A revenue recognition or payment booking had a zero or negative amount and was left out                  |

Errors with a row number refer to the line in the downloaded file, counting the header and column-name lines, so the first booking is row 3.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.younium.com/erp-and-accounting-integrations/datev.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
