JSON-Rechnungsfelder zu KSeF FA(3) XML

Verfügbar ab Version 2025-10-13

Diese Anleitung beschreibt die Zuordnung zwischen den B2Brouter Invoice API-Feldern, den entsprechenden Business Terms (BT) gemäß dem europäischen E-Rechnungsstandard (EN 16931) und den XML-Pfaden im KSeF FA(3)-Format (Polnisches nationales E-Rechnungssystem).

Ziel ist es, zu verstehen, wie Rechnungsdaten im JSON-Format über die Invoice API dem KSeF FA(3) XML-Aufbau entsprechen. Es werden nur Felder aufgeführt, die bei der Steuerberichterstellung tatsächlich zugeordnet werden.

Hinweis

KSeF verwendet ein polnisches XML-Schema (FA-Variante 3, Schemaversion 1-0E), das sich erheblich von EN 16931-Formaten wie UBL oder CII unterscheidet. Nicht alle EN 16931 Business Terms haben ein direktes Äquivalent in KSeF, und KSeF führt polnische spezifische Felder ein, die im europäischen Standard nicht vorhanden sind.

Hinweis: Die Verkäufer-/Lieferanteninformationen (Podmiot1) werden automatisch aus Ihren Kontoeinstellungen befüllt. Die Käufer-/Kundeninformationen (Podmiot2) werden aus dem Rechnungskontakt befüllt. Wenn Sie direkten Zugriff auf alle Felder benötigen, verwenden Sie stattdessen die Tax Report API.

Zuordnung auf Header-Ebene

BT-ID	Business Term	API-Feld (B2Brouter)	KSeF FA(3) XPath
BT-1	Rechnungsnummer	invoice.number	Fa/P_2
BT-2	Ausstellungsdatum der Rechnung	invoice.date	Fa/P_1
BT-3	Rechnungstyp-Code	invoice.type_document Abgeleitet: Standard VAT; KOR bei Korrekturrechnung; ZAL bei Anzahlung; UPR bei vereinfachter Rechnung	Fa/RodzajFaktury
BT-5	Rechnungswährung	invoice.currency	Fa/KodWaluty
BT-7	Steuerlicher Leistungszeitpunkt	invoice.tax_point_date	Fa/P_6
BT-9	Zahlungsfälligkeitsdatum	invoice.due_date	Fa/Platnosc/TerminPlatnosci/Termin
BT-25	Nummer der vorherigen Rechnung	invoice.invoice_references[reference_type=amend].number (v2026-04-20+) oder invoice.amended_number (ältere Versionen)	Fa/DaneFaKorygowanej/NrFaKorygowanej
BT-26	Datum der vorherigen Rechnung	invoice.invoice_references[reference_type=amend].date (v2026-04-20+) oder invoice.amended_date (ältere Versionen)	Fa/DaneFaKorygowanej/DataWystFaKorygowanej
—	Wechselkurs	invoice.exchange_rate	Fa/KursWalutyZ
BT-10	Käuferreferenz	invoice.buyer_reference	Podmiot2/NrKlienta
BT-13	Bestellreferenz	invoice.ponumber	Fa/WarunkiTransakcji/Zamowienia/NrZamowienia
BT-92	Bestelldatum	invoice.order_date	Fa/WarunkiTransakcji/Zamowienia/DataZamowienia
BT-14	Auftragsreferenz	invoice.sales_order_reference	Fa/DodatkowyOpis (Schlüssel-Wert-Paar)
BT-16	Lieferscheinreferenz	invoice.delivery_note_number	Fa/WZ
—	Korrekturwirkungscode	invoice.amend_code_tax oder tax_report_setting.credit_note_code	Fa/TypKorekty (nur für KOR-Typen)

Zuordnung auf Zahlungsebene

