Mapping JSON Invoice Fields to KSeF FA(3) XML

Available from version 2025-10-13

Invoice Field Mapping Guide (B2Brouter API ↔ Business Terms ↔ KSeF FA(3) XPath)

This guide details the mapping between the B2Brouter Invoice API fields, the corresponding Business Terms (BT) as defined by the European e-Invoicing standard (EN 16931), and the XML paths in the KSeF FA(3) format (Polish National e-Invoice System).

Its purpose is to help understand how invoice data submitted in JSON format via the Invoice API corresponds to the KSeF FA(3) XML structure. Only fields that are actually mapped during tax report generation are included.

Note: KSeF uses a Poland-specific XML schema (FA variant 3, schema version 1-0E) which differs significantly from EN 16931 formats like UBL or CII. Not all EN 16931 Business Terms have a direct equivalent in KSeF, and KSeF introduces Poland-specific fields not present in the European standard.

Note: The seller/supplier information (Podmiot1) is automatically populated from your account settings. The buyer/customer information (Podmiot2) is populated from the invoice contact. If you need direct control over all fields, consider using the Tax Report API instead.

Header-Level Mapping

Payment-Level Mapping

Note: KSeF does not support card account details (BT-87, BT-88), direct debit mandates (BT-89), creditor references (BT-90), payment terms text (BT-20), or remittance information (BT-83).

Parties Mapping

This mapping is described for an issued invoice. If you want to map a received invoice, swap Podmiot1 and Podmiot2.

Podmiot1 (Seller/Supplier)

The Podmiot1 is automatically populated based on your account settings. This includes company name, NIP (Polish tax ID), and address.

Podmiot2 (Buyer/Customer)

Third Party Mapping (Podmiot3)

KSeF supports multiple third-party roles via the Podmiot3 element. A Podmiot3 is generated when delivery information is present or when the invoice has a third_party object (available from v2026-04-20).

Role Codes

Delivery (Role 2)

Delivery information is mapped to Podmiot3 with role code 2 when invoice.delivery_address is present. The delivery address is also duplicated under Fa/WarunkiTransakcji/Transport/WysylkaDo.

Note: KSeF does not support delivery date (BT-72) or delivery period fields.

JST / GV / Other Roles (Roles 3–11) — v2026-04-20+

Changed in version 2026-04-20: third-party support beyond delivery recipient.

When the invoice has a third_party object, a Podmiot3 is generated with the party's identification, address, and the corresponding role code. See the changelog for details on creating invoices with third parties.

When apply_to_local_government_unit is true, the role must be 8 (JST) and third_party.tin_value is required. When apply_to_vat_group_member is true, the role must be 10 (GV) and third_party.tin_value is required. For role 11 (employee), tin_value is not required.

Order & Transaction References (WarunkiTransakcji / DodatkowyOpis)

The WarunkiTransakcji section is rendered when a delivery address is present (third party role = 2) or when a purchase order reference is provided. The sales order reference is rendered as a DodatkowyOpis key-value pair.

Note: When a delivery address is present, KSeF also includes transport details (Transport/TransportInny, OpisInnegoTransportu, etc.) with default values (wg ustalenia/umowy) inside WarunkiTransakcji.

Invoice Line-Level Mapping (FaWiersz)

All attributes listed in the following table are properties of objects contained in the array: invoice.invoice_lines_attributes[]. The API Field column refers to keys within each invoice line object.

For regular invoices (VAT, KOR, UPR, ROZ), lines are rendered as FaWiersz elements. For advance payment invoices (ZAL, KOR_ZAL), lines are rendered as ZamowienieWiersz elements.

Additional Item Properties Mapping (DodatkowyOpis per Line)

Each invoice line can carry additional key-value properties that map to line-level DodatkowyOpis elements in the KSeF XML. These correspond to EN 16931 Business Terms BT-160 (Item Attribute Name) and BT-161 (Item Attribute Value).

All attributes listed in the following table are properties of objects contained in the array: invoice.invoice_lines_attributes[].additional_item_properties_attributes[].

Example JSON:

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

Resulting 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>

Note: Line-level DodatkowyOpis elements (with NrWiersza) are distinct from header-level ones (without NrWiersza). The sales order reference (BT-14) uses a header-level DodatkowyOpis, while additional item properties use line-level ones linked by their NrWiersza to the corresponding FaWiersz line number.

Special Property: unit_of_measure

Setting an additional item property with name unit_of_measure allows you to specify a free-text unit code for the line's P_8A field in KSeF, overriding the standard unit codelist. This is useful when the required unit is not available in the standard code list.

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

This property is consumed directly as the line's unit code (Fa/FaWiersz/P_8A) and is not emitted as a DodatkowyOpis element in the XML output.

Taxes Mapping

All attributes listed in the following table are properties of objects contained in the array: invoice.invoice_lines_attributes[].taxes_attributes[]. The API Field column refers to keys within each tax object.

Tax Breakdown Aggregation (P_13_x / P_14_x)

KSeF requires tax amounts to be aggregated by rate at the header level. These fields are automatically computed from the invoice's tax breakdowns:

Note: Fields P_14_xW (tax amounts converted to PLN) are only included for invoices in foreign currencies. The conversion uses the exchange_rate provided in the invoice.