FA(3)-XML-Struktur: Der KSeF-Leitfaden für Entwickler

Die FA(3)-XML-Struktur ist das Schema, das KSeF für strukturierte Rechnungen verwendet, die seit dem 1. Februar 2026 ausgestellt werden. Behandeln Sie sie als drei getrennte Verträge: Das XSD legt die XML-Form fest, die polnischen Umsatzsteuerregeln bestimmen die erforderlichen Rechnungsangaben und die jeweilige Transaktion entscheidet über bedingte Zweige. Validieren Sie alle drei Ebenen vor dem Versand. Als Annahme gilt erst der endgültige KSeF-Status – nicht die Antwort auf den Upload.

Dieser Beitrag ist ein technischer Implementierungsleitfaden und keine Steuerberatung. Lassen Sie die umsatzsteuerliche Behandlung und die gesetzlich erforderlichen Angaben jedes Rechnungstyps qualifiziert prüfen.

Was ist die FA(3)-XML-Struktur?

FA(3) ist die logische Struktur des polnischen Finanzministeriums für strukturierte Rechnungen. Sie ist weder PDF-Layout noch visuelle Vorlage. Der XML-Vertrag legt fest, welche Elemente wo und wie oft vorkommen dürfen und welche Datentypen und Formate sie annehmen.

Das KSeF-2.0-Handbuch zieht eine wichtige Grenze: Die Struktur bestimmt, was die XML-Datei enthalten muss oder darf. Welche Angaben eine bestimmte Rechnung enthalten muss, richtet sich weiterhin nach Artikel 106e des Umsatzsteuergesetzes. FA(3) bietet zudem optionale Felder wie Kontaktdaten, die steuerrechtlich in der Regel nicht vorgeschrieben sind.

Daraus ergeben sich drei Validierungsebenen:

Fassen Sie diese Ebenen nicht zu einem einzigen Wahrheitswert „valide XML“ zusammen. minOccurs="0" bedeutet lediglich, dass das XSD ein Weglassen zulässt. Es bedeutet nicht, dass das Feld auf jeder rechtlich korrekten Rechnung fehlen darf. Umgekehrt wird ein Feld nicht dadurch allgemein verpflichtend, dass es in einem Beispiel des Ministeriums ausgefüllt ist.

Welchen FA(3)-Namensraum und Header sollten Sie verwenden?

Verwenden Sie den Zielnamensraum aus dem aktuellen offiziellen FA(3)-XSD:

http://crd.gov.pl/wzor/2025/06/25/13775/

Der abschließende Schrägstrich gehört dazu. Das Schema verlangt qualifizierte Elemente. Ein <Faktura> ohne Namensraum wird nicht zum gleichen Dokument, nur weil Sie später einen Schemapfad hinzufügen.

Das offizielle Beispiel des Java-Clients zeigt den zugehörigen Header:

<Faktura xmlns="http://crd.gov.pl/wzor/2025/06/25/13775/">
  <Naglowek>
    <KodFormularza kodSystemowy="FA (3)" wersjaSchemy="1-0E">FA</KodFormularza>
    <WariantFormularza>3</WariantFormularza>
    <DataWytworzeniaFa>2026-08-28T09:30:00Z</DataWytworzeniaFa>
    <SystemInfo>YourApp 4.2</SystemInfo>
  </Naglowek>
  <!-- Remaining sections in XSD order -->
</Faktura>

Halten Sie Namensraum, kodSystemowy, wersjaSchemy und Variante in einem versionierten Serialisierungsmodul. Verteilen Sie diese Zeichenketten nicht über mehrere Templates. Veröffentlicht das Ministerium ein Nachfolgeschema, brauchen Sie eine bewusste Auswahl der Version und passende Fixtures – keine Such-und-Ersetz-Migration.

Erzeugen Sie XML 1.0 als UTF-8 ohne Byte Order Mark. Die Prüfregeln für Rechnungen erlauben es, die XML-Deklaration wegzulassen. Ist sie vorhanden, darf sie keine andere Kodierung angeben. KSeF weist außerdem Processing Instructions und bestimmte unerwünschte Unicode-Bereiche zurück. Normalisieren und prüfen Sie Text vor der Serialisierung.

Aus welchen acht Hauptabschnitten besteht FA(3)?

Das Handbuch des Ministeriums gliedert FA(3) in acht Hauptelemente. Einige bilden den Kern einer gewöhnlichen Rechnung, andere gelten nur für bestimmte Rollen oder Funktionen.