BT-ID	Business Term	API-Feld (B2Brouter)	KSeF FA(3) XPath
BT-9	Zahlungsfälligkeitsdatum	invoice.due_date	Fa/Platnosc/TerminPlatnosci/Termin
BT-81	Zahlungsmittel-Code	invoice.payment_method (auf KSeF-Codes gemappt)	Fa/Platnosc/FormaPlatnosci
BT-84	IBAN des Zahlungsempfängers	invoice.bank_account.iban	Fa/Platnosc/RachunekBankowy/NrRB
BT-84-0	Kontonummer des Zahlungsempfängers	invoice.bank_account.number (Fallback ohne IBAN)	Fa/Platnosc/RachunekBankowy/NrRB
BT-85	Name der Bank des Zahlungsempfängers	invoice.bank_account.name	Fa/Platnosc/RachunekBankowy/NazwaBanku
BT-86	BIC des Zahlungsempfängers	invoice.bank_account.bic	Fa/Platnosc/RachunekBankowy/SWIFT
—	Bezahlt-Kennzeichen	Abgeleitet: 1 wenn payable_amount = 0 und total > 0	Fa/Platnosc/Zaplacono
—	Zahlungsdatum (bei Bezahlung)	invoice.due_date (wenn Zaplacono=1)	Fa/Platnosc/DataZaplaty

Hinweis: KSeF unterstützt keine Kartenkontodetails (BT-87, BT-88), Lastschriftmandate (BT-89), Gläubigerreferenzen (BT-90), Zahlungsbedingungs-Text (BT-20) oder Verwendungszweck (BT-83).

Zuordnung der Parteien

Diese Zuordnung gilt für eine ausgestellte Rechnung. Bei einer empfangenen Rechnung sind Podmiot1 und Podmiot2 zu vertauschen.

Podmiot1 (Verkäufer/Lieferant)

Podmiot1 wird automatisch aus Ihren Kontoeinstellungen befüllt. Dazu gehören Firmenname, NIP (polnische Steuer-ID) und Adresse.

BT-ID	Business Term	API-Feld (B2Brouter)	KSeF FA(3) XPath
—	Länderkürzel des Verkäufers	account.country (Großbuchstaben)	Podmiot1/PrefiksPodatnika
BT-31	Steuer-ID des Verkäufers (NIP)	account.tin_value (ohne Länderpräfix)	Podmiot1/DaneIdentyfikacyjne/NIP
BT-27	Name des Verkäufers	account.name	Podmiot1/DaneIdentyfikacyjne/Nazwa
BT-40	Land des Verkäufers	account.country (Großbuchstaben)	Podmiot1/Adres/KodKraju
BT-35	Straße des Verkäufers	account.address	Podmiot1/Adres/AdresL1
BT-37,38	PLZ + Stadt des Verkäufers	account.postalcode + account.city	Podmiot1/Adres/AdresL2
BT-29-0	GLN des Verkäufers	account.cin_value (wenn cin_scheme = 88)	Podmiot1/Adres/GLN
BT-42	Telefon des Verkäufers	account.phone	Podmiot1/DaneKontaktowe/Telefon
BT-43	E-Mail des Verkäufers	account.email	Podmiot1/DaneKontaktowe/Email
—	REGON des Verkäufers	account.routing_codes.cinX (Schema 8037)	Stopka/Rejestry/REGON
—	KRS des Verkäufers	account.routing_codes.cinX (Schema 8036)	Stopka/Rejestry/KRS
—	BDO des Verkäufers	account.routing_codes.cinX (Schema 8038)	Stopka/Rejestry/BDO

Podmiot2 (Käufer/Kunde)

BT-ID	Business Term	API-Feld (B2Brouter)	KSeF FA(3) XPath
BT-48	Steuer-ID des Käufers	invoice.contact.tin_value	PL: Podmiot2/DaneIdentyfikacyjne/NIP EU: Podmiot2/DaneIdentyfikacyjne/NrVatUE Nicht-EU: Podmiot2/DaneIdentyfikacyjne/NrID
—	Steuerland Käufer (EU)	invoice.contact.country (Großbuchstaben)	Podmiot2/DaneIdentyfikacyjne/KodUE (nur EU)
—	Steuerland Käufer (Nicht-EU)	invoice.contact.country (Großbuchstaben)	Podmiot2/DaneIdentyfikacyjne/KodKraju (nur Nicht-EU)
—	Kennzeichen “Keine Steuer-ID”	Abgeleitet: 1 wenn contact.tin_value leer ist	Podmiot2/DaneIdentyfikacyjne/BrakID
BT-44	Name des Käufers	invoice.contact.name	Podmiot2/DaneIdentyfikacyjne/Nazwa
BT-55	Land des Käufers	invoice.contact.country (Großbuchstaben)	Podmiot2/Adres/KodKraju
BT-50	Straße des Käufers	invoice.contact.address	Podmiot2/Adres/AdresL1
BT-52,53	PLZ + Stadt des Käufers	invoice.contact.postalcode + invoice.contact.city	Podmiot2/Adres/AdresL2
BT-46-0	GLN des Käufers	invoice.contact.cin_value (wenn cin_scheme = 88)	Podmiot2/Adres/GLN

