Skip to content

GoBD plugin (EN)

Claude edited this page Nov 20, 2026 · 7 revisions

Deutsch: GoBD-Plugin

GoBD compliance plugin

The GoBD plugin (id groovy.gobd-compliance, version 2.0) adds technical safeguards for the German GoBD (principles for the proper keeping and storage of books, records and documents in electronic form and for data access). It is a Java plugin and comes with YaBS as plugins/gobd-compliance.jar (source). Its messages and labels are in German.

A plugin alone does not make bookkeeping GoBD compliant: backups, access control and the company's procedure documentation are needed too (see Organisational notes). This page is no tax or legal advice.

Features

  • Finalizing on export: when an invoice, credit note, deposit or part payment invoice is created as PDF, ZUGFeRD or XRechnung, the plugin finalizes it (festschreiben, can be switched off). Orders, offers and confirmations are never affected.
  • Immutability: finalized documents and their positions are protected against changes of tax relevant fields and against deleting and the trash – in the user interface and when saving.
  • Open items workflow: payment status, part payments and dunning levels stay changeable and are logged.
  • No new print of finalized documents: print, PDF, preview and e-invoice open the archived file of a finalized invoice instead of creating a new one.
  • Snapshots of master data and positions at the time of finalizing.
  • SHA-256 hash chains over finalized documents, income, receipts and the audit log: SHA256(record ‖ "\n" ‖ previous hash), starting with 64 zeros. The record holds the SHA-256 of the archived file and the tax relevant data (number, dates, contact, amounts, tax, positions), so the check also finds changes made directly in the database. Older locks (before version 2 of the chain) are still checked with SHA256(file bytes ‖ previous hash).
  • Cancellation invoices instead of editing – numbered in a number format of their own, Cancellation invoice (see below).
  • Receipts of expenses and e-invoices as income (ZUGFeRD / XRechnung), archived byte-identical with SHA256SUMS.
  • Auditor access: the Z1 auditor view in YaBS (read only) and the Z3 export for IDEA (GDPdU).

Installation

  1. Get gobd-compliance.jar: it is in the YaBS zip in the folder openyabs/plugins/, and a download of its own in every release (for the installers .deb, .rpm, .msi, .dmg).
  2. Settings › Plugin Manager › Import Java plugin... and choose the file – or drop it onto the Plugin Manager. (Not via Classic plugins (database): YaBS recognizes the jar there too and installs it in the plugin list.)
  3. After the start the status bar says: GoBD-Konformitaets-Plugin (v2.0.0) vollstaendig geladen.

The plugin creates or extends its database tables (gobd_document_lock, gobd_audit_log, gobd_receipt, gobd_income_lock) when it starts.

Moving from the Groovy script gobd_compliance.groovy: the jar has the same id. Settings, archive folder and database tables stay. Installing the jar replaces the running script and keeps it as gobd_compliance.groovy.replaced; it is not loaded any more.

Needs YaBS 2.0.10 or newer.

Settings

Settings › Plugins › GoBD-Konformitaet:

Setting Default Description
Finalize invoices on export on finalizes invoices when PDF / ZUGFeRD / XRechnung are created. Off: only with the command or the button in the banner.
GoBD archive folder <plugin data folder>/gobd-archive where all archived originals (per year) and the Z3 exports go
Import e-invoices from the watch folder off checks the watch folder every 15 seconds and imports new ZUGFeRD PDFs / XRechnung XMLs as finalized income
Watch folder empty the folder of the automatic income import

Life cycle of an invoice

1. Draft

As long as an invoice is not finalized it can be edited or deleted. The view shows the badge GoBD: Entwurf (offen) and a banner with "Jetzt GoBD-festschreiben" (finalize now). New drafts are logged as DRAFT_CREATED.

2. Finalizing

On export, with Plugins › GoBD: 1. Beleg festschreiben or with the button in the banner:

  1. Number: without a final number (empty, ENTWURF…, DRAFT…) the plugin assigns the next number in the number format of the document type (Control panel › Formats); if none is set there, RE-YYYY-NNNNN (credit notes ST-YYYY-NNNNN). The year is the one of the invoice date.
  2. Status finished; the end date is set if empty.
  3. Mandatory data (§ 14 (4) UStG): number, issue date, delivery date, contact with street and city, amounts, at least one position. If something is missing, nothing is finalized.
  4. Archive: the file just created (ZUGFeRD PDF or XRechnung XML) is copied read only to <archive folder>/<year>/; without a file the plugin writes an XML with the data of the document.
  5. Hash chain and snapshots are stored in gobd_document_lock, the action is logged as FINALIZED, and the open document is shown locked at once.