Die Reihenfolge gehört zum Vertrag. XML-Elemente wirken zwar wie unabhängige Felder, sind im XSD aber häufig in sequence und choice eingebettet. Ein allgemeiner Objekt-zu-XML-Mapper kann alle richtigen Werte in falscher Reihenfolge ausgeben. Legen Sie die Serialisierungsreihenfolge ausdrücklich fest und sichern Sie sie mit einem Schematest ab.

Podmiot3, PodmiotUpowazniony, Stopka und Zalacznik sind kein Standardballast. Fügen Sie sie nur hinzu, wenn Ihr Domänenmodell die entsprechende Rolle oder Funktion enthält. Strukturierte Anhänge folgen außerdem einem freizuschaltenden Ablauf mit anderen Größen- und Versandgrenzen. Behandeln Sie sie getrennt vom Serializer für gewöhnliche Rechnungen.

Wie sieht das Gerüst einer FA(3)-Rechnung aus?

Das folgende Gerüst zeigt die Beziehung der wichtigsten Elemente einer gewöhnlichen Rechnung. Es ist absichtlich unvollständig und weder direkt verwendbar noch schema-minimal oder rechtlich hinreichend.

<Faktura xmlns="http://crd.gov.pl/wzor/2025/06/25/13775/">
  <Naglowek>
    <KodFormularza kodSystemowy="FA (3)" wersjaSchemy="1-0E">FA</KodFormularza>
    <WariantFormularza>3</WariantFormularza>
    <DataWytworzeniaFa>2026-08-28T09:30:00Z</DataWytworzeniaFa>
    <SystemInfo>YourApp 4.2</SystemInfo>
  </Naglowek>

  <Podmiot1>
    <DaneIdentyfikacyjne>
      <NIP>1234567890</NIP>
      <Nazwa>Example Seller sp. z o.o.</Nazwa>
    </DaneIdentyfikacyjne>
    <!-- Seller address as required for this invoice -->
  </Podmiot1>

  <Podmiot2>
    <DaneIdentyfikacyjne>
      <NIP>9876543210</NIP>
      <Nazwa>Example Buyer sp. z o.o.</Nazwa>
    </DaneIdentyfikacyjne>
    <!-- Buyer address as required for this invoice -->
  </Podmiot2>

  <Fa>
    <KodWaluty>PLN</KodWaluty>
    <P_1>2026-08-28</P_1>
    <P_2>FV/2026/08/1042</P_2>
    <!-- Totals in the exact schema order -->
    <P_15>123.00</P_15>
    <Adnotacje><!-- Applicable markers and branches --></Adnotacje>
    <RodzajFaktury>VAT</RodzajFaktury>
    <FaWiersz>
      <NrWierszaFa>1</NrWierszaFa>
      <P_7>Software subscription</P_7>
      <P_8A>szt.</P_8A>
      <P_8B>1</P_8B>
      <P_9A>100.00</P_9A>
      <P_11>100.00</P_11>
      <P_12>23</P_12>
    </FaWiersz>
    <!-- Payment data, when applicable -->
  </Fa>
</Faktura>

Warum veröffentlichen wir keine „minimale valide Rechnung“? Weil das Minimum von Rechnungsart, Identität der Parteien, Umsatzsteuerbehandlung, Zahlungsstatus, Korrekturen, Anzahlungen und weiteren Umständen abhängt. Ein Dokument, das nur XSD-Kardinalitäten erfüllt, kann gesetzlich vorgeschriebene Angaben auslassen. Beginnen Sie mit einem typisierten Rechnungsmodell und eindeutigen Szenario-Fixtures.

Wie werden Verkäufer- und Käuferkennungen in FA(3) abgebildet?

Die Zuordnung der Identitäten ist entscheidend, denn sie beeinflusst sowohl die Validierung als auch die Bereitstellung in KSeF. Speichern Sie Steuerkennungen strukturiert statt in einer einzigen Anzeigezeichenkette.

Die Regel für polnische Käufer hat praktische Folgen: Laut Handbuch verwendet KSeF Podmiot2/DaneIdentyfikacyjne/NIP, um die Rechnung dem Käufer bereitzustellen. Ein in NrID versteckter polnischer NIP kann intern plausibel wirken und dennoch die erwartete Bereitstellung in KSeF verhindern.

Speichern Sie tax_identifier_kind, country_code, identifier und has_no_identifier getrennt. Prüfen Sie sich ausschließende Zweige vor der Serialisierung. Entfernen Sie Anzeige-Trennzeichen aus einem NIP, „reparieren“ Sie aber keine zweideutige Kennung stillschweigend. KSeF prüft in der Produktion zudem NIP-Prüfziffern, während TEST diese Prüfung nicht gleich durchsetzt. Prüfen Sie selbst, damit die Umstellung auf Produktion keinen Datenfehler aufdeckt.

