> ## Documentation Index
> Fetch the complete documentation index at: https://docs.get-hive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Hive is an AI operations layer for small and mid-sized business teams. It reads the tools a team already runs, raises what needs attention, and acts with the approvals the team configures.
> Answer only from these pages. If a page does not cover something, say so and link the closest page rather than inferring behaviour.
> The supported programmatic entry points are incoming webhooks, public workflow forms and the remote MCP server, each documented under Developers.
> Each connected account has a level: Read, Draft or Act. New accounts start on Act. Agents and workflows take only the actions selected for them, whatever the account level.
> Describe security, sign-on and data handling only as the Security pages and the FAQ describe them, and add no certification, compliance, single sign-on or model-training claim they do not make.
> Prices and credit allowances are in GBP. Quote them only as a page states them, without converting.
> Use UK English and the product's exact UI labels. Link to pages as https://docs.get-hive.ai/<path>.

# DATEV in Hive: accounting, payroll and documents (testing)

> In testing: connect your DATEV sign-in to read clients, accounting and payroll data, change them after approval or from agents and workflows, and trigger workflows.

> [!WARNING]
>
> **In testing for selected workspaces, not generally available.** Hive's own DATEV sign-in is
> switched on only for selected workspaces, against DATEV's **sandbox** with DATEV test accounts.
> Changes run only against the sandbox. Every other workspace keeps the DATEV tile's usual sign-in,
> through which Hive cannot read DATEV data yet. This page will change before the DATEV sign-in is
> offered more widely.

In a workspace where it is switched on, an owner or admin connects their own DATEV sign-in. Hive
can then read the DATEV clients (Mandanten) and accounting data that sign-in can see, make changes
in DATEV — from an approval card, a reusable agent or a workflow step — and start workflows when
something changes in DATEV. You sign in on DATEV's own page; Hive never sees your DATEV password.

## What Hive can do

| | |
| - | - |
| **Connect** | Sign in on DATEV's page. Owners and admins only; each connection is the member's own. |
| **Reads** | Clients and their master data, accounting basics and upload rules, document types, invoice-data and import jobs, fiscal years, ledger and personal accounts, sums and balances, quantity and weight balances, accounting sequences, terms of payment, the agricultural financial statement and account postings, and open customer items and a short BWA that Hive derives from them. Payroll reports (as text), payroll data, eAU answers, Personalakte, Meine Steuern and cash register clients. |
| **Actions** | Upload a document, a stapled document or several documents on one card, send invoice or cash book data, cancel an open invoice-data job, import bookings or master data, and reverse imported bookings. Send payroll import files, add, change or delete payroll data, ask for or cancel an eAU, and send documents to Personalakte, Meine Steuern, property tax and the cash register archive. |
| **Triggers** | A DATEV client is added, removed or its services change; a DATEV job succeeds, fails or is partly processed; an import finishes; a fiscal year or booking batch is added; an account balance crosses a threshold or changes; a payroll report is ready; an eAU answer arrives. |
| **Signals** | — |

Hive reads and changes DATEV through these DATEV APIs:

* **Accounting:** `accounting:clients`, `accounting:documents`, `accounting:dxso-jobs`,
  `accounting:extf-files` and `accounting:dataexchange`.