3. After finalizing

The view shows GoBD FESTGESCHRIEBEN (or GoBD STORNIERT), a banner with "Originalbeleg oeffnen" (open the original) and "Stornorechnung erstellen" (create a cancellation invoice), and locks customer, address, number, dates, description and positions.

Area Behaviour Audit log
Tax relevant data (amounts, taxes, discounts, dates, number, description, customer, positions) locked BLOCKED_EDIT
Deleting / trash (document or position) locked BLOCKED_DELETE
Setting "cancelled" by hand locked (use a cancellation invoice) BLOCKED_MANUAL_CANCEL
Payment status, part payments allowed PAYMENT_STATUS_CHANGED
Dunning level allowed DUNNING_CHANGED
Customer master data allowed, with old and new values MASTERDATA_CHANGED
Print, PDF, preview, e-invoice open the archived file –

Numbers of cancellation invoices

Cancellation invoices have a number format of their own in Control panel › Formats: Cancellation invoice – free like any other (e.g. ST-[YEAR]-00001, STORNO-2026-001 or a range per user). The law does not prevent this: § 14 (4) no. 4 UStG only asks for a sequential number from one or more ranges that identifies the invoice once; the format is free. Counting goes on from the last cancellation invoice, numbers in use are skipped. Without a format of their own, cancellation invoices get ST-YYYY-NNNNN.

Expenses and receipts (GoBD Rz. 61–64)

  • Receipts are linked in the expense view (button, drag and drop or the e-invoice import) and stored byte-identical with SHA256SUMS in the receipts folder – not as BLOB in the database. Check them outside YaBS too: sha256sum -c SHA256SUMS.
  • Expenses with a receipt: badge GoBD BELEGABLAGE (n); amounts, tax, account and removing the receipt are locked, payment status and date stay changeable. Without a receipt: GoBD: OHNE BELEG with "Beleg verknuepfen & festschreiben" (link receipt and finalize).
  • Expenses with archived receipts can not be deleted.

Income from e-invoices

  • Plugins › GoBD: 7. ZUGFeRD / XRechnung als Einnahme importieren (or the watch folder) reads invoice number (BT-1), issue date (BT-2), due date (BT-9), partner, net (BT-109), gross (BT-112) and tax rate (BT-119) and creates finalized income. Without the mandatory fields the file is refused.
  • The original goes to <archive folder>/einnahmen/<year>/ with SHA256SUMS and a hash chain of its own (gobd_income_lock).
  • Duplicates (same file or same number) are refused.
  • In the income view without a receipt, "ZUGFeRD / Beleg verknuepfen" links a file to the existing income.

Existing data: plugin activated later or switched off in between

YaBS is often used for years without the plugin, or the plugin is switched off and on again. For the time it did not run, the plugin cannot add any protection afterwards – and it does not claim to. Instead it seals the existing data at every start and documents everything that happened without it:

  • At the start the plugin computes, in the background, a SHA-256 hash of every tax relevant record: invoices, credit notes, deposit and progress invoices with their positions, income, expenses, receipts of expenses and income, older audit log entries without hash, and older locks. It compares them with the last state it knows (gobd_seal_state).
  • First activation: all existing data is sealed with today's date. The seal says explicitly that the protection starts then; nothing is back-dated.
  • Restart after a pause (plugin off, other workstations without it, changes by SQL): every record changed or deleted since then is recorded with its old and new content in gobd_seal_item and in the hash chain of the audit log (CHANGED_WITHOUT_PLUGIN, DELETED_WITHOUT_PLUGIN). The original content stays visible (GoBD Rz. 58). YaBS shows this as a message at the start. Records added meanwhile are sealed.
  • While the plugin runs, it follows every save. If a sealed older record is changed (e.g. an old invoice that was never finalized), this is not blocked but logged with the old content (SEALED_RECORD_CHANGED). New documents are protected by finalizing.
  • Every seal is a link of a hash chain of its own (gobd_seal) and an entry of the audit log, with the time without the plugin, the numbers and a hash over all existing data. This happens again at every start, any number of times.
  • Start and stop of the plugin are in the audit log: PLUGIN_STARTED with version, user and settings (archive folder, finalizing on export, income import), PLUGIN_STOPPED. If the session before ended without a stop (crash), the next start says so.
  • GoBD: 3. Archiv-Integritaet pruefen also checks the chain of the seals and reports records changed outside the plugin since the last seal. GoBD: 9. Bestand jetzt versiegeln seals at once.

