Z3-Exportformat

Der Z3-Export übergibt die Dokumente eines Prüfungszeitraums als ein Paket, im „Beschreibungsstandard für die Datenträgerüberlassung“: eine index.xml, die CSV-Tabellen beschreibt, die Tabellen und die Originaldateien. Diese Seite beschreibt die Dateien so, wie Acriva sie schreibt. Sie richtet sich an alle, die das Paket einlesen, prüfen oder importieren.

Stand der Prüfung

Acrivas Tests lesen Referenzpakete mit einem eigenen Prüfprogramm, allein nach der Beschreibung in index.xml, und prüfen index.xml gegen die DTD gdpdu-01-09-2004.dtd. Ein Import in die Prüfsoftware einer Betriebsprüfung ist noch nicht bestätigt: Den ersten echten Import nimmt ein Pilotkunde vor. Bis dahin beschreibt diese Seite, was Acriva schreibt, und nicht, was eine Prüfsoftware angenommen hat.

Das Paket

Ein Export ist ein Download, eine ZIP-Datei mit dem Namen Z3-Export_<erstes Jahr>-<letztes Jahr>.zip, zum Beispiel Z3-Export_2023-2025.zip.

Eintrag	Inhalt
index.xml	Die Beschreibung der Tabellen.
ausgelassen.txt	Wie viele Dokumente der Auswahl das Paket ausgelassen hat, und warum.
dokumente_<Typschlüssel>.csv	Eine Tabelle je Dokumenttyp, von dem ein Dokument im Paket ist.
rechnungen.csv	Die Rechnungen der Dokumente. Nur vorhanden, wenn mindestens ein Dokument eine Rechnung hat.
kontierung.csv	Die Kontierungszeilen der Rechnungen. Nur vorhanden, wenn es mindestens eine Zeile gibt.
Belege/<Dokument-ID><.ext>	Die Originaldatei der aktuellen Version jedes Dokuments.

• <Typschlüssel> ist der Schlüssel des Dokumenttyps in Kleinbuchstaben; jedes Zeichen, das kein ASCII-Buchstabe und keine Ziffer ist, wird zu _: incoming-invoice ergibt dokumente_incoming_invoice.csv.
• Ein Original heißt nach der ID des Dokuments ohne Bindestriche, mit der Endung seines Dateinamens in Kleinbuchstaben. Die Endung bleibt, wenn sie höchstens 8 ASCII-Buchstaben und Ziffern hat; sonst hat der Eintrag keine.
• Die DTD liegt nicht im Paket. index.xml nennt sie nur.
• Das Paket wird nicht gespeichert. Acriva erstellt es bei jedem Download neu, aus dem, was die herunterladende Person in diesem Moment lesen darf. Zwei Downloads eines Exports können sich deshalb unterscheiden.

Was ein Paket enthält

Ein Paket enthält die Dokumente,

• die zu den gewählten Dokumenttypen gehören (die eingebauten Typen „Löschprotokoll“ und „Verfahrensdokumentation“ stehen nicht zur Wahl),
• deren Aufbewahrungsfrist im Prüfungszeitraum begonnen hat, der aus ganzen Kalenderjahren besteht,
• die nicht im Papierkorb liegen, nicht gerade gelöscht werden und nicht in Quarantäne sind (alle Versionen gesperrt), archivierte Dokumente eingeschlossen,
• die die Person, die den Export erstellt oder herunterlädt, über ihre Zugriffsrechte lesen darf, und
• deren aktuelle Version verarbeitet ist. Ein Dokument, das noch verarbeitet wird oder dessen aktuelle Version in Quarantäne ist, hat kein Original zum Übergeben.

Dokumente der ersten drei Punkte, die einen der letzten beiden nicht erfüllen, werden ausgelassen. Das Paket zählt sie in ausgelassen.txt, nennt aber keines: Die Datei hat eine Zeile mit dem Zeitraum, dann „Ausgelassen: keine.“ oder die Zahl, und dann die beiden Gründe (die herunterladende Person darf das Dokument nicht lesen; die aktuelle Fassung ist noch nicht verarbeitet). Sie ist UTF-8 ohne Byte Order Mark mit CR LF, wie die Tabellen. Die Zahl gilt für dieses Paket, also für die Person und den Moment des Downloads. Die Liste der Exporte in der App und leftOutCount der API (POST und GET /compliance/auditor-exports) zeigen dagegen die Zahl beim Erstellen des Exports; lädt jemand anderes oder später herunter, können beide Zahlen abweichen.

Grenzen

Grenze	Wert
Dokumente je Paket	2.000
Größe der Originale je Paket	1 GB (2^30 Bytes)
Dokumenttypen je Export	1 bis 50

Die Grenzen gelten für das ganze Paket, nicht je Tabelle. Ein Betreiber kann die ersten beiden senken, nie anheben. Darüber wird nichts erstellt: Die API antwortet mit 400, dem Code auditor-export-too-large und den Feldern documentCount, sizeBytes, maxDocuments und maxBytes. Ein Download antwortet genauso, wenn die Auswahl seit dem Erstellen über die Grenzen gewachsen ist.

index.xml

index.xml ist UTF-8 ohne Byte Order Mark und beginnt mit

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

Element	Inhalt
DataSet/Version	1.0
DataSupplier/Name	Der Name des Arbeitsbereichs.
DataSupplier/Location	Leer.
DataSupplier/Comment	„Datenträgerüberlassung (Z3) aus Acriva, Prüfungszeitraum 01.01.2023 bis 31.12.2025, erstellt am …“, mit dem Tag des Downloads in deutscher Zeit.
Media/Name	Z3-Export <erstes Jahr>-<letztes Jahr>. Es gibt ein Media.
Media/Table	Eine je CSV-Datei, in dieser Reihenfolge: die Dokumenttypen nach ihrem Schlüssel, dann Rechnungen, dann Kontierung.
Media/AcceptNoTables	true, nur in einem Paket ohne Tabelle.

Jede Table enthält, in dieser Reihenfolge:

Element	Inhalt
URL	Der Dateiname der Tabelle.
Name	Dokumente_<Typschlüssel> (der Schlüssel in seiner Schreibung, andere Zeichen als ASCII-Buchstaben und Ziffern als _, mit dem Präfix F_, wenn er nicht mit einem Buchstaben beginnt), Rechnungen oder Kontierung.
Description	Deutsch, zum Beispiel „Dokumente des Typs Eingangsrechnung“.
Validity/Range/From, To	Der erste und der letzte Tag des Prüfungszeitraums, mit Validity/Format DD.MM.YYYY.
UTF8	Der Zeichensatz der Datei.
DecimalSymbol	,
DigitGroupingSymbol	. (angegeben, weil die DTD beide Zeichen nur zusammen oder gar nicht kennt; Acriva schreibt keine Tausendertrennung).
Range/From	2: Die Daten beginnen in Zeile 2, nach der Kopfzeile.
VariableLength/ColumnDelimiter	;
VariableLength/RecordDelimiter	CR LF
VariableLength/TextEncapsulator	"
VariablePrimaryKey, VariableColumn	Eine je Spalte, die Schlüsselspalten zuerst, jede mit Name, einer deutschen Description und ihrem Typ.
ForeignKey	Nur in Kontierung, wenn das Paket Rechnungen hat: Name Dokument_ID, References Rechnungen.

Der Typ einer Spalte ist einer von:

In index.xml	Verwendet für	Geschrieben als
AlphaNumeric	Text	Siehe Wie Werte geschrieben werden.
Numeric mit Accuracy 0	Position	Ziffern.
Numeric mit Accuracy 2	Beträge	Zwei Nachkommastellen, , als Dezimalzeichen: 1190,00, -59,50.
Numeric mit Accuracy 4	Ein Zahlenfeld eines Dokumenttyps	Vier Nachkommastellen: 12,5000.
Date mit Format DD.MM.YYYY	Datumsangaben	15.03.2024

Namen und Beschreibungen sind deutsch, weil eine deutsche Finanzbehörde sie liest. Ein Zeichen, das XML 1.0 nicht erlaubt, fehlt im Namen des Arbeitsbereichs und in einer Beschreibung.

Die Tabellen

Jede Tabelle ist UTF-8 ohne Byte Order Mark. Zeile 1 nennt die Spalten, jede weitere Zeile ist ein Datensatz.

dokumente_<Typschlüssel>.csv

Ein Datensatz je Dokument. Der Schlüssel ist Dokument_ID.

Spalte	Typ	Inhalt
Dokument_ID	AlphaNumeric	Die ID des Dokuments in Acriva, eine UUID mit Bindestrichen.
Titel	AlphaNumeric	Der Titel des Dokuments.
Aufbewahrung_Beginn	Date	Der Tag, an dem die Aufbewahrungsfrist begonnen hat: der 31. Dezember des Jahres des Datums, mit dem ihre Regel beginnt, eines Datumsfelds des Typs oder des Eingangs.
Aufbewahrung_Ende	Date	Der letzte Tag der Aufbewahrungsfrist. Leer, solange sie kein Ende hat.
Erfasst_am	Date	Der Tag, an dem das Dokument in Acriva angelegt wurde, in deutscher Zeit.
Datei	AlphaNumeric	Der Pfad des Originals im Paket, zum Beispiel Belege/0199c000000070008000000000000001.pdf.
SHA256	AlphaNumeric	Die SHA-256-Prüfsumme des Originals, hexadezimal in Kleinbuchstaben.
eine je Feld	nach Feld	Die Felder des Dokumenttyps, in der Reihenfolge des Typs.

Die Feldspalten folgen dem Dokumenttyp, wie er beim Download ist:

• Der Name der Spalte ist der Schlüssel des Feldes; jedes Zeichen, das kein ASCII-Buchstabe und keine Ziffer ist, wird zu _. Ein Name, der nicht mit einem Buchstaben beginnt, erhält das Präfix F_: 2nd-party ergibt F_2nd_party. Ein Name, den eine andere Spalte der Tabelle schon hat, ohne Rücksicht auf Groß- und Kleinschreibung, erhält das Präfix Feld_, ebenso einer, dessen Währungsspalte (<Name>_Waehrung) einen solchen Namen trüge: Ein Feld titel ergibt Feld_titel.
• Die Beschreibung der Spalte ist die deutsche Bezeichnung des Feldes.
• Ein Betragsfeld ergibt zwei Spalten: <Name> (Numeric, 2 Nachkommastellen) und <Name>_Waehrung (AlphaNumeric, der Währungscode).
• Ein Zahlenfeld ist Numeric mit 4 Nachkommastellen, ein Datumsfeld ist Date.
• Jedes andere Feld ist AlphaNumeric und wird als Text geschrieben: ein Ja/Nein-Wert als ja oder nein, eine Liste als ihre Einträge, getrennt durch ; (eine Liste in einer Liste wird aufgelöst, leere Einträge bleiben leer), eine Zahl so, wie sie gespeichert ist (1234.5, 1E+3). Die Regel für Texte, die wie eine Formel aussehen, gilt für den geschriebenen Text.
• Ein Feld, das auf eine Akte verweist, und ein Feld, das aus dem Typ entfernt wurde, ergeben keine Spalte.
• Ein Feld ohne Wert ist leer.

rechnungen.csv

Ein Datensatz je Dokument, das in Acriva eine Rechnung hat. Der Schlüssel ist Dokument_ID.

Spalte	Typ	Inhalt
Dokument_ID	AlphaNumeric	Die ID des Dokuments.
Rechnungsnummer	AlphaNumeric	Die Rechnungsnummer.
Rechnungsdatum	Date	Das Rechnungsdatum.
Faelligkeit	Date	Die Fälligkeit.
Lieferant	AlphaNumeric	Der Name des Lieferanten.
Lieferantennummer	AlphaNumeric	Die Nummer des Lieferanten (Kreditorenkonto).
Waehrung	AlphaNumeric	Die Währung.
Netto	Numeric, 2 Nachkommastellen	Der Nettobetrag.
Steuer	Numeric, 2 Nachkommastellen	Der Steuerbetrag.
Brutto	Numeric, 2 Nachkommastellen	Der Bruttobetrag.

kontierung.csv

Ein Datensatz je Kontierungszeile. Der Schlüssel ist Dokument_ID und Position; Dokument_ID verweist auf Rechnungen.

Spalte	Typ	Inhalt
Dokument_ID	AlphaNumeric	Die ID des Dokuments.
Position	Numeric, 0 Nachkommastellen	Die Position der Zeile.
Betrag	Numeric, 2 Nachkommastellen	Der Betrag der Zeile.
Sachkonto	AlphaNumeric	Die Nummer des Sachkontos.
Kostenstelle	AlphaNumeric	Die Nummer der Kostenstelle.
Steuerschluessel	AlphaNumeric	Die Nummer des Steuerschlüssels.

Die beiden Finanztabellen enthalten nur Rechnungen, deren Dokument im Paket ist und die die Person lesen darf.

Wie Werte geschrieben werden

• Zeichensatz: UTF-8 ohne Byte Order Mark, je Tabelle mit UTF8 angegeben. Der Standard erlaubt auch ANSI (Windows-1252). Acriva schreibt UTF-8, weil Titel, Lieferantennamen und Feldwerte Unicode sind und Windows-1252 nicht alle davon darstellen kann.
• Trennzeichen: ; zwischen den Spalten und CR LF nach jedem Datensatz, auch dem letzten.
• Anführungszeichen: Ein Text, der ;, ", einen Wagenrücklauf oder einen Zeilenvorschub enthält, steht in ", und ein " darin wird verdoppelt: "Rechnung 4711; Bürobedarf ""Nord""". Andere Werte stehen ohne Anführungszeichen.
• Zahlen: , als Dezimalzeichen, keine Tausendertrennung, ein führendes - bei einem negativen Betrag, kaufmännisch auf die Nachkommastellen der Spalte gerundet.
• Datumsangaben: DD.MM.YYYY.
• Leer: Ein fehlender Wert ist eine leere Zelle.

Texte, die wie eine Formel aussehen

Eine Tabellenkalkulation liest eine Zelle, die mit bestimmten Zeichen beginnt, als Formel. Damit ein Wert aus einem Dokument nicht als Formel ausgeführt wird, schreibt Acriva einen Apostroph ' vor einen Text, der

• mit =, +, - oder @ beginnt, auch nach führenden Leerzeichen, oder
• mit einem Tabulator, einem Wagenrücklauf oder einem Zeilenvorschub beginnt.

Eine Rechnungsnummer -123 steht als '-123 im Paket, ein Titel =Gutschrift als '=Gutschrift. Der Wert im Paket weicht dann um dieses eine Zeichen vom Wert im Dokument ab. Das gilt für die AlphaNumeric-Spalten Titel, Datei, die Textfelder eines Dokumenttyps und die Texte von rechnungen.csv und kontierung.csv. Numeric- und Date-Spalten werden nie verändert; ein negativer Betrag bleibt also -59,50.

Protokoll

Das Erstellen eines Exports steht im Protokoll. Jeder Download hält dort einen Download je Original fest, bevor das erste Byte gesendet wird.