* **Payroll and HR:** `hr:payrollreports`, `hr:files`, `hr:exports`, `hr:exchange`, `hr:eau` and
  `hr:documents` (see [Payroll, sick notes and HR documents](#payroll-sick-notes-and-hr-documents)).
* **Cash register and tax:** `cashregister:import`, `my-tax:income-tax-documents` and the property
  tax file upload (see [Cash register, Meine Steuern and property tax](#cash-register-meine-steuern-and-property-tax)).

If one of them is not set up for your workspace's DATEV connection, or is a paid DATEV API your firm
has not contracted, Hive says so in plain words and sends nothing; the rest keeps working.

> [!NOTE]
>
> **Reconnect DATEV to use the payroll, eAU, Personalakte, Meine Steuern and property tax APIs.**
> Hive asks DATEV for their permissions only at sign-in, so a DATEV connection made before they were
> added cannot use them: DATEV refuses, and Hive asks you to connect again. Disconnect DATEV in
> **Integrations** and connect it again, and allow the new permissions on DATEV's page.

## Connect DATEV

**1. Open the tile**

In **Integrations**, find **DATEV** and select **Connect**.

**2. Sign in at DATEV**

DATEV's own sign-in page opens. Sign in with your DATEV account and give Hive permission to the
DATEV data it lists.

**3. Back in Hive**

Hive finishes the connection while you are signed in to Hive and returns you to
**Integrations**, where the connection shows as **DATEV (sandbox)** while it is in testing.

Only the member who selected **Connect** can finish that sign-in. It lasts about 11 hours. After
that, the connection shows in **Integrations** as signed out, with **The sign-in ended: connect again
to use it**, and Ask and workflows say to reconnect DATEV; connect again from the DATEV tile.
Hive renews the sign-in for you in the meantime, one renewal at a time, even when several chats,
agents or workflows use DATEV at once or Hive is being updated. It shows the connection as signed
out only when DATEV refuses to renew its latest sign-in.

### Keep one client connected

A DATEV sign-in that has to last longer than a working day, for example for workflows that run
overnight, can be kept for **one client**. On the DATEV tile, select **Keep one client connected**,
enter the client as consultant number and client number (such as `455148-1`), and sign in at DATEV.
Hive asks DATEV for offline access to that client: DATEV keeps the sign-in for up to 2 years from
each time Hive uses it. DATEV grants it for exactly one client, so such a connection reads and
changes only that client. If your DATEV sign-in cannot see the client, DATEV refuses the sign-in.

DATEV does not list clients for such a connection, so Hive answers it itself: asking for your DATEV
clients on it shows its one client by its number. A search by name reads that client's own record
first and finds it only when its real name matches, so Ask and agents never mistake it for another
client. They use that client's number without looking it up. A request about another client is
stopped before anything is sent, with a note that the connection is kept for its own client. A
workflow's **Use a connected app** step is held to the same rule: when the person it runs as has only
a kept connection, a step naming another client, such as a production client on a sandbox
connection, is refused before DATEV is asked.

You can see and end what you let Hive keep in DATEV's own **Verbundene Anwendungen** page
(apps.datev.de/tokrevui), linked from the tile. To remove a connection, disconnect it in
**Integrations**: Hive deletes its copy of the sign-in and asks DATEV to end both its tokens.

### Connect more than one DATEV account

A firm often works with more than one DATEV account: several consultant numbers or DATEV logins, or
access a client granted for itself. You can connect each of them:

* **Each kept client is its own connection.** Once DATEV is connected, select **Keep another
  client connected** on a connected DATEV tile for each further client, and sign in at DATEV with
  the DATEV login that can see it. Each connection shows in
  **Integrations** with its client, for example **DATEV (sandbox) · client 455148-1**. The label is
  the client's consultant number and client number, never anything secret.
* **One ordinary sign-in.** Beside them you can keep one ordinary DATEV sign-in, shown as
  **DATEV (sandbox)**. While you have only kept clients, a connected DATEV tile offers **Sign in to
  DATEV** to add it. Connecting it again, or keeping the same client again, reconnects that
  connection rather than adding a second one.
* **Disconnecting one leaves the others.** Disconnecting a connection ends only its own sign-in.

Every connection is still your own: Hive never uses one member's DATEV account for another member.

Hive uses the account that holds the client:

* **Ask and agents** list each account's DATEV tools under the account's name, so *"List my DATEV
  clients"* lists the clients of every account, each with the account it comes from. A change is
  prepared on the account whose own read showed its client, and its approval card is for that
  account.
* **A Use a connected app step** reads or changes a client through the account that keeps it, and
  otherwise through your ordinary sign-in. The cash register and property tax tools name no
  client, so set the step's **DATEV account** to the client the account to use keeps, such as
  `455148-2`. A read that names no client and no account, such as listing clients, reads every
  account and names each. When Hive cannot tell which account to use, the step stops, names your
  DATEV accounts and asks you to set the step's **DATEV account** or name the client; nothing is
  sent.
* **Triggers** check each watched client through the account that holds it, so no event is raised
  twice. Client list events come from your ordinary sign-in, or, without one, from each kept
  client.

## Read DATEV data

Ask in plain words, in Ask or in an agent that uses your DATEV connection, or read one thing
exactly in a workflow with a [**Use a connected app**](https://docs.get-hive.ai/workflows/workflow-steps.md#use-a-connected-app)
step:

* *"List my DATEV clients"*
* *"Show the accounting basics of client 455148-1: fiscal years, account length and ledgers"*
* *"Which file types does client 455148-1 take for an upload?"*
* *"Show the fiscal years and the sums and balances for client 455148-1 in 2025"*
* *"List the debtor and creditor accounts of client 455148-1 in 2025"*
* *"Read the account postings for account 1200 of client 455148-1 in 2025, with document links"*
* *"Show the account postings of client 455148-1 for January 2023"*
* *"Read the agricultural financial statement of client 455148-1 for 2023"*
* *"How did my last bookings import for client 455148-1 end?"*
* *"Which bookings of client 455148-1 in January 2023 have no linked receipt?"* (Hive reads the
  postings with their document links: a posting with no link has no receipt)
* *"Check this booking file against the DATEV format"* (a DATEV-Format file in your Library)
* *"Did the cash register import for client Café Muster on 4 November succeed?"* (see
  [Cash register, Meine Steuern and property tax](#cash-register-meine-steuern-and-property-tax))
* *"Show me the open customer items (OPOS) for client 455148-1 older than 30 days, with amounts and
  customers"*
* *"Summarise the BWA of client 455148-1 for October 2026: revenue, main costs, result, and change
  against last year"*
* *"Which DATEV data transfer jobs failed or finished with warnings this week, by client?"*
* *"What is client 455148-1's VAT position for October 2026 based on the postings, before the VAT
  return is filed?"*
* *"Which supplier invoices for client 455148-1 are due this week, and what is the total?"*

A client is named by its consultant number and client number, such as `455148-1`. You can also
name it as DATEV does, such as *"Show the open items of Musterfirma GmbH"*: Hive looks the client up
in your DATEV client list itself and does not ask you for its number.

Hive's own upload history covers only the uploads you approved in that chat. For the imports DATEV
itself ran, such as *"Which Buchungsdatenservice uploads ran in November?"*, Hive reads DATEV's
import jobs for the client.

| What Hive reads | DATEV API |
| - | - |
| Your clients (every page, up to 2,000, or one page you ask for), and one client's master data | `accounting:clients` |
| A client's accounting basics (fiscal years with their start and end, account length, chart of accounts, which ledgers exist), document types and upload rules | `accounting:documents` |
| The status, outcome and protocol of an invoice-data job | `accounting:dxso-jobs` |
| A client's import jobs (DATEV-Format) from any software, and how one ended | `accounting:extf-files` |
| Fiscal years, ledger accounts (optionally with debtors and creditors), sums and balances, accounting sequences, terms of payment, agricultural financial statement | `accounting:dataexchange` (paid DATEV API) |
| Account postings, and quantity and weight balances (agriculture and forestry) | `accounting:dataexchange` (paid DATEV API) |
| Open customer items (OPOS) and a short BWA, both worked out by Hive from the data above (see [Open items and BWA](#open-items-and-bwa)) | `accounting:dataexchange` (paid DATEV API) |
| Open supplier items with due dates and a VAT position before the return, both worked out by Hive (see [Supplier items and VAT position](#supplier-items-and-vat-position)) | `accounting:dataexchange` (paid DATEV API) |
| Which transfer jobs failed or finished with warnings, by client (see [Transfer jobs by client](#transfer-jobs-by-client)) | `accounting:extf-files`, `accounting:dxso-jobs` |

DATEV's clients API filters only by consultant number and client number, so Hive reads the whole
list and finds a client by name itself, ignoring upper and lower case and spaces. A filter DATEV
does not take, such as a client name, is refused before anything is sent to DATEV.

When DATEV's document management (Belege online) cannot be read for a client, the accounting
basics come from DATEV accounting (`accounting:dataexchange`) instead: the current fiscal year's
start and end, the chart of accounts (such as SKR04) and the account length. The answer says where
they came from and that document management could not be read, so whether it is available and which
ledgers exist is then not shown.

A fiscal year can be named by its year, for example 2025: Hive uses the client's fiscal year that
starts in that year. If none or more than one does (a short fiscal year), Hive reads nothing and
lists the client's fiscal years so you can pick one. Account numbers are identifiers: Hive hands
them on as account numbers and tells the AI to write them digit for digit, such as 50000, never as
an amount such as 50,000. DATEV's accounting data comes with account numbers in DATEV's technical
length (account 1200 of a client with 4-digit accounts is 12000000); Hive writes them in the
client's own account length, such as 1200 for a bank account and 10003 for a debtor, and finds an
account by either number.

DATEV sends the agricultural financial statement as a table (CSV). Hive returns its rows as DATEV
wrote them, with figures in German number format, and DATEV's plausibility check (correct or
faulty).

DATEV prepares account postings, and quantity and weight balances, as an export of the whole
fiscal year, from what DATEV Rechnungswesen last archived: bookings you just imported show there
only once the client's accountant has taken them into DATEV Rechnungswesen. Hive starts it and waits up to about 20 seconds; if DATEV is still preparing it, Hive
says so and reads it when you ask again. Starting an export changes no booking. Ask for a month or
a date range, such as January 2023, and Hive keeps only the postings dated in it, so the first 500
it shows are from that period. When you ask for one account's postings or a period, Hive looks
through up to 10 pages of the export and says which pages it did not read. A page of the export can
hold up to 50,000 postings: Hive reads the first part of a page that large and says so, so ask for
one account's postings or one month when a client books a lot. Because
exports are part of a paid DATEV API, Hive reuses an export of the same client, fiscal year and
kind started in the last hour, and starts at most five exports an hour per DATEV connection; past
that, it tells you when it can start one again. An agent running on a schedule or an event never
starts one on its own.

What DATEV returns is your data for that answer only: it is not added to Signals or the Brain, and
Hive reads it as information, never as instructions.

### Open items and BWA

DATEV's own open items list (OPOS) and BWA come from **DATEVconnect Rechnungswesen**, which runs on
the firm's own DATEV installation and which Hive is not connected to. Hive therefore works both out
from the accounting data it can read, and every answer says that it is derived:

* **Open customer items (derived from postings).** Hive reads the account postings of the fiscal
  year (the paid export above, reused and limited the same way) on the client's debtor accounts
  (10000 to 69999 for a client with 4-digit accounts). It groups them by invoice number
  (Belegfeld 1, the number DATEV itself keeps open items by) and keeps each invoice whose postings
  do not add up to zero, so part payments leave the rest open and a fully paid invoice drops out.
  Each item shows the customer's name and account, the invoice number and date, the open amount and
  its age in days, with totals in 0-30, 31-60, 61-90 and over 90 days. Ask for items older than a
  number of days, or for one customer. Hive lists up to 150 items, oldest first (the totals cover
  them all), reads up to 10 pages of the export and says which pages it did not read, and counts
  postings without an invoice number separately because they cannot be matched. Items booked only
  in DATEV's open items ledger, without postings in the fiscal year, are not seen.
* **Short BWA (derived from sums and balances).** For a month, Hive groups the client's monthly
  account balances into revenue, material, personnel, rooms, other costs and the result (revenue
  less all costs), for the month and the year to date, each with the same month a year earlier and
  the change, and names the three largest accounts of each cost line. It uses these account
  ranges (the first four digits of each account):

  | Line | SKR03 | SKR04 |
  | - | - | - |
  | Revenue | 8000-8999 | 4000-4999 |
  | Material | 3000-4099 | 5000-5999 |
  | Personnel | 4100-4199 | 6000-6199 |
  | Rooms | 4200-4299 | 6300-6399 |
  | Other costs | 2000-2999, 4300-4999 | 6200-6299, 6400-6999, 7000-7999 |

  "Other costs" includes depreciation and the neutral, interest and tax accounts, netted. This is a
  short summary, not DATEV's official BWA report: its lines and any adjustments the accountant set
  up in DATEV can differ. Clients on other charts of accounts (such as SKR14) are not summarised.

### Supplier items and VAT position

Both are worked out by Hive from the accounting data it reads, and each answer says so:

* **Open supplier items with due dates (derived from postings).** As for the open customer items,
  Hive reads the account postings of the fiscal year, here on the client's creditor accounts (70000
  to 99999 for a client with 4-digit accounts), groups them by invoice number and keeps each supplier
  invoice whose postings do not add up to zero. DATEV's postings carry no due date and a supplier's
  terms of payment are not part of what Hive reads, so each item is due a number of days after its
  invoice date: 30 unless you give the supplier's terms (*"with 14 days' payment terms"*). Ask for the
  items due in a range, such as this week, and Hive totals them. Up to 150 items are listed, earliest
  due first; the totals cover them all.
* **VAT position before the return (derived from sums and balances).** For a month, or a quarter,
  Hive adds up the monthly balances of the client's standard revenue and VAT accounts: revenue at
  19 % and at 7 % and tax-free intra-EU supplies (net), output VAT, input VAT, and the VAT payable
  (output less input; a negative figure is a refund). It is not the official advance VAT return
  (UStVA), which is prepared and sent in DATEV Rechnungswesen, and it leaves out VAT booked on other
  accounts, corrections and reverse charge. It uses these accounts (the first four digits):

  | Line | SKR03 | SKR04 |
  | - | - | - |
  | Revenue at 19 % (net, Kz 81) | 8400-8409 | 4400-4409 |
  | Revenue at 7 % (net, Kz 86) | 8300-8309 | 4300-4309 |
  | Tax-free intra-EU supplies (Kz 41) | 8125 | 4125 |
  | Output VAT | 1770-1779 | 3800-3819 |
  | Input VAT (Kz 66) | 1570-1579 | 1400-1409 |

### Transfer jobs by client

Ask which DATEV transfers failed or finished with warnings, for the last 7 days or since a day, and
Hive lists them by client: each client's booking imports (DATEV-Format files from any software,
failed or imported with validation notes) and the invoice-data jobs Hive started for you that DATEV
did not take in full. It reads up to 30 clients at a time; name the clients to read others. DATEV
lists invoice-data jobs one at a time only, so jobs other software started are not in the list, and
Hive keeps the ones it started for about a week, finished or not.

### Check a booking file against the DATEV format

Hive can check a DATEV-Format booking batch (EXTF Buchungsstapel, CSV) in your
[Library](https://docs.get-hive.ai/library/library.md) before it is sent: the header and the booking period it names, the
column names, and each booking's amount (a decimal comma, at most two decimals), debit or credit mark
(S or H), account and contra account, document date (a real day inside the booking period),
receipt link and cost centres (KOST1 and KOST2: at most 36 letters, digits, spaces and `. _ / -`).
It counts the bookings that carry a cost centre. It lists each problem by line and column, up to 50, and counts the rest. The check is a
read: DATEV is not called and nothing is sent. Files up to 5 MB and 10,000 bookings are checked; a
larger one is refused unread. A file saved as UTF-8 with a byte order mark, as Excel saves CSV, is
read like any other. Name the file in the chat (*"check TEST EXTF Buchungsstapel 2026-11.csv
against the DATEV format"*): Hive finds it in your Library and checks that file.

Ask Hive also reads every booking in such a file with all of its columns (amount, debit or credit
mark, account, contra account, tax key, document date, document number and booking text), and
names the client and the booking period from its header. So you can ask Hive to send the bookings
of your own file to DATEV: it checks the file, then prepares the import as a change you approve
(see [Make changes in DATEV](#make-changes-in-datev)).

When DATEV refuses a read or a change, Hive gives its own explanation followed by DATEV's own
reason, for example a fiscal year or a client DATEV does not know, so the request can be corrected.
When DATEV gives no reason in words, Hive still names its HTTP status and its error code (such as
`DCO01019`).

Hive asks you to reconnect DATEV only when DATEV refuses to renew your sign-in. Other refusals mean
something else, and connecting again does not change them:

| What Hive says | What it means |
| - | - |
| DATEV no longer accepts this connection. Reconnect DATEV | DATEV refused to renew your sign-in (it lasts about 11 hours). Connect DATEV again from **Integrations**. |
| DATEV refused the call even with a freshly renewed sign-in | Your connection works, and other DATEV reads in the same chat do too, but this DATEV product (for example payroll data or Personalakte) is not licensed or authorised for that client or your DATEV user. Your DATEV administrator or tax consultant grants it in DATEV. |
| DATEV's cash register API does not accept this kind of DATEV sign-in | DATEV's cash register API answered "Wrong IDP configured": it takes only the DATEV sign-in its cash register product (DATEV MeinFiskal) is set up for, not the sign-in Hive connects with. |
| The client has no Belege online | The client's DATEV services do not include Belege online (DATEV's Belegbilderservice), so DATEV has no document types or upload rules for it. The accounting basics still come from DATEV accounting. The tax consultant sets up Belege online in DATEV. |
| DATEV refused to answer the document types or upload rules without a reason | DATEV answered HTTP 400 with no error code or reason. An upload does not need either: Hive still prepares the upload card, without a document type, and DATEV checks the file itself when it arrives. There is nothing for you to fix. |
| Hive's DATEV app is not subscribed, or your sign-in was not given access | The DATEV API is not set up for Hive's DATEV app yet, or your sign-in predates it. See the note at the top of this page. |

For payroll data, a range whose last month is its first month is read as that one month (DATEV
refuses a range that does not end after it starts). If DATEV has no payroll report PDF for the month
and report codes you asked for, Hive says so and points to the payroll report list, whose period
names the month to ask for.

When Hive updates its DATEV tools, your connection picks them up the next time you use it. You never
need to re-sync DATEV on the Integrations page.

### Read e-invoices

Hive reads German e-invoices in your [Library](https://docs.get-hive.ai/library/library.md): XRechnung in either syntax (UBL or
CII XML) and ZUGFeRD or Factur-X (the XML inside the PDF). For each one it shows the invoice number
and date, the seller and the buyer with their VAT IDs, the net, VAT and gross totals, each VAT rate
and the invoice lines, and the invoice-data entry it becomes. When you send an e-invoice to DATEV as
invoice data, its number, date, gross amount, the supplier (an incoming invoice) or customer (an
outgoing one) and its VAT come from the file itself; an invoice with several VAT rates is one entry
split by rate. If an entry you approve differs from the e-invoice it attaches, Hive sends nothing and
says which values differ.

The check is a read and calls DATEV for nothing. Hive never follows a DTD or an entity in an XML file
(a file that declares one is refused unread), and reads at most 2 MB of XML, a PDF of at most 10 MB
and at most 50 files embedded in it. A credit note is not sent as invoice data; upload it as a
document instead.

## Send email attachments and cloud files to DATEV

DATEV's uploads take files from your Library. Ask saves the files you name into your Library first,
then prepares the DATEV card for them, so you can ask in one go:

* *"Upload the invoice attached to the Outlook email from Muster GmbH to DATEV Belege online for
  client 455148-1 as Rechnungseingang"*
* *"Upload every PDF in the SharePoint folder Belege/2026-10 to DATEV Belege online for client
  455148-1 as Rechnungseingang and tell me which ones failed"*
* *"Find the receipts in my Gmail from Bahn since 1 October and upload them to DATEV Belege online"*
* *"Upload the documents Anna Muster emailed me for her 2025 tax return to Meine Steuern, sorted
  into the right folders"*
* *"Upload every file in the OneDrive folder Steuer/2025 to DATEV Meine Steuern for Anna Muster, tax
  year 2025, into the folder Belege"*
* *"Send our outgoing invoices for October from Stripe to DATEV for client 455148-1 as structured
  invoice data with the PDFs attached"*
* *"Take the XRechnung and ZUGFeRD e-invoices in my Outlook inbox from this week and send them to
  DATEV with their structured data"*

| Source | What Hive saves |
| - | - |
| Outlook | A file attached to an email in your own mailbox, named by its file name when the email has several. Hive reads the attachment's details again first: an attached email, a link or a picture inside the email body is not saved. |
| Gmail | A file attached to an email in your own Gmail, named by its file name when the email has several. The name matches in any upper or lower case and spacing, and an email's whole conversation is searched when Hive is given the conversation. Gmail's own attachment ids are long, and any length Gmail uses is read. |
| SharePoint, OneDrive, Google Drive | A file in your own drive or a document library you can open, or every file directly in one folder (sub folders are listed as skipped, not opened; a folder of more than 20 items is refused). Google Docs, Sheets and Slides are not documents DATEV takes. |
| QuickBooks, Xero, Stripe | The PDF of an outgoing invoice an invoice read showed. Hive reads the invoice first, then its PDF; Xero bills are not outgoing invoices. A Stripe invoice's PDF is fetched only from Stripe's own site, once the invoice is finalised. |

* **Your own Library.** Files are saved at the top of your Library or in a folder selected for the
  chat that you can edit, never in a folder you can only view. Saving them sends nothing to DATEV.
* **Bounded.** At most 20 files at a time, each at most 20 MB and 100 MB together. Only PDF, PNG,
  JPEG, TIFF and XML files are saved, told from their contents, not their names.
* **Read as you.** Every file is read through your own connection, with read requests only. A file
  Hive could not save is listed with the reason, and the others are still saved. The reason says
  what went wrong: an id the app did not recognise, a connection to reconnect, an app limiting
  requests for a minute, a file or email too large to read, a request Hive does not send because it
  is not a read, a reply from the app Hive could not read, an error on the app's side, or no answer
  in time.

For Belege online, one approval card then uploads all the saved files, each its own DATEV document.
The card lists the files one a line, each with its Library file, document type, note and
fingerprint. A file that changed after the card was prepared
stops the whole upload before anything is sent. If DATEV refuses a file, the others are still
uploaded, and the card's result lists per file what DATEV took and what it refused, with DATEV's
reason. Ask *"Tell me which uploads failed and why"* and Hive reads that back from the chat's upload
cards, without calling DATEV. Meine Steuern takes one document per card, in the tax year's folder
you choose.

The same works for a file already in your Library (*"Upload TEST receipt 5 Nov.pdf from my Library
to DATEV Belege online for Musterfirma"*): the card names the Library file and the client. Hive
finds a client you name in your DATEV client list, and a Meine Steuern client and folder in Meine
Steuern's own lists. If a change still needs something only you know, such as the contact person an
eAU request names, Ask asks you for it rather than preparing a card without it.

## Payroll, sick notes and HR documents

Hive works with DATEV's payroll programs, **LODAS** and **Lohn und Gehalt**, through DATEV's HR
APIs. Ask in plain words, for example:

* *"Has the October payroll been run for client 455148-1?"*
* *"Which payroll clients have not sent this month's changes yet?"*
* *"Get the payslips for client 455148-1 for October 2026 from DATEV"*
* *"Get the payroll journal (Lohnjournal) and the wage tax summary for client 455148-1 for October
  2026"*
* *"Show the gross totals of every employee of client 455148-1 for September and October 2026"*
* *"Read the hourly wages of employee 101 in client 455148-1 as of November"*
* *"Ask the health insurer for the eAU of employee 101 from 2 November"*
* *"Send this payroll import file to client 455148-1 for October"*
* *"Add 12 overtime hours (wage type 200) for employee 104 of Musterfirma GmbH for November"*

Changes you give in the prompt, such as hours, wage types or a new wage, go to DATEV as payroll data
on an approval card: you do not need an import file. If you do not say whether the client uses
LODAS or Lohn und Gehalt, Hive checks the client's services in DATEV and otherwise sends to LODAS.
A new employee (*"Create TEST QA Employee in DATEV payroll for client 455148-1, starting
1 December"*) and an eAU request are prepared the same way, as a DATEV approval card.

Payroll data uses DATEV's own field names. A new employee needs at least a surname. If you give
personal data, it needs the employee's sex, and an address needs a postal code and country. Hive
checks every record against DATEV's fields when it prepares the approval card, so a card never shows
a field DATEV does not take, such as an invented `social_insurance.health_insurer_name`. Ask
corrects the record or asks you for the missing value, and the error names the field by its path and
the fields DATEV does take. Hive checks again before it sends anything.

An eAU request needs only the employee's personnel number and the first sick day. Naming a contact
at the employer for the health insurer is optional. If you name one, DATEV needs the contact's name,
telephone, company name, postal code, city and street. DATEV's client record holds no address, so
Ask asks you once for every detail you have not given, all in one question. If any value DATEV needs
is missing, Ask asks you for exactly that value, such as `contact_person.street`, rather than
ending without a card.

| What Hive reads | DATEV API |
| - | - |
| Which payroll reports (payslips, income tax certificates, payroll accounts, journals and DATEV's other report types) exist for a client and month, for which employees, and since when; which report types your sign-in may read for a client | `hr:payrollreports` |
| The payroll reports themselves for a month, such as the payslips (LOBN), the payroll journal (LOJO) and the wage tax return (LSTA), for all employees or one, read as text | `hr:payrollreports` |
| Which payroll clients' month has been run, and the last month run for the others | `hr:payrollreports` |
| The clients you may send payroll import files to, and the state of a file Hive sent (uploaded, imported, corrupted or deleted) | `hr:files` |
| Payroll results for all employees or one, for a month or a range: master data, pay components and totals, tax, social security, accounting records and absences; an employee's personnel number from the company's own | `hr:exports` |
| Payroll data as of a month: the client's own payroll data, employees, and one employee's employment periods, gross payments, hourly wages, month records and absences | `hr:exchange` |
| The health insurer's answer to an eAU request: the certificate's dates or its error message | `hr:eau` |
| The clients whose Personalakte you may send documents to | `hr:documents` |

DATEV fetches `hr:exchange` data from the payroll program as a job, because the program runs on the
firm's own computers: Hive waits about 10 seconds and then shows the data, or tells you the job is
still running and reads it when you ask again. The payroll program must be online for it.

**Payroll report documents.** DATEV hands a month's payroll reports of the types you ask for as one
PDF. Hive fetches it (up to 10 MB; ask for fewer types or one employee when it is larger), reads
its text and answers from it. The PDF itself is not added to the chat or your Library and is not
kept: open it in DATEV Arbeitnehmer online, or under the month's reports in Lohn und Gehalt or
LODAS. DATEV only hands the reports your DATEV sign-in may read for that client. A ZIP or any file
that is not a PDF is refused unread.

**Which clients have not sent this month's changes.** DATEV keeps no history of payroll changes
sent to it that Hive can read, so Hive answers from what DATEV shows: for each payroll client (up
to 25 at a time) whether the month's payroll has been run, meaning DATEV has its payroll reports,
and for the others the last month DATEV has a payroll journal for. A client whose month has not
been run may still have sent its changes; the answer says so.

> [!WARNING]
>
> **Payroll and sick-note data is yours alone.** Payroll and eAU data is special-category personal
> data (GDPR Article 9). What Hive reads of it goes only to you, the member who connected DATEV: in
> your own chat or your own agent run. It is never added to the Business Brain or to Signals, Hive
> never learns from it, an agent running on a schedule or an event never reads it on its own, and a
> workflow's **Use a connected app** step does not offer these reads, because others may see a
> workflow's runs. Every payroll, eAU and Personalakte change, sending a payroll import file
> included, runs only from your own click on its approval card. If you share an Ask chat that holds
> payroll data, the people you share it with see that data too.

Payroll and HR changes:

| Change | What it does |
| - | - |
| **Send a payroll import file** | Sends one of your Library files in DATEV's ASCII import format (master data or current data, up to 3 MB) to a client for LODAS or Lohn und Gehalt, for the payroll clerk to import. Optionally, DATEV emails an address you give when it is ready. |
| **Add payroll data** | Adds employees, or one employee's employment periods, gross payments, hourly wages, month records or absences, valid from a month, in DATEV's own fields (refused before sending if a field is not one of DATEV's). |
| **Change payroll data** | Changes employees, an employee, an employment period, or an employee's gross payments or hourly wages, from a month on. |
| **Delete payroll data** | Deletes one employee's employment period or absence. |
| **Cancel a payroll data job** | Cancels a payroll data job the payroll program has not taken over yet. |
| **Ask for an eAU** | Asks the employee's health insurer, through DATEV, for the electronic certificate of incapacity for work (eAU) from a day. Hive needs the personnel number and the first sick day, and uses LODAS unless the client's services show Lohn und Gehalt. A contact at the employer for the insurer is optional; if you name one, Ask asks you once for its name, telephone, company name and address. |
| **Cancel an eAU request** | Cancels an eAU request Hive sent. |
| **Send a document to Personalakte** | Sends one of your Library files (PDF or image, up to 20 MB) to a client's DATEV Personalakte, where the payroll office files it to the employee. |

## Cash register, Meine Steuern and property tax

| What Hive reads or changes | DATEV API |
| - | - |
| **Reads:** the cash register tenants (companies in DATEV MeinFiskal) and what DATEV holds of a TSE's logs. **Changes:** send a cash register file from your Library (a cash point closing, transactions, a TSE export or another document) to a tenant's archive; send the report about the cash registers to the tax office | `cashregister:import` |
| **Reads:** private clients in DATEV Meine Steuern (with their master client id), their income tax years and folders. **Changes:** add an income tax year; send one of your Library files into a folder of a tax year, with a note | `my-tax:income-tax-documents` |
| **Changes:** send one of your Library files for a property (a land register extract, a plan, a contract; PDF, image, Word, Excel, PowerPoint or text, up to 20 MB) to DATEV DMS for a client, named by its master client id | Property tax file upload |

DATEV built the cash register API for registered cash registers, and its description names no
permission to grant at sign-in: Hive calls it with your DATEV sign-in, and DATEV says whether that
sign-in may use it. If DATEV answers that the wrong identity provider is configured, the cash
register API does not take the kind of DATEV sign-in Hive connects with; connecting again does not
change that. The property tax API has no reads: if DATEV DMS cannot take a file after the
upload, DATEV tells you in DATEV Mitteilungen.

The cash register archive takes files a cash register wrote (Kasse and TSE exports, cash point
closings). A cash book you keep yourself (Kassenbuch), such as a spreadsheet of cash income and
expenses in your Library, goes to the client's cash book as cash data instead: see **Send invoice or
cash data** under [Make changes in DATEV](#make-changes-in-datev).

Each cash point closing is its own file and its own approval card. DATEV's cash register API reads
back only its tenants and a TSE's highest signature counter, never which days' closings it holds or
how an import ended, so Hive cannot tell from DATEV which days of a month are missing. To answer
"did the import on this day succeed?", Hive keeps its own record of every cash register file it sends
from your DATEV connection for 90 days: the tenant, the file, the days it covers, when it was sent and
whether DATEV took it, refused it, or gave no clear answer. Ask reads that record, by tenant and day,
and says when an import was not sent from Hive (one made from other software must be checked in DATEV
MeinFiskal).

## Make changes in DATEV

| Change | What it does |
| - | - |
| **Upload a document** | Uploads one of your Library files (a receipt or invoice, PDF or image, up to 20 MB) to a client's documents in Unternehmen online, with an optional document type and note. Hive checks the client's upload rules first, and sends the file with the type its contents show, adding the matching extension (such as `.pdf`) when the Library name has none. |
| **Upload a stapled document** | Uploads 2 to 10 Library files, in order, as one stapled document (for example the pages of one invoice). |
| **Upload several documents** | Uploads up to 20 Library files to a client's documents in Unternehmen online on one approval card, each its own document, with one document type for all or one per file. If DATEV refuses a file, the others are still uploaded and the result lists each file's outcome. |
| **Send invoice or cash data** | Sends structured invoices (number, date, gross amount, account, the supplier of an incoming invoice or the customer of an outgoing one) to a client's receivables or payables, or cash entries (money in or out) to its cash book, as a DATEV invoice-data job, each optionally with its image. Hive writes the DATEV XML, creates the job, attaches the files and finalises the job, all in the one change you approve. A cash book spreadsheet becomes one cash entry per income or expense row; its opening balance is not an entry. A cash book in your Library needs no Excel connection: Hive reads the file and prepares the card in the same answer, titled **Send cash book to DATEV**. |
| **Cancel an invoice-data job** | Cancels an invoice-data job that has not been finalised yet. DATEV deletes everything the job holds. |
| **Import bookings** | Imports bookings (Buchungsstapel) into a client's accounting. Hive builds the DATEV-Format (EXTF) file from checked fields, never from free text, and never locks the bookings. Each booking can be linked to its receipt (Beleglink): name the receipt in your Library, and the same card uploads each receipt to the client's Belege online first and then imports the bookings linked to them. If DATEV refuses a receipt, the bookings are not imported, so no booking links a missing receipt; approving again does not upload a receipt twice. A booking can also link a receipt already in DATEV by its document id. Each booking can also carry a cost centre (KOST1) and a second cost centre or cost object (KOST2), at most 36 characters each; the card lists every cost centre and how many bookings carry it at the top, and the file shows it on each line. A batch built from Stripe or Shopify (see [Bookings from Stripe and Shopify](#bookings-from-stripe-and-shopify)) shows its account table at the top of the card. |
| **Import master data** | Imports debtors and creditors (business partners), account labels, or terms of payment as a DATEV-Format file. A row with an existing number updates it. Debtors and creditors from another system (such as FreeAgent) need no account numbers: Hive reads the client's existing debtor and creditor accounts and gives each new one the next free number in DATEV's range (debtors from 10000, creditors from 70000 at account length 4), shown on the card. If the client's debtor or creditor accounts change in DATEV before you approve, so the numbers would differ from the card's, Hive sends nothing and asks you to prepare the change again. Approving the same card again after the import sends nothing either, so those debtors and creditors are never created twice under new numbers. A contact with sales invoices becomes a debtor, one with bills a creditor; Hive asks only about contacts with neither, all in one question. This works for contacts from any connected system, such as FreeAgent or HubSpot: ask, for example, *"send all FreeAgent contacts to DATEV client 455148-1 as Debitoren and Kreditoren"*. Ask reads all of that system's contacts, rather than looking for a contact named like the DATEV client, and Hive previews the change as it prepares the card, so the card shows the numbers it picked. If Hive cannot read the client's accounts to pick them, it makes no master data card and says so in the answer, beside any other card it prepared. |
| **Reverse bookings** | Reverses bookings already imported, as a reversal batch (DATEV's Generalumkehr) of exactly those bookings, which takes them out of the account totals. Hive refuses to import a reversal built by hand (a batch named Storno or reversal, or a booking alongside its flipped twin) and uses this instead. New bookings whose text says Storno or Rückbuchung, such as a returned direct debit or a supplier credit note, import as usual. |

Ask for a change in plain words; you do not need to name Hive's tool. For example:

* *"Create an invoice data job for this invoice from Muster GmbH in client 455148-1"*
* *"Reverse the bookings I imported into client 455148-1 yesterday"*

A request to reverse, undo or cancel something (Storno, rückgängig) counts as a request for a
change: Ask gets two more steps for it (10 rather than 8) and keeps its last steps for preparing the
approval card, so a long look-up in DATEV first still ends on the card. Bookings you have just
imported do not show in the account postings yet; give the bookings as you imported them, or the
import job, and Ask reverses those.

"Reverse the bookings I just imported" means the most recent import approved and carried out in
the same chat. Ask takes its client, bookings and debit or credit sides from that import and
prepares the reversal card without asking you for them. It asks only when the chat has no import
and you name none. An import made in another chat counts only when you name it, for example by its
client and import job. If a reversal names a client nothing in the chat showed, Ask reads the
client first and prepares the card again once, rather than ending without one.

One booking import or reversal is always one change, and one approval card, however you list its
details: the fiscal year, account length, batch label and each booking, written with commas or as
bullet points, are details of that change, never separate requests. A reversal batch is labelled
"Storno" followed by the original label, within DATEV's 30 characters; Storno appears once,
wherever the label already had it.

Amounts may be written the German way (1.190,00) or with a decimal point; the card shows each one
as the number Hive will send. If the details Ask drafted for a change do not fit what DATEV takes,
Ask corrects them and prepares the card again once before telling you why nothing was prepared. A
preview is never a card of its own: the change's card already shows what it will send.

### Bookings from Stripe and Shopify

Ask can turn a month of Stripe balance transactions (charges, fees, refunds and payouts) or Shopify
Payments payouts with their fees into one booking batch for a client, on the same **Import bookings**
card as any other batch: for example *"Turn the Stripe payouts, fees and refunds for October 2026
into a DATEV booking batch for client 455148-1 on SKR03 and send it"*. The card starts with the
account table the batch uses, one line per kind of entry, such as *Stripe fees: 4970 against 1361*,
and every booking must use an account the table names, so a booking on an account you did not see
there is refused before the card exists. Typical accounts are a clearing account for the payment
provider, revenue (SKR03 8400, SKR04 4400), fees (SKR03 4970, SKR04 6855), revenue reductions for
refunds and the money in transit to the bank (SKR03 1360, SKR04 1460); check them with the client's
accountant. Shopify payouts need the `read_shopify_payments_payouts` access on the Shopify app.

### Who carries out a change

| Change | In Ask | A reusable agent or a workflow step its author chose it for |
| - | - | - |
| Upload a document, a stapled document or several documents, send invoice or cash data; send a document to Meine Steuern, property tax or the cash register archive; add a Meine Steuern tax year | An approval card you approve. Ask's **Act** level does not carry it out. | Runs as the change its author chose |
| Cancel an invoice-data job, import bookings, import master data, reverse bookings; send a payroll import file, add, change or delete payroll data, cancel a payroll data job; ask for or cancel an eAU; send a document to Personalakte; send the cash register report to the tax office | An approval card you approve | Only your own click on its approval card, always |

A workflow step whose change only you may make waits for your approval: the run pauses until you
approve or decline the card in [Signals](https://docs.get-hive.ai/approvals/review-and-approve.md), for up to seven days. If
the run ends first, for example because you cancel it, the card leaves Signals. If Hive cannot
confirm whether DATEV made a change you approved, the step fails and says so: check DATEV before
you run the workflow again.

An AI client connected over [MCP](https://docs.get-hive.ai/integrations/mcp-servers.md) cannot run, deploy or schedule a
workflow that changes DATEV, whatever access you gave it. Do that in Hive.

Every change follows these rules:

* **What you approve is what is sent.** The approval card shows the change's input: the client,
  the Library files, the invoices, the bookings or the master data.
  Hive builds the DATEV XML or DATEV-Format file from exactly that input. To see the file itself
  first, ask Hive to preview the change: the preview shows the DATEV XML, the DATEV-Format rows, the
  request, or each file's name, size and fingerprint.
* **The exact file.** Hive works out each Library file's SHA-256 fingerprint itself, so you are
  never asked for one, and the same file is the same change. When a change was previewed, the card
  carries the fingerprints the preview showed: if a Library file changes after that, Hive sends
  nothing and asks you to approve the new version. A change that was not previewed sends each file
  as it is when the change runs.
* **Never sent twice.** Each change is recorded with a key made from its exact content. The same
  change again is not sent again: its card says DATEV already received exactly this change, and
  when, and shows DATEV's whole message. To import the same bookings again on purpose, ask Hive to prepare the import again with a
  different batch label (for example "January bookings 2"); a changed label makes it a new change.
  If Hive did not hear whether DATEV took a change, it does not send it again for an hour: check
  DATEV, and approve it again yourself after that only if it is not there. Such a change is never
  sent again automatically, by an agent or a workflow. A document upload, alone or several on one
  card, can be retried at once, because DATEV refuses a second copy of the same document; a stapled
  document cannot.
* **Nothing half made.** If DATEV refuses part of an invoice-data job before it is finalised, Hive
  cancels the open job, so nothing of it is kept.
* **Sandbox only, for now.** While DATEV is in testing, changes run only against DATEV's sandbox.
* **Recorded.** Each change is written to the workspace's [audit log](https://docs.get-hive.ai/approvals/audit-log.md).
* **Refused with DATEV's reason.** When DATEV refuses a change before taking any of it, the card
  or the workflow step says so with DATEV's own reason, nothing was sent, and you can approve it
  again once corrected.

### What DATEV does not allow

* DATEV's documents API has no way to read, change or delete a document once it is uploaded.
* Bookings cannot be deleted; reverse them instead. Bookings and master data are imported, never
  edited in place.
* Only an invoice-data job that is still open can be cancelled; a finalised one cannot.
* Hive reads payroll report PDFs as text for the answer but does not add them to the chat or keep
  them: the PDFs stay in DATEV.
* DATEV's open items export returns no data yet, and DATEV's own OPOS list and BWA need
  DATEVconnect Rechnungswesen, so Hive's open items and short BWA are derived (see
  [Open items and BWA](#open-items-and-bwa)).
* DATEV's notification callbacks for payroll data jobs (REST hooks) are not used: Hive checks the
  jobs it started instead.

## Start a workflow from DATEV

DATEV has no webhooks, so Hive checks your DATEV connection about every 15 minutes for the
workflows that listen to it. In a workflow's trigger, choose **Connected app event**, pick your
DATEV connection under **Connected app**, and choose one or more events:

| Event | Starts a run when | Settings it needs |
| - | - | - |
| **New DATEV client available** | A client your DATEV sign-in can see that it could not before | — |
| **DATEV client no longer available** | A client your sign-in could see is gone | — |
| **DATEV client's services changed** | A client's services in DATEV changed | — |
| **DATEV job succeeded** | A bookings import, invoice-data job, postings export, payroll import file (imported) or payroll data job Hive started succeeded | — |
| **DATEV job failed** | Such a job failed | — |
| **DATEV job partly processed** | An invoice-data job was only partly processed | — |
| **DATEV job finished** | Such a job ended in any way, including a cancelled invoice-data job | — |
| **DATEV import finished** | An import job of a watched client ended, from any software | Clients |
| **New DATEV fiscal year** | A watched client has a new fiscal year | Clients |
| **New DATEV booking batch** | A watched client has a new booking batch in the fiscal year; optionally only once it is committed (festgeschrieben) | Clients; fiscal year optional |
| **DATEV account balance crossed a threshold** | An account's balance goes below or above a threshold | Clients, account, threshold, direction; fiscal year optional |
| **DATEV account balance changed** | An account's balance changes | Clients and account; fiscal year optional |
| **New DATEV payroll report** | DATEV created a payroll report for a watched client: its type, payroll month, when it was made and how many employees it covers, never who | Clients |
| **DATEV eAU answer received** | The health insurer answered an eAU request Hive sent: whether a certificate or an error came, never the employee or the dates | — |

Under **What to watch in DATEV**, name up to 10 clients by their DATEV client ids, and for a
balance the account, the threshold and whether it fires going **below the threshold** or **above
the threshold**. Without a fiscal year, Hive watches each client's newest. A credit balance counts
as negative. Each event reaches only the workflows whose settings raised it, and a crossing fires
once, until the balance crosses back. Each later crossing fires again, even between the same two
balances, and so does every change, a client's services switching back, or a client removed again
after it was added back.

The first check only notes what is already there — the clients, imports, fiscal years, batches,
balances and payroll reports — and so does the first check after a time when no workflow listened.
For payroll reports, the first check is the first one at which your DATEV sign-in may read a report
type for that client: reports that were already there when you got that access raise no event. A
job Hive started
is different: it is reported when it ends, even when it started after the first check and ended
before the next one. Hive checks the DATEV connections of each member who has a deployed workflow
listening to DATEV. Only your own
deployed workflows start from your connection, and these events are offered only when your own
DATEV sign-in is connected. Your DATEV sign-in is the connection a DATEV trigger needs: the
workflow's setup checklist does not ask you to connect DATEV again. An event carries ids, statuses, numbers and short names only.

* **Bounded.** Hive raises at most 20 client list events per check, and the rest on the next
  checks. It watches client lists of up to 2,000 clients, and reads each watched client's data once
  a check: at most 10 clients and 10 balances per connection. It checks up to 20 of the jobs Hive
  started each time, the ones it checked longest ago first, so jobs that wait a long time never
  hold up newer ones.
* **How long a job is watched.** A payroll import file and an eAU request are watched for 60 days
  (DATEV deletes a payroll import file left unimported for 60 days), a payroll data job for 30
  days, and every other job for 7 days. A job that ends after that raises no event. A payroll data
  read that Hive finished while you waited is not watched.
* **Nothing lost.** An event whose workflow could not be started is tried again on a later check.
  A job DATEV no longer answers for is dropped after a few failed checks, and a client DATEV cannot
  answer for keeps what Hive saw last.
* **Waits when DATEV does not answer.** If DATEV does not answer, or the client list cannot be read
  in full, Hive keeps what it saw last and waits longer before the next check.

## Use DATEV in a workflow step

A [**Use a connected app**](https://docs.get-hive.ai/workflows/workflow-steps.md#use-a-connected-app) step reads or changes
DATEV directly, with the arguments you state: for example, read a client's sums and balances after
**New DATEV fiscal year**, or import the bookings an Agent step prepared. Add it from **+** under
**Apps**, where your DATEV tools are listed once your DATEV sign-in is connected. The step offers
every DATEV change, and every read except the payroll and eAU reads, which stay yours alone: use
them in Ask or an agent.

## Related

> [card] [Workflow steps](https://docs.get-hive.ai/workflows/workflow-steps.md#use-a-connected-app)
>
> The Use a connected app step, its arguments and what it hands on.

> [card] [MCP servers](https://docs.get-hive.ai/integrations/mcp-servers.md)
>
> How Hive's own servers and vendor servers connect, and what Ask reads on its own.

> [card] [Accounts and autonomy](https://docs.get-hive.ai/integrations/accounts-and-autonomy.md)
>
> Personal connections, and how Read, Draft and Act apply to them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.