Zuordnung von Drittparteien (Podmiot3)

KSeF unterstützt mehrere Drittparteirollen über das Element Podmiot3. Ein Podmiot3 wird generiert, wenn Lieferinformationen vorhanden sind oder wenn die Rechnung ein third_party-Objekt enthält (verfügbar ab v2026-04-20).

Rollencodes

Rollencode	B2Brouter third_party.role	Beschreibung
2	delivery_recipient	Lieferempfänger
3	original_supplier	Ursprüngliche Einheit (übernommen/umgewandelt)
4	additional_buyer	Zusätzlicher Käufer
5	invoice_issuer	Rechnungsaussteller im Namen des Steuerpflichtigen
6	payer	Zahler im Namen des Käufers
7	local_government_unit_issuer	Kommunale Körperschaft – Aussteller
8	local_government_unit_recipient	Kommunale Körperschaft – Empfänger (JST)
9	vat_group_member_issuer	MwSt.-Gruppenmitglied – Aussteller
10	vat_group_member_recipient	MwSt.-Gruppenmitglied – Empfänger (GV)
11	employee	Mitarbeiter

Lieferung (Rolle 2)

Lieferinformationen werden Podmiot3 mit Rollencode 2 zugeordnet, wenn invoice.delivery_address vorhanden ist. Die Lieferadresse wird auch unter Fa/WarunkiTransakcji/Transport/WysylkaDo dupliziert.

BT-ID	Business Term	API-Feld (B2Brouter)	KSeF FA(3) XPath
BT-70	Name der Lieferpartei	invoice.delivery_party_name	Podmiot3/DaneIdentyfikacyjne/Nazwa
BT-71	Lieferort-ID (GLN)	invoice.delivery_location_id (wenn Typ GLN/088)	Podmiot3/Adres/GLN
BT-75	Lieferadresse Straße	invoice.delivery_address	Podmiot3/Adres/AdresL1 und Fa/WarunkiTransakcji/Transport/WysylkaDo/AdresL1
BT-77,78	PLZ + Stadt der Lieferadresse	invoice.delivery_postalcode + invoice.delivery_city	Podmiot3/Adres/AdresL2 und Fa/WarunkiTransakcji/Transport/WysylkaDo/AdresL2
BT-80	Land der Lieferadresse	invoice.delivery_country	Podmiot3/Adres/KodKraju und Fa/WarunkiTransakcji/Transport/WysylkaDo/KodKraju
—	Drittpartei-Rolle	Fest: 2 (Empfänger)	Podmiot3/Rola

Hinweis: KSeF unterstützt kein Lieferdatum (BT-72) oder Lieferzeitraumfelder.

JST / GV / Weitere Rollen (Rollen 3–11) — ab v2026-04-20

Geändert in Version 2026-04-20

Drittpartei-Unterstützung über den Lieferempfänger hinaus.

Business Term	API-Feld (B2Brouter)	KSeF FA(3) XPath
Name der Drittpartei	invoice.third_party.name	Podmiot3/DaneIdentyfikacyjne/Nazwa
Steuer-ID der Drittpartei	invoice.third_party.tin_value	Podmiot3/DaneIdentyfikacyjne/NIP (PL), NrVatUE (EU) oder NrID (Nicht-EU)
Adresse der Drittpartei	invoice.third_party.address	Podmiot3/Adres/AdresL1
PLZ + Stadt der Drittpartei	invoice.third_party.postalcode + invoice.third_party.city	Podmiot3/Adres/AdresL2
Land der Drittpartei	invoice.third_party.country	Podmiot3/Adres/KodKraju
Rolle der Drittpartei	invoice.third_party.role → Rollencode	Podmiot3/Rola
JST-Kennzeichen	invoice.apply_to_local_government_unit	Podmiot2/JST (1 wenn true, 2 wenn false)
GV-Kennzeichen	invoice.apply_to_vat_group_member	Podmiot2/GV (1 wenn true, 2 wenn false)

