Z3 export format

The Z3 export hands the documents of an audit period over as one package, in the “Beschreibungsstandard für die Datenträgerüberlassung”: an index.xml that describes CSV tables, the tables, and the original files. This page describes the files as Acriva writes them. It is for everyone who reads, checks or imports the package.

State of the proof

Acriva’s tests read reference packages with a checker of their own, by the description in index.xml alone, and validate index.xml against the DTD gdpdu-01-09-2004.dtd. An import into the analysis software of a tax auditor is not confirmed yet: a pilot customer does the first real one. Until then this page describes what Acriva writes, not what an auditor’s software has accepted.

The package

An export is one download, a ZIP file named Z3-Export_<first year>-<last year>.zip, for example Z3-Export_2023-2025.zip.

Entry	Content
index.xml	The description of the tables.
ausgelassen.txt	How many documents of the selection the package left out, and why.
dokumente_<type key>.csv	One table per document type that has a document in the package.
rechnungen.csv	The invoices of the documents. Present only when at least one document has an invoice.
kontierung.csv	The allocation lines of the invoices. Present only when there is at least one line.
Belege/<document ID><.ext>	The original file of the current version of each document.

• <type key> is the key of the document type in lower case, with every character that is no ASCII letter or digit replaced by _: incoming-invoice gives dokumente_incoming_invoice.csv.
• An original is named by the document’s ID without hyphens, with the extension of its file name in lower case. The extension is kept when it has at most 8 ASCII letters and digits; otherwise the entry has none.
• The DTD is not in the package. index.xml only names it.
• The package is not stored. Acriva builds it again at every download, from what the downloading person may read at that moment. Two downloads of one export can therefore differ.

What a package holds

A package holds the documents

• of the chosen document types (the built-in types “Löschprotokoll” and “Verfahrensdokumentation” can’t be chosen),
• whose retention period started in the audit period, which is whole calendar years,
• that are not in the recycle bin, not being deleted and not in quarantine (every version quarantined), archived documents included,
• that the person who creates or downloads the export may read through their access rights, and
• whose current version is processed. A document that is still being processed or whose current version is in quarantine has no original to hand over.

Documents of the first three points that fail one of the last two are left out. The package counts them in ausgelassen.txt but names none: the file has a line with the period, then “Ausgelassen: keine.” or the number, and then the two causes (the downloading person may not read the document; its current version isn’t processed yet). It is UTF-8 without a byte order mark, with CR LF, like the tables, and in German, like the rest of the package. The number is this package’s: for the person and the moment of the download. The app’s list of exports and leftOutCount of the API (POST and GET /compliance/auditor-exports) show the number from when the export was created instead; when someone else downloads, or later, the two can differ.

Limits

Limit	Value
Documents per package	2,000
Size of the originals per package	1 GB (2^30 bytes)
Document types per export	1 to 50

The limits count for the whole package, not per table. An operator can lower the first two and never raise them. Above them nothing is created: the API answers 400 with the code auditor-export-too-large and the fields documentCount, sizeBytes, maxDocuments and maxBytes. A download answers the same when the selection has grown past the limits since the export was created.

index.xml

index.xml is UTF-8 without a byte order mark and starts with

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE DataSet SYSTEM "gdpdu-01-09-2004.dtd">

Element	Content
DataSet/Version	1.0
DataSupplier/Name	The name of the workspace.
DataSupplier/Location	Empty.
DataSupplier/Comment	“Datenträgerüberlassung (Z3) aus Acriva, Prüfungszeitraum 01.01.2023 bis 31.12.2025, erstellt am …”, with the day of the download in German time.
Media/Name	Z3-Export <first year>-<last year>. There is one Media.
Media/Table	One per CSV file, in this order: the document types by their key, then Rechnungen, then Kontierung.
Media/AcceptNoTables	true, only in a package without any table.

Each Table holds, in this order:

Element	Content
URL	The file name of the table.
Name	Dokumente_<type key> (the key in its own case, characters other than ASCII letters and digits as _, with the prefix F_ when it doesn’t start with a letter), Rechnungen or Kontierung.
Description	German, for example “Dokumente des Typs Eingangsrechnung”.
Validity/Range/From, To	The first and the last day of the audit period, with Validity/Format DD.MM.YYYY.
UTF8	The character set of the file.
DecimalSymbol	,
DigitGroupingSymbol	. (declared, because the DTD knows the two symbols only together or not at all; Acriva writes no digit grouping).
Range/From	2: the data starts in line 2, after the header line.
VariableLength/ColumnDelimiter	;
VariableLength/RecordDelimiter	CR LF
VariableLength/TextEncapsulator	"
VariablePrimaryKey, VariableColumn	One per column, the key columns first, each with Name, a German Description and its type.
ForeignKey	Only in Kontierung, when the package has Rechnungen: Name Dokument_ID, References Rechnungen.

A column’s type is one of:

In index.xml	Used for	Written as
AlphaNumeric	Text	See How values are written.
Numeric with Accuracy 0	Position	Digits.
Numeric with Accuracy 2	Amounts	Two decimals, , as the decimal symbol: 1190,00, -59,50.
Numeric with Accuracy 4	A number field of a document type	Four decimals: 12,5000.
Date with Format DD.MM.YYYY	Dates	15.03.2024

Names and descriptions are German, because the reader is a German tax authority. A character that XML 1.0 doesn’t allow is left out of the workspace’s name and of a description.

The tables

Every table is UTF-8 without a byte order mark. Line 1 names the columns, and every further line is one record.

dokumente_<type key>.csv

One record per document. The key is Dokument_ID.

Column	Type	Content
Dokument_ID	AlphaNumeric	The ID of the document in Acriva, a UUID with hyphens.
Titel	AlphaNumeric	The title of the document.
Aufbewahrung_Beginn	Date	The day the retention period started: December 31 of the year of the date its rule starts from, a date field of the type or the day the document arrived.
Aufbewahrung_Ende	Date	The last day of the retention period. Empty while it has no end.
Erfasst_am	Date	The day the document was created in Acriva, in German time.
Datei	AlphaNumeric	The path of the original in the package, for example Belege/0199c000000070008000000000000001.pdf.
SHA256	AlphaNumeric	The SHA-256 checksum of the original, in lower-case hex.
one per field	by the field	The fields of the document type, in the type’s order.

The field columns follow the document type as it is at the download:

• The column’s name is the field’s key, with every character that is no ASCII letter or digit replaced by _. A name that doesn’t start with a letter gets the prefix F_: 2nd-party gives F_2nd_party. A name that another column of the table already has, without regard to case, gets the prefix Feld_, and so does one whose currency column (<name>_Waehrung) would take such a name: a field titel gives Feld_titel.
• The column’s description is the field’s German label.
• A money field gives two columns: <name> (Numeric, 2 decimals) and <name>_Waehrung (AlphaNumeric, the currency code).
• A number field is Numeric with 4 decimals, a date field is Date.
• Every other field is AlphaNumeric and written as text: a yes/no value as ja or nein, a list as its items joined with ; (a list inside a list is flattened, empty items stay empty), a number as it is stored (1234.5, 1E+3). The rule for texts that look like a formula applies to the text that is written.
• A field that refers to an Akte, and a field that was removed from the type, give no column.
• A field without a value is empty.

rechnungen.csv

One record per document that has an invoice in Acriva. The key is Dokument_ID.

Column	Type	Content
Dokument_ID	AlphaNumeric	The ID of the document.
Rechnungsnummer	AlphaNumeric	The invoice number.
Rechnungsdatum	Date	The invoice date.
Faelligkeit	Date	The due date.
Lieferant	AlphaNumeric	The name of the vendor.
Lieferantennummer	AlphaNumeric	The vendor’s number (vendor account).
Waehrung	AlphaNumeric	The currency.
Netto	Numeric, 2 decimals	The net amount.
Steuer	Numeric, 2 decimals	The tax amount.
Brutto	Numeric, 2 decimals	The gross amount.

kontierung.csv

One record per allocation line. The key is Dokument_ID and Position; Dokument_ID refers to Rechnungen.

Column	Type	Content
Dokument_ID	AlphaNumeric	The ID of the document.
Position	Numeric, 0 decimals	The position of the line.
Betrag	Numeric, 2 decimals	The amount of the line.
Sachkonto	AlphaNumeric	The number of the G/L account.
Kostenstelle	AlphaNumeric	The number of the cost center.
Steuerschluessel	AlphaNumeric	The number of the tax key.

The two finance tables hold only invoices whose document is in the package and that the person may read.

How values are written

• Character set: UTF-8 without a byte order mark, declared per table with UTF8. The standard also allows ANSI (Windows-1252). Acriva writes UTF-8 because titles, vendor names and field values are Unicode, and Windows-1252 can’t hold all of them.
• Delimiters: ; between columns and CR LF after every record, also the last.
• Quoting: a text that holds ;, ", a carriage return or a line feed is written in ", and a " in it is doubled: "Rechnung 4711; Bürobedarf ""Nord""". Other values are written without quotes.
• Numbers: , as the decimal symbol, no digit grouping, a leading - for a negative amount, rounded half away from zero to the column’s decimals.
• Dates: DD.MM.YYYY.
• Empty: a missing value is an empty cell.

Texts that look like a formula

A spreadsheet reads a cell that starts with certain characters as a formula. So that a value from a document can’t run as one, Acriva writes a leading apostrophe ' before a text that

• starts with =, +, - or @, also after leading blanks, or
• starts with a tab, a carriage return or a line feed.

An invoice number -123 is '-123 in the package, and a title =Gutschrift is '=Gutschrift. The value in the package then differs from the value in the document by that one character. This applies to the AlphaNumeric columns Titel, Datei, the text fields of a document type and the texts of rechnungen.csv and kontierung.csv. Numeric and Date columns are never changed, so a negative amount stays -59,50.

Audit

Creating an export is in the audit log. Every download records one download per original in it, before the first byte leaves.