SUPERINTELLIGENTHUB DOKUMENTATION

Amtliche FinanzOnline-Dateien und Jahreserklärungen

Prüfstand: 10. Oktober 2026. Die Anwendung erzeugt amtliche XML-Strukturen aus ausdrücklich eingegebenen Formularwerten und validiert diese lokal gegen unveränderte BMF-XSD-Dateien. Sie stellt keine Verbindung zu FinanzOnline her und übermittelt keine Erklärung. Die Kanzlei übernimmt Sachverhaltsprüfung, Vollmacht, Freigabe, Übermittlung und Kontrolle des amtlichen Ergebnisprotokolls.

Veröffentlichte und eingebundene Versionen

Formular	Unterstützte Jahre / Zeiträume	Originalschema
E1 mit den im Schema enthaltenen Beilagen	2025	`annual2025/BMF_XSD_Jahreserklaerungen_2025.xsd`, Stand 21.11.2025
K1 mit den im Schema enthaltenen Beilagen	2025	Dasselbe Jahreserklärungsschema
U30	2025 und Januar–Juni 2026	`uva2022/BMF_ERKLAERUNGS_UEBERMITTLUNG_U30_01_2022.xsd`
U30	Ab Juli bzw. drittem Quartal 2026	`uva2026/BMF_ERKLAERUNGS_UEBERMITTLUNG_U30_07_2026.xsd`, Stand 24.04.2026
ZM / U13	2025 und 2026 mit aktuell publizierter Übermittlungsstruktur	`zm/BMF_XSD_Schema_Zusammenfassende_Meldung.xsd`, Stand 14.01.2025, gültig ab Übermittlungsstichtag 06.03.2025

Die BMF-Seite Jahreserklärungen veröffentlicht derzeit Jahreserklärungen 2025 als neueste Ausgabe. Ein Jahreserklärungs-XSD 2026 für E1/K1 ist dort nicht verfügbar. Diese Kombinationen erscheinen deshalb als nicht verfügbar; das 2025-Schema wird nicht durch Umbenennung oder Änderung der Jahreszahl zu einem 2026-Schema. Die separat veröffentlichte Arbeitnehmerveranlagung L1 2026 ersetzt das E1/K1-Schema nicht.

UVA und ZM stammen von BMF: Sonstige Erklärungen und Anträge. Die U30-Version wird anhand des tatsächlichen Meldezeitraums ausgewählt. Die neuen KZ 124 und 125 gehören zum 4,9%-Satz ab Juli 2026; der Satz betrifft materiell die in Anlage 3 bezeichneten Lieferungen/Einfuhrfälle, keine beliebige Dienstleistung. § 10 Abs. 1a UStG, Fassung ab 01.07.2026.

Alle eingebundenen XSDs, offiziellen XML-Strukturdokumente, Erläuterungs-/Prüfungs-PDFs und Wertelisten liegen in tax_at_schemas/. manifest.json enthält pro unveränderter Originaldatei den genauen BMF-Downloadlink, die Veröffentlichungsseite, Dateigröße, SHA-256 und Abrufdatum. Schemas werden beim Laden gegen den gespeicherten Hash geprüft und ausschließlich lokal kompiliert. Schemaänderungen erfordern erneut geprüfte Originaldateien, einen aktualisierten Nachweis und einen Neustart; alte Berichtssnapshots behalten ihren bisherigen Schemafingerprint.

Die BMF-XML-Dateien sind Strukturbeschreibungen, keine fertigen gültigen Steuererklärungen: Sie enthalten Mustertexte wie JJJJ-MM-TT und mitunter gemeinsam abgebildete alternative Felder. Sie werden als Referenz unverändert aufbewahrt und nicht mit echten Übermittlungsbeispielen verwechselt.

Vollständiger Formularbaum