Record in the procedure documentation (Verfahrensdokumentation) since when the plugin is active (first seal) and that records from before are protected from that point on. No warranty – ask your tax advisor if in doubt.

Commands and search

In the menu Plugins and in Search anything (Shift Shift):

  1. GoBD: 1. Beleg festschreiben – choose an invoice that is not finalized yet.
  2. GoBD: 2. Beleg stornieren (Stornorechnung) – creates a finalized cancellation invoice (a credit note with the same, positive amounts; the type reduces), sets the original to CANCELLED and links it via cancels_document_id. The cancelled invoice is also the reference of the cancellation invoice on the document (<item.correctedinvoice>) and in the e-invoice (type 381, BT-25/BT-26).
  3. GoBD: 3. Archiv-Integritaet pruefen – checks in the background all archived files, the hash chains of invoices and income against the archive and the database, and the chain of the audit log; it reports all problems, not only the first.
  4. GoBD: 4. Betriebspruefer-Export (Z3 / IDEA ZIP) – see below.
  5. GoBD: 5. Pruefer-Ansicht oeffnen (Z1 Read-Only Tab) – four tabs (invoices and cancellations, imported income, expenses and receipts, audit log) with a year filter; a double click opens the original.
  6. GoBD: 6. Eingangsbelege pruefen (SHA256SUMS) – adds receipts of expenses and income not chained yet to the chains gobd_receipt / gobd_revenue_receipt and checks receipts and income originals against the database, the hash chain and SHA256SUMS.
  7. GoBD: 7. ZUGFeRD / XRechnung als Einnahme importieren.
  8. GoBD: 8. Audit-Log als Textdatei oeffnen – writes the complete audit log (all years) as a UTF-8 text file to <archive folder>/audit-log/ and opens it in the system's text editor (also the button "Audit-Log als Textdatei" in the auditor view). One line per entry (separated by ;) with prev_hash / row_hash; the header lines explain the computation, the end shows the end of the chain and the result of the check. So the chain can be recomputed outside YaBS too.
  9. GoBD: 9. Bestand jetzt versiegeln – seals the existing data at once and reports what was changed or deleted without the plugin (see above).

The search finds finalized documents and income by number; a click opens the original.

Z3 export (IDEA / GDPdU)

YaBS_GoBD_Z3_Export_<year>_<timestamp>.zip in the archive folder, for a year of your choice:

  • index.xml and gdpdu-01-09-2004.dtd – the description for the import into IDEA,
  • rechnungen.csv, rechnungspositionen.csv, kunden.csv, audit_log.csv,
  • ausgaben.csv, eingangsbelege.csv, einnahmen.csv,
  • belege/, belege/eingangsbelege/, belege/einnahmen/ – the originals,
  • VERFAHRENSDOKUMENTATION_TECHNIK.txt – the technical locking, snapshot and hash mechanisms.

Database tables

  • gobd_document_lock – per finalized document: document_id, chain_seq, document_number, status (FINALIZED / CANCELLED), finalized_at, finalized_by, customer_snapshot, positions_snapshot, archive_path, artifact_format, sha256_hash, prev_sha256_hash, cancels_document_id, hash_version, file_sha256, record_data (the hashed record). chain_seq is unique: two workstations cannot fork the chain.
  • gobd_income_lock – per imported income: original file, archive path, file SHA-256, chain hash, financial snapshot, hash_version, record_data.
  • gobd_receipt – the hash chain of the receipts of expenses (from expense_receipts), with the hashed record in record_data.
  • gobd_revenue_receipt – the same for the receipts linked to income in YaBS (from revenue_receipts); the Z3 export has them under belege/einnahmen/.
  • gobd_audit_log – the running log with time, user, object, action, old and new value, file hash; every entry is chained by prev_hash / row_hash (deleted or changed entries are found by the check).
  • gobd_seal, gobd_seal_state, gobd_seal_item – the seals of the existing data (hash chain), the last known hash per record with its content, and the records changed or deleted without the plugin with old and new content.

Limit of hash chains: whoever controls the database and the archive can recompute a whole chain. Only keeping the latest hash outside helps against that (e.g. in the Z3 export sent to the tax advisor, or with a qualified time stamp).

Organisational notes

  1. Backups: back up the archive folder, the receipts folder and the database regularly and keep them for the retention periods (§ 147 (3) AO, § 14b UStG).
  2. Access control: block or monitor direct write access to the database outside YaBS (especially to the gobd_* tables and items).
  3. Procedure documentation: VERFAHRENSDOKUMENTATION_TECHNIK.txt only covers the technical part; add your own procedures, responsibilities and approvals.

Clone this wiki locally