Zuordnung auf Rechnungspositionsebene (FaWiersz)

Alle in der folgenden Tabelle aufgeführten Attribute sind Eigenschaften von Objekten im Array: invoice.invoice_lines_attributes[]. Die Spalte API-Feld bezieht sich auf Schlüssel innerhalb jedes Rechnungspositionsobjekts.

Bei regulären Rechnungen (VAT, KOR, UPR, ROZ) werden Positionen als FaWiersz-Elemente dargestellt. Bei Anzahlungsrechnungen (ZAL, KOR_ZAL) werden Positionen als ZamowienieWiersz-Elemente dargestellt.

BT-ID	Business Term	API-Feld (Rechnungspositionsobjekt)	KSeF FA(3) XPath
BT-126	Rechnungspositions-ID	position	Fa/FaWiersz/NrWierszaFa
BT-153	Artikelname	description	Fa/FaWiersz/P_7
BT-130	Berechnete Menge (Einheitencode)	unit (Codeliste siehe API-Referenz)	Fa/FaWiersz/P_8A
BT-129	Berechnete Menge	quantity	Fa/FaWiersz/P_8B
BT-155	Artikelnummer (Verkäufer)	article_code	Fa/FaWiersz/Indeks
BT-157	Standard-Artikelnummer (GTIN)	article_code2	Fa/FaWiersz/GTIN
BT-146	Einzelpreis	price	Fa/FaWiersz/P_9A
-	Rabattierter Einzelpreis	Abgeleitet aus allowance_charges_attributes[]{allowance_charge_indicator: "allowance"} Betrag / quantity	Fa/FaWiersz/P_10
BT-131	Nettobetrag der Position	extension_amount (wenn nicht angegeben, wird er berechnet)	Fa/FaWiersz/P_11
—	Steuerbetrag der Position	Aus Steuern berechnet	Fa/FaWiersz/P_11Vat
—	Steuercode	Aus Steuereigenschaften abgeleitet	Fa/FaWiersz/P_12

Zuordnung zusätzlicher Artikeleigenschaften (DodatkowyOpis je Position)

Jede Rechnungsposition kann zusätzliche Schlüssel-Wert-Eigenschaften enthalten, die auf DodatkowyOpis-Elemente auf Positionsebene im KSeF XML gemappt werden.

Alle in der folgenden Tabelle aufgeführten Attribute sind Eigenschaften von Objekten im Array: invoice.invoice_lines_attributes[].additional_item_properties_attributes[].

BT-ID	Business Term	API-Feld (zusätzliche Artikeleigenschaft)	KSeF FA(3) XPath
—	Positionsnummernreferenz	position der übergeordneten Position	Fa/DodatkowyOpis/NrWiersza
BT-160	Name der Artikeleigenschaft	name (max. 255 Zeichen)	Fa/DodatkowyOpis/Klucz
BT-161	Wert der Artikeleigenschaft	value (max. 255 Zeichen)	Fa/DodatkowyOpis/Wartosc

Beispiel JSON:

{
  "invoice": {
    "invoice_lines_attributes": [
      {
        "position": 1,
        "description": "Product A",
        "additional_item_properties_attributes": [
          { "name": "Color", "value": "Red" },
          { "name": "Size", "value": "XL" }
        ]
      }
    ]
  }
}

Resultierendes KSeF XML:

<tns:DodatkowyOpis>
  <tns:NrWiersza>1</tns:NrWiersza>
  <tns:Klucz>Color</tns:Klucz>
  <tns:Wartosc>Red</tns:Wartosc>
</tns:DodatkowyOpis>
<tns:DodatkowyOpis>
  <tns:NrWiersza>1</tns:NrWiersza>
  <tns:Klucz>Size</tns:Klucz>
  <tns:Wartosc>XL</tns:Wartosc>
