Mapping JSON Invoice Fields to KSeF FA(3) XML

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)

Delivery Mapping (Podmiot3) as Role '2'

Delivery information is mapped to Podmiot3 (third party) with role code 2 (recipient) 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.

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.