Wie sollten Sie Fa, Summen und Positionen modellieren?

Fa ist der Transaktionskörper. Bei einer gewöhnlichen Umsatzsteuerrechnung enthält er meist Währung (KodWaluty), Ausstellungsdatum (P_1), die vom Verkäufer vergebene Rechnungsnummer (P_2), relevante Summen, gesetzliche Vermerkzweige, Rechnungsart (RodzajFaktury), wiederholte FaWiersz-Elemente und gegebenenfalls Zahlungsdaten.

Verwenden Sie XML-Feldnamen nicht als primäres Geschäftsmodell. Modellieren Sie Geld, Steuerkategorien, Mengen, Daten, Parteien und Rechnungsart mit Domänentypen und ordnen Sie diese anschließend FA(3) zu. So lassen sich Steuerberechnung und Rundung testen, ohne die eigene Ausgabe wieder einzulesen.

Prüfen Sie pro unterstütztem Szenario mindestens:

• Nettowerte der Positionen stimmen mit den jeweiligen Summen überein;
• Umsatzsteuerbeträge folgen einer dokumentierten Rundungsregel;
• P_15 stimmt mit dem fälligen Betrag des Szenarios überein;
• Währungs- und Zahlenwerte verwenden Punkte und keine lokalen Tausendertrennzeichen;
• P_1 liegt nicht nach dem Annahmezeitpunkt in KSeF;
• P_2 ist stabil und innerhalb des Dublettenschlüssels eindeutig.

KSeF kombiniert für die Dublettenprüfung Verkäufer-NIP, RodzajFaktury und P_2. Ein erneuter Versuch muss daher dieselbe logische Rechnung erneut senden und abgleichen, statt blind eine neue Verkäufernummer zu vergeben. Speichern Sie einen Idempotenzdatensatz rund um Rechnung und KSeF-Referenz.

Vermerke brauchen Szenariotests statt pauschaler Standardwerte. Das offizielle Beispiel enthält für mehrere Zweige ausdrückliche Negativ- oder Nicht-anwendbar-Markierungen. Mechanisches Kopieren kann ein strukturell sauberes, aber inhaltlich falsches Dokument erzeugen. Leiten Sie den Zweig aus den Rechnungsfakten ab und testen Sie Befreiung, Reverse Charge, Split Payment, Margenbesteuerung und andere unterstützte Fälle getrennt.

Wie validieren Sie FA(3) lokal vor dem Versand?

Validieren Sie vor Verschlüsselung und Upload genau die Bytes, die Sie übermitteln wollen.

1. Erstellen Sie einen typisierten Rechnungsschnappschuss. Fixieren Sie Verkäufer, Käufer, Positionen, Steuerbehandlung, Summen, Daten und Rechnungsart für diesen Ausstellungsversuch.
2. Wenden Sie Geschäftsregeln an. Weisen Sie fehlende Pflichtangaben und unmögliche Zweigkombinationen mit verständlichen Feldfehlern zurück.
3. Serialisieren Sie deterministisch. Erzeugen Sie XML 1.0 als UTF-8 ohne BOM, mit genauem FA(3)-Namensraum, Schemareihenfolge und invarianten Zahlen- und Datumsformaten.
4. Validieren Sie gegen das festgelegte XSD. Speichern Sie offizielles Schema und importierte Ministeriumsdefinitionen als kontrollierte Build-Abhängigkeit; dokumentieren Sie Prüfsumme und Quell-URL.
5. Fixieren Sie die Bytes. Berechnen Sie Größe und Hash aus derselben Bytefolge, die Sie verschlüsseln und hochladen. Erneutes Rendern kann Leerraum, Kodierung, Hash oder Größe ändern.
6. Speichern Sie Diagnosedaten. Halten Sie Serializer-Version, Referenz auf den Domänenschnappschuss, XML-Hash, Bytegröße und Prüfergebnis fest. Schützen Sie Rechnungs-XML als sensible Finanzdaten.

Die offiziellen Regeln begrenzen eine Rechnung ohne Anhang auf 1 MB und mit Anhang auf 3 MB. Prüfen Sie den aktuellen Vertrag, statt anzunehmen, dass eine lokale XSD-Prüfung Dienstgrenzen abdeckt.

Ihre Fixtures sollten Szenarien abbilden: gewöhnliche inländische Umsatzsteuer, EU-Käufer, Drittstaat, Verbraucher, Korrektur, Anzahlung und Abrechnung, Befreiung sowie jedes tatsächlich unterstützte Sonderverfahren. Eine einzige riesige „alle Felder“-Fixture liefert Abdeckung, beweist aber bedingte Zweige schlecht.

Wie testen Sie FA(3) in TEST, DEMO und Produktion?

Führen Sie denselben Serializer durch drei Umgebungen, halten Sie aber Zugangsdaten, Endpunkte, Berechtigungen und Daten getrennt.

Die offizielle Umgebungsmatrix beschreibt TEST für Integrationen, DEMO als produktionsnah und PRD als Umgebung mit rechtlich wirksamen Rechnungen. TEST und DEMO dürfen keine echten Produktionsdaten enthalten. TEST akzeptiert selbst signierte Zertifikate, und seine Daten sind nicht als vertraulich zu behandeln. Verwenden Sie daher synthetische Namen, Adressen, Rechnungsnummern und zufällig erzeugte Test-NIPs.

Ein sicherer Weg in die Produktion:

1. Testen Sie Zuordnung, Summen, Zweigauswahl und deterministische Serialisierung in Unit-Tests.
2. Validieren Sie alle Szenario-Fixtures lokal gegen das festgelegte XSD.
3. Senden Sie synthetische Fixtures an TEST und prüfen Sie abgelehnte wie angenommene Pfade.
4. Prüfen Sie Zugangsdaten, Berechtigungen, Statusabfrage und UPO-Abruf in DEMO mit Nicht-Produktionsdaten.
5. Bringen Sie denselben Serializer-Build überwacht und kontrolliert nach PRD.

Die Annahme in TEST beweist keine korrekten Produktionskennungen. Prüfen Sie NIP-Prüfziffern und andere Produktionsregeln vorab. Versionieren Sie auch die Fähigkeiten je Umgebung getrennt, da offizielle API-Versionen TEST früher als DEMO und PRD erreichen können.

Wann ist eine gesendete Rechnung wirklich angenommen?

Der Versand innerhalb einer Online-Sitzung ist asynchron. Die API kann Ihren Verarbeitungsauftrag annehmen und eine Rechnungsreferenz liefern, bevor sie die Rechnung selbst angenommen hat. Speichern Sie die Referenz sofort und setzen Sie die Rechnung sichtbar auf processing.

Der offizielle Leitfaden zu Status und UPO beschreibt Sitzungsstatus, Rechnungslisten, Einzelstatus, fehlgeschlagene Rechnungen und UPO-Abruf. Fragen Sie mit Backoff ab, bewahren Sie strukturierte KSeF-Details auf und machen Sie endgültige Fehler handlungsfähig, ohne die ursprünglichen Belege zu überschreiben.

Ihr dauerhaftes Zustandsmodell sollte mindestens unterscheiden:

• erzeugt und lokal validiert;
• mit KSeF-Rechnungsreferenz übermittelt;
• in Verarbeitung;
• mit strukturierten Details abgelehnt;
• mit KSeF-Nummer angenommen;
• UPO abgerufen und gespeichert.

Nur im angenommenen Pfad darf die KSeF-Nummer als endgültiger Beleg erscheinen. Speichern Sie das UPO mit manipulationssicheren Metadaten und gleichen Sie lang laufende Sitzungen ab. Eine HTTP-202-Antwort bedeutet Warteschlange, nicht Rechnungserfolg.

FA(3) selbst entwickeln oder KSeF Kit verwenden?

Entwickeln Sie direkt, wenn FA(3) eine Kernfunktion Ihres Produkts ist, Sie Rechnungsquellen jenseits von Stripe unterstützen oder besondere Steuerszenarien und vollständige Kontrolle benötigen. Planen Sie Schemaüberwachung, Szenario-Fixtures, Zugangsdaten, Umgebungswechsel, Statusüberwachung und Betrieb ein – nicht nur XML-Erzeugung.

Ist Stripe Ihre Datenquelle, wählt KSeF Kit einen engeren Weg: Es wandelt finalisierte Stripe-Rechnungen in FA(3) um, sendet sie an KSeF und speichert KSeF-Nummer und UPO. Die Einrichtungsdokumentation beschreibt die Verbindung von Stripe und KSeF; das Produkt unterstützt Test- und Produktionsabläufe.

Das ersetzt weder korrekte Steuer- und Kundendaten noch garantiert es pauschal Steuerkonformität. Es nimmt Ihnen jedoch eine beträchtliche Integrationsfläche ab: Pflege des Serializers, Verschlüsselung und Upload, asynchrones Zustandsmodell und Nachweisübergabe für gewöhnliche Stripe-Rechnungen.

Für beide Wege gilt derselbe Maßstab: korrekte Domänenfakten, valides FA(3)-XML, erfolgreiche KSeF-Verarbeitung und gespeicherte Nachweise. Weitere technisch ausgerichtete Beiträge finden Sie im Archiv zur Compliance-Entwicklung.