Klardaten (DATEV)

Sensitive data: read this first. This connector reads a tax advisory firm's DATEV data through Klardaten: the master data, tax returns, bookkeeping and payroll of the firm's clients, including salaries, tax numbers, birth dates and bank transactions of private persons and companies. That data is covered by professional secrecy (§ 203 StGB, § 57 StBerG) and the GDPR. Add this connector only to servers whose users are allowed to see all of it, for example the partners or the staff who already have that access in DATEV. Do not add it to a shared or company-wide server. The API key acts with the DATEV profile behind it, so a model sees whatever that profile can read.

Setup

1. Sign in at https://dashboard.klardaten.com and create an API key for your user. It starts with uk- and goes into KLARDATEN_API_KEY; it is sent as Authorization: Bearer.
2. Copy the id of the DATEV instance (a UUID, created with your consultant number when the Klardaten connector was installed on the DATEV server) into KLARDATEN_INSTANCE_ID. Every DATEV request carries it in the x-client-instance-id header. klardaten_list_instances lists the instances the key can reach.
3. The Klardaten connector on the DATEV server must be running. When it is offline, DATEV calls fail while klardaten_get_me still works; klardaten_get_datevconnect_health shows the service status.

Which tool to start with: klardaten_get_me to check access, then klardaten_list_clients (master data), klardaten_list_accounting_clients (bookkeeping), klardaten_list_payroll_clients (LODAS payroll) or klardaten_list_firm_clients (the firm's own practice management analytics).

Ids differ per area. Master data uses UUIDs (client_id, addressee_id). Accounting uses a numeric client_id from klardaten_list_accounting_clients, and fiscal years are keyed by their start date as YYYYMMDD (e.g. 20250101). Payroll and firm analytics use the client_number. Tax returns have their own id. Passing an id from another area is the usual cause of a 400 or 404.

Paging, fields and filters: list tools take page (from 1) and page_size (default 100), order_by (field:asc|desc, comma-separated), fields (comma-separated, keeps answers small) and filter. A filter is field operator value with eq, like, gt, gte, lt, lte, in, notin, is, isnot, combined with AND/OR, e.g. client_id eq 101 AND fiscal_year eq 20250101. Only the fields of that endpoint are accepted; an unknown field or a wrongly formatted value returns 400. Always filter klardaten_list_postings by client_id and fiscal_year: across all clients of a firm the query takes about a minute and can time out.

DATEVconnect passthrough: klardaten_datevconnect_get reads any DATEVconnect GET path (e.g. master-data/v1/clients) for data the other tools do not cover. It is read-only.

DATEV profile: DATEVconnect calls run with the API key's default Klardaten profile. To act as another profile, set KLARDATEN_PROFILE_ID; it is sent as x-profile-id on every DATEVconnect call. Eigenorganisation writes need a profile that is an Eigenorganisation employee (EODC10015 otherwise). DCO10009 ("License for DATEVconnect is not present") comes from the DATEV server itself: check the DATEVconnect licence there.

DATEV Anwalt and user management: klardaten_list_law_files and the other klardaten_*_law_* tools read the law firm module (files, parties, budget, expenses and its reference lists); they need DATEV Anwalt on the server. klardaten_list_datev_users and klardaten_list_datev_groups read DATEV's user management (read-only).

Writes (installed switched off): klardaten_update_order changes an Eigenorganisation order, klardaten_create_expense_posting books a time or cost entry on a sub-order, and klardaten_set_client_responsibilities replaces a client's responsibilities. They change the firm's DATEV data: turn them on only on a server whose users may do that in DATEV, and confirm every change with the user. klardaten_update_order and klardaten_set_client_responsibilities replace what they write, so read first and send the full object or list.

Licensing: the Enterprise endpoints (accounting, payroll, tax, analytics) depend on the Klardaten plan; an endpoint outside the plan answers 403. klardaten_search_documents needs the document search add-on, which Klardaten enables per instance on request; it is installed switched off, turn it on once the add-on is active.