</tns:DodatkowyOpis>

Spezielle Eigenschaft: unit_of_measure

Durch das Setzen einer zusätzlichen Artikeleigenschaft mit dem Namen unit_of_measure können Sie einen Freitext-Einheitencode für das Feld P_8A der Position in KSeF angeben, der die Standard-Einheitencodeliste überschreibt.

{
  "additional_item_properties_attributes": [
    { "name": "unit_of_measure", "value": "szt." }
  ]
}

Diese Eigenschaft wird direkt als Einheitencode der Position (Fa/FaWiersz/P_8A) verwendet und wird nicht als DodatkowyOpis-Element in der XML-Ausgabe ausgegeben.

Steuerzuordnung

Alle in der folgenden Tabelle aufgeführten Attribute sind Eigenschaften von Objekten im Array: invoice.invoice_lines_attributes[].taxes_attributes[].

BT-ID	Business Term	API-Feld (Steuerobjekt)	KSeF FA(3) Zuordnung
BT-118	Steuerkategorie-Code	category (siehe Codeliste)	Wird zur Ableitung des P_12-Steuercodes verwendet
BT-119	Anwendbarer Steuerprozentsatz	percent	Wird zur Ableitung des P_12-Steuercodes und der P_13_x/P_14_x-Aggregierungen verwendet
BT-120	Steuerbefreiungsgrund	comment	Fa/Adnotacje/Zwolnienie/P_19A. Akzeptiert auch einen KSeF P_12-Code (zw, np I, np II, 0 KR, 0 WDT, 0 EX, oo) um den abgeleiteten Wert zu überschreiben.

Steueraggregation (P_13_x / P_14_x)

KSeF erfordert die Aggregierung der Steuerbeträge nach Steuersatz auf Header-Ebene. Diese Felder werden automatisch aus den Steueraufschlüsselungen der Rechnung berechnet:

KSeF-Feld	Beschreibung	Steuersatz / Kategorie
P_13_1	Steuerbasis zum Normalsatz	23 % oder 22 %
P_14_1	Steuerbetrag zum Normalsatz	23 % oder 22 %
P_14_1W	Steuerbetrag zum Normalsatz in PLN umgerechnet	23 % oder 22 % (nur Fremdwährungsrechnungen)
P_13_2	Steuerbasis zum ersten ermäßigten Satz	8 % oder 7 %
P_14_2	Steuerbetrag zum ersten ermäßigten Satz	8 % oder 7 %
P_14_2W	Steuerbetrag zum ersten ermäßigten Satz in PLN	8 % oder 7 % (nur Fremdwährungsrechnungen)
P_13_3	Steuerbasis zum zweiten ermäßigten Satz	5 %
P_14_3	Steuerbetrag zum zweiten ermäßigten Satz	5 %
P_14_3W	Steuerbetrag zum zweiten ermäßigten Satz in PLN	5 % (nur Fremdwährungsrechnungen)
P_13_6_1	Gesamtwert inländischer Umsätze mit 0 %	0 % Inland (ohne innergemeinschaftliche und Exporte)
P_13_6_2	Gesamtwert innergemeinschaftlicher Lieferungen mit 0 %	0 % innergemeinschaftliche Waren
P_13_6_3	Gesamtwert der Exporte mit 0 %	0 % Export
P_13_7	Gesamtwert steuerbefreiter Umsätze	Befreit (Kategorie E, inländischer Geltungsbereich)
P_13_8	Gesamtwert grenzüberschreitender Umkehrbesteuerungen (np I)	Kategorie AE, nicht-inländischer Geltungsbereich
P_13_10	Gesamtwert inländischer Umkehrbesteuerungen	Kategorie AE, inländischer Geltungsbereich
P_15	Gesamtfälliger Betrag (einschließlich aller Steuern)	Summe aller Kategorien

Hinweis: Felder P_14_xW (Steuerbeträge in PLN umgerechnet) werden nur für Rechnungen in Fremdwährungen ausgegeben. Die Umrechnung verwendet den in der Rechnung angegebenen exchange_rate.