tax_at_finanzonline.catalog() gibt die amtlichen Feldbäume für E1 und K1 einschließlich verschachtelter und wiederholbarer Beilagen sowie U30/ZM zurück. Das betrifft sämtliche im jeweils eingebundenen XSD verfügbaren Felder, nicht nur eine Gewinnsumme. E1a ist ein eingebetteter Block der E1-Erklärung: beispielsweise

BETRIEBLICHE_EINKUNFTSARTEN
  EINKUENFTE_GEWERBEBETRIEB
    EINZELUNTERNEHMER[]
      ALLGEMEIN
      ERTRAEGE_EINNAHMEN
      AUFWENDUNGEN_AUSGABEN
      GEWINN_VERLUST
      BILANZKENNZAHLEN

Selbständige Arbeit, Land-/Forstwirtschaft, Beteiligungen, Vermietung, Kapitalvermögen, ausländische Einkünfte, Sonderausgaben und weitere E1-Bereiche sind über ihre tatsächlichen amtlichen Blöcke zugänglich. K1 umfasst insbesondere Bilanzposten, Gewinn-/Verlustrechnung, Aufwendungen, steuerliche Bilanzkorrekturen, Beteiligungen, Verlust-/Sonderausgaben, Gruppenbesteuerung und die im XSD vorhandenen Zinschrankenblöcke. Nur die Erklärung selbst besitzt art="E1" bzw. art="K1"; es wird kein erfundenes eigenständiges <E1a>-Einreichungsformat erzeugt.

Jeder Katalogknoten enthält name, label, path, kind, type, minOccurs, maxOccurs, gegebenenfalls children, enum, Grenzen, Muster und attributes. sequence und choice sind Schemamodelle für Reihenfolge/Auswahl, keine XML-Felder und keine Schlüssel im Werteobjekt. path bezieht sich auf den Inhalt einer einzelnen ERKLAERUNG. Auswahlregeln und Wiederholungen bleiben erhalten. Manche gemeinsame XSD-Blöcke enthalten ein formularübergreifendes Feldangebot; die fachliche Zulässigkeit einzelner Angaben richtet sich zusätzlich nach BMF-Erläuterungen und Prüfungen.

Eingabe- und Funktionsvertrag

catalog() -> dict
validate_declaration(form, year, values, header) -> dict
render_xml(form, year, values, header, production=False) -> bytes

form ist E1, K1, U30 oder ZM, year eine unterstützte Ganzzahl. values enthält die tatsächlichen XML-Feldnamen innerhalb einer ERKLAERUNG, ohne äußeren Übermittlungsumschlag und ohne SATZNR. Komplexe Blöcke sind Objekte; wiederholbare Blöcke Listen. Skalare sind Zeichenfolgen bzw. verlustfreie Ganz-/Dezimalwerte. Floats werden abgelehnt. Geldwerte verwenden Dezimalpunkt ohne Tausendertrennzeichen/Exponenten. Der jeweilige XSD-Feldtyp bestimmt, ob null, negative Werte oder Nachkommastellen zulässig sind; leere optionale Felder werden weggelassen, nicht pauschal mit null gefüllt.

Im amtlichen ZM-Schema ist SUM_BGL ganzzahlig. Gemäß BMF-Fachinformation zur ZM wird der Eurobetrag ohne Centbetrag gemeldet, ohne kaufmännisches Aufrunden. Die Dateierzeugung ändert Centwerte nicht stillschweigend. Eine Vorbelegung dokumentiert die weggelassenen Centbeträge gegenüber der vollständigen Belegsumme.

XML-Attribute mit einem im XSD eindeutig festgelegten Wert, insbesondere type="kz", type="datum" und type="jahrmonat", erzeugt die Anwendung aus dem Schema. Variable Attribute können über $attributes angegeben werden; ein Skalar mit eigenen Attributen verwendet {"$value":"...","$attributes":{...}}. Nicht amtliche Felder, falsche Attribute und Änderungen fester Attribute führen zu Fehlern.

Der Kopf header verwendet native amtliche Bezeichnungen:

Feld	Bedeutung
`IDENTIFIKATIONSBEGRIFF`	Neunstellige Steuernummer des Übermittlers / FinanzOnline-Teilnehmers
`FASTNR`	Neunstellige Steuernummer des Pflichtigen / Mandanten
`PAKET_NR`	Positive Paketkennung bis neun Stellen
`SATZNR`	Positive Kennung der einzelnen Erklärung
`DATUM_ERSTELLUNG`	Erstellungsdatum `YYYY-MM-DD`
`UHRZEIT_ERSTELLUNG`	Erstellungszeit `HH:MM:SS`

ART_IDENTIFIKATIONSBEGRIFF=FASTNR und ANZAHL_ERKLAERUNGEN=1 werden automatisch erzeugt. Pflichtigen-Steuernummer, Formularart und jährlicher Zeitraum werden in ALLGEMEINE_DATEN übertragen; widersprüchliche Angaben sind Fehler. Bei U30/ZM sind ZRVON und ZRBIS echte Meldezeiträume im Format YYYY-MM. Es werden weder ein TID-Tag noch Login-/Passwortfelder erfunden. Eine Steuernummer ist kein FinanzOnline-Loginsecret. Unterschiedliche Übermittler-/Mandanten-Steuernummern sind für Vertretung möglich; eine tatsächliche Vollmacht ist außerhalb des XSD zu prüfen.

Die XML-Datei beginnt mit ERKLAERUNGS_UEBERMITTLUNG/INFO_DATEN. E1/K1 nutzen JAHRESERKLAERUNG art="JAHR_ERKL"/ERKLAERUNG art="E1|K1"; U30/ZM verwenden unmittelbar ERKLAERUNG art="U30|U13". Reihenfolge, Feldnamen, Datentypen und Attribute stammen aus dem veröffentlichten Schema.

Prüfung und Freigabe

Nachvollziehbare Vorbelegung

POST /api/tax-at/clients/{identifier}/declarations/prepare erhält form, year, optional report_id und inputs. Ein Bericht muss zum Mandanten gehören, unveraltet sein und den gewählten Jahres-/Meldezeitraum enthalten. Die Antwort trennt unveränderte values, suggestions mit nativem Feldpfad und Herkunft, issues, steuerliche adjustments und tax_estimate. Vorschläge benötigen ausdrückliche Übernahme; sie sind kein bestätigter Formularinhalt. Der gespeicherte Snapshot kann an report_id gebunden werden und verlangt dessen Fachfreigabe vor dem aktuellen XML-Export.

Im Portal nimmt „Ergänzende Angaben“ folgende Vorbereitungsfelder entgegen:

Eingabe unter `inputs`	Zweck
`values`	Bereits erfasste native Formularwerte; im Portal werden die aktuellen Feldeditorwerte mitgegeben
`business_income_kind`	E1-Betrieb ausdrücklich als `trade`, `self_employment` oder `agriculture` einordnen
`bookkeeping_mapping.default_income_kz`	Gesamte belegte Einnahmen einer fachlich passenden KZ zuordnen; keine automatische Zuordnung aller Einnahmen zu KZ9040
`bookkeeping_mapping.income_split`	Einnahmen in amtliche Kennzahlen aufteilen; Summe muss dem Bericht entsprechen
`bookkeeping_mapping.expense_categories`	Ausgabenkategorie auf eine veröffentlichte KZ abbilden; unbekannte Kategorien werden nicht automatisch in KZ9230 gesammelt
`bookkeeping_mapping.accounts`	Kontonummer auf amtliche KZ abbilden; `omit` ist eine ausdrückliche Entscheidung für ein nicht in diesen Formularpositionen auszuweisendes Konto
`adjustments`	Liste mit `label`, `reason`, signierter Gewinnwirkung `amount` und bestätigter `official_kz`
`adjustments_reviewed`	Tatsächliche Prüfung der steuerlichen Mehr-/Wenigerrechnung bestätigen, keine automatische Bestätigung
`tax_basis`	Gesondert festgestelltes steuerpflichtiges Jahreseinkommen; Buchgewinn wird nicht ungeprüft eingesetzt
`gfb`	E1-GFB mit `eligible_profit`, ausdrücklich `single_business=true`; gegebenenfalls `tax_method` (`full_ea`, `balance`, `pauschal`), `asset_claim`, `eligible_assets`, `securities_claim`, `eligible_securities`
`corporation`	K1: bestätigte `legal_form` (`gmbh`, `flexco`, `ag`), `full_quarters` von 0 bis 4, `prepayments` und `minimum_tax_credit`

Kennzahlen werden mit oder ohne Präfix KZ akzeptiert, Beträge als Dezimalstrings. adjustments.amount ist die signierte Gewinnwirkung; amtliche GFB-Abzugsfelder enthalten dagegen den positiven Abzug. Mehrbetriebsfälle benötigen Gesamtbemessung, Durchschnittssatz und Verteilung nach § 10 EStG und bleiben ohne automatische GFB-Vorbelegung. Eine bestätigte Einzelbetriebsbasis ersetzt keine Investitions-/Behaltefristnachweise. Bei Gewinnermittlung nach § 17 EStG ist der investitionsbedingte GFB ausgeschlossen. Ungeklärte Gewinnermittlung verhindert entsprechende Vorschläge; positive Investitions-GFB-Werte bei bekannter Pauschalierung werden auch im XML-Prüfpfad gesperrt. Maßgeblich sind die tatsächlichen Pauschalierungsmerkmale, nicht eine einzelne Angabe zur Nichtnutzung bei einer anderen Mitunternehmerschaft. Die Körperschaftsteuerrechnung verwendet den Tarifsatz und eine gesondert bestätigte Mindeststeuerbasis; Gruppen- und Sonderfälle bleiben fachlich zu prüfen.

Beispiel einer fachlich zu prüfenden Eingabestruktur, ohne Betrags- oder Kontenvorschlag:

{
  "business_income_kind": "trade",
  "bookkeeping_mapping": {
    "default_income_kz": "9040",
    "expense_categories": {}
  },
  "adjustments": [],
  "adjustments_reviewed": false
}

Die KZ9040 ist hier nur ein Strukturbeispiel; §-109a-Einnahmen benötigen ihre eigene Zuordnung. Bei U30/ZM wird der vollständige Monats-/Quartalszeitraum aus dem Bericht vorgeschlagen. ZM aggregiert belegte Umsätze pro Empfänger und Umsatzart, bevor Centbeträge entfernt werden. Fehlende UID-/Leistungs-/Korrekturgrundlagen bleiben sichtbar.

Die Validierung liefert valid, schema_valid, issues, normalized: {values, header}, schema_id, schema_sha256, manifest_hash, source_info und business_checks. Ein Fehler besitzt code, path, message, severity="blocker". XML-Ausgabe ist bei lokalen Fehlern gesperrt. valid beschreibt die lokale Struktur-/Prüfvalidität, keine behördliche Annahme.

Zusätzlich zur vollständigen XSD-Prüfung sind folgende veröffentlichte Regeln lokal umgesetzt:

Formular-/Kopf-/Jahres-/Steuernummer-Konsistenz; monatlicher oder vollständiger Quartalszeitraum; UVA vergangener Zeitraum; Auswahl des zeitlich passenden Schemas.
U30: KZ 000 erforderlich, Summe steuerfreier/steuerpflichtiger Bemessungsgrundlagen, Erwerbsteuer-Summen, passende Reverse-Charge-Vorsteuergrenzen und Zusammenhang KZ 020/VST.
ZM: Meldezeilen oder Gesamtrückziehung, keine österreichische UID, alternative Umsatzarten, Konsignationslager-/Erwerberwechselregeln und doppelte Meldezeilen.
E1: sich ausschließende AVAB/AEAB-Angaben, zugehörige Kinderzahl-/Pensionistenregeln, Beilagenanzahlen, Berufsgruppenpauschalen-Grundangaben, Freibetragsbescheid-Auswahl und positive Abzugsbeträge der Gewinnfreibeträge.
E1a: notwendige Betriebsadresse, amtliche Länder-/Branchenangabe, Gewinnermittlungs- und USt-Methodenauswahl; vollständige veröffentlichte E1a/E11-/Verteilungsformeln für die Einkünfte aus selbständiger Arbeit (KZ320) und Gewerbebetrieb (KZ330).
K1: Pflicht-Grundfelder, Bilanz-/Liquidationszeitraum, Gruppenmerkmale und K1g-Grundfelder; vollständige veröffentlichte Ertrags-/Aufwands-/Korrektursumme KZ704 sowie Abstimmung KZ777. Insbesondere wird die signierte KZ9306 in dieser amtlichen Formel addiert, nicht nochmals mit umgekehrtem Vorzeichen verrechnet.

Die vollständigen amtlichen fachlichen Prüfdokumente sind zusätzlich eingebunden und im Validierungsnachweis aufgeführt. Weitere sachverhaltsabhängige Kennzahlverknüpfungen, Einkünfte-/Gewinnfreibetragsberechnungen, Rechtsform-/Abzugsvoraussetzungen, Vollmacht, Steuersignal, bestehende Erklärungen/Bescheide und UID-Gültigkeit sind keine allgemeine Offline-XSD-Prüfung. Sie müssen anhand dieser Unterlagen durch die Kanzlei und teilweise durch FinanzOnline geprüft werden. Der Prüfumfang und die nicht ausgeführten Behördenprüfungen stehen in business_checks; fachliche Gesamtabdeckung wird nicht aus einem erfolgreichen XML-Schematest abgeleitet.

In diesen BMF-Schemas gibt es kein Test-/Produktionsflag innerhalb der XML-Datei. production=True ist ausschließlich ein interner Downloadmodus nach menschlicher Freigabe und erzeugt dieselben amtlichen XML-Daten. Der spätere Uploadkanal in FinanzOnline bestimmt Test- bzw. Produktionsübermittlung. Die Anwendung fügt kein eigenes Mode-Tag hinzu. Gemäß BMF: Informationen für die Datenstromübermittlung bestätigt eine formale Übermittlung allein keine wirksame Einbringung: Dafür ist ein positives inhaltliches Übermittlungsprotokoll maßgeblich.

Technische Absicherung und Tests

lxml.XMLSchema kompiliert unveränderte Original-XSDs offline; DTDs, externe Entitäten, Schemaimporte und Netzwerkauflösung sind gesperrt. Werte werden ausschließlich als XML-Text/Attribute serialisiert, nicht als frei injizierbare XML-Struktur interpretiert. Mutable Schema-Fehlerprotokolle werden pro Validierung gesperrt, damit parallele Mandantenprüfungen keine Fehlerdetails vermischen. Die Ausgabe bleibt innerhalb der BMF-Paketgrenze von 5 MiB.

tests/test_tax_at_finanzonline.py prüft Originalhashes, alle angebotenen Feldfamilien, wiederholbare E1-Beilagen, tatsächliche Umschläge, unabhängige Validierung erzeugter Dateien gegen Original-XSDs, Jahres-/Steuernummer-Widersprüche, U30-Versionen/Summen, ZM-Regeln, unzulässige Felder/Floats/Präzision, XML-Escaping und parallele Validierungen. Alle Kennungen sind isolierte Testwerte; die Tests senden keine FinanzOnline-Anfrage.

← Alle Artikel OpenAPI-Spezifikation ↗