Champs de facture JSON vers XML KSeF FA(3)

Disponible à partir de la version 2025-10-13

Ce guide détaille le mapping entre les champs de l’Invoice API de B2Brouter, les Business Terms (BT) correspondants tels que définis par la norme européenne de facturation électronique (EN 16931), et les chemins XML du format KSeF FA(3) (Système national polonais de facturation électronique).

Son objectif est d’aider à comprendre comment les données de facture soumises au format JSON via l’Invoice API correspondent à la structure XML KSeF FA(3). Seuls les champs réellement mappés lors de la génération de tax reports sont inclus.

Remarque

KSeF utilise un schéma XML spécifique à la Pologne (variante FA 3, version de schéma 1-0E) qui diffère fortement des formats EN 16931 comme UBL ou CII. Tous les Business Terms EN 16931 n’ont pas d’équivalent direct dans KSeF, et KSeF introduit des champs spécifiques à la Pologne absents de la norme européenne.

Remarque : les informations du vendeur/fournisseur (Podmiot1) sont automatiquement alimentées à partir des paramètres de votre compte. Les informations de l’acheteur/client (Podmiot2) sont alimentées à partir du contact de la facture. Si vous avez besoin d’un contrôle direct sur tous les champs, envisagez plutôt d’utiliser la Tax Report API.

Mapping au niveau de l’en-tête

BT ID	Business Term	API Field (B2Brouter)	KSeF FA(3) XPath
BT-1	Invoice Number	invoice.number	Fa/P_2
BT-2	Invoice Issue Date	invoice.date	Fa/P_1
BT-3	Invoice Type Code	invoice.type_document Derived: defaults to VAT; KOR if amended invoice; ZAL if advance; UPR if simplified	Fa/RodzajFaktury
BT-5	Invoice Currency	invoice.currency	Fa/KodWaluty
BT-7	Tax Point Date	invoice.tax_point_date	Fa/P_6
BT-9	Payment Due Date	invoice.due_date	Fa/Platnosc/TerminPlatnosci/Termin
BT-25	Preceding Invoice Number	invoice.invoice_references[reference_type=amend].number (v2026-04-20+) or invoice.amended_number (older versions)	Fa/DaneFaKorygowanej/NrFaKorygowanej
BT-26	Preceding Invoice Issue Date	invoice.invoice_references[reference_type=amend].date (v2026-04-20+) or invoice.amended_date (older versions)	Fa/DaneFaKorygowanej/DataWystFaKorygowanej
—	Exchange Rate	invoice.exchange_rate	Fa/KursWalutyZ
BT-10	Buyer Reference	invoice.buyer_reference	Podmiot2/NrKlienta
BT-13	Purchase Order Reference	invoice.ponumber	Fa/WarunkiTransakcji/Zamowienia/NrZamowienia
BT-92	Purchase Order Date	invoice.order_date	Fa/WarunkiTransakcji/Zamowienia/DataZamowienia
BT-14	Sales Order Reference	invoice.sales_order_reference	Fa/DodatkowyOpis (key-value pair)
BT-16	Despatch Advice Reference	invoice.delivery_note_number	Fa/WZ
—	Correction Effect Code	invoice.amend_code_tax or tax_report_setting.credit_note_code	Fa/TypKorekty (only for KOR types)

Payment-Level Mapping

BT ID	Business Term	API Field (B2Brouter)	KSeF FA(3) XPath
BT-9	Payment Due Date	invoice.due_date	Fa/Platnosc/TerminPlatnosci/Termin
BT-81	Payment Means Code	invoice.payment_method (mapped to KSeF codes)	Fa/Platnosc/FormaPlatnosci
BT-84	Payee Financial Account IBAN	invoice.bank_account.iban	Fa/Platnosc/RachunekBankowy/NrRB
BT-84-0	Payee Financial Account Number	invoice.bank_account.number (fallback if no IBAN)	Fa/Platnosc/RachunekBankowy/NrRB
BT-85	Payee Financial Account Name	invoice.bank_account.name	Fa/Platnosc/RachunekBankowy/NazwaBanku
BT-86	Payee Financial Account BIC	invoice.bank_account.bic	Fa/Platnosc/RachunekBankowy/SWIFT
—	Paid Flag	Derived: 1 when payable_amount = 0 and total > 0	Fa/Platnosc/Zaplacono
—	Payment Date (when paid)	invoice.due_date (when Zaplacono=1)	Fa/Platnosc/DataZaplaty

Remarque : KSeF ne prend pas en charge les détails de carte (BT-87, BT-88), les mandats de prélèvement (BT-89), les références créancier (BT-90), le texte des conditions de paiement (BT-20) ni les références de paiement (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.

BT ID	Business Term	API Field (B2Brouter)	KSeF FA(3) XPath
—	Seller Country Prefix	account.country (uppercased)	Podmiot1/PrefiksPodatnika
BT-31	Seller Tax Registration ID (NIP)	account.tin_value (without country prefix)	Podmiot1/DaneIdentyfikacyjne/NIP
BT-27	Seller Party Name	account.name	Podmiot1/DaneIdentyfikacyjne/Nazwa
BT-40	Seller Address Country	account.country (uppercased)	Podmiot1/Adres/KodKraju
BT-35	Seller Address Street	account.address	Podmiot1/Adres/AdresL1
BT-37,38	Seller Postal Code + City	account.postalcode + account.city	Podmiot1/Adres/AdresL2
BT-29-0	Seller GLN	account.cin_value (if cin_scheme = 88)	Podmiot1/Adres/GLN
BT-42	Seller Contact Telephone	account.phone	Podmiot1/DaneKontaktowe/Telefon
BT-43	Seller Contact Email	account.email	Podmiot1/DaneKontaktowe/Email
—	Seller REGON	account.routing_codes.cinX (scheme 8037)	Stopka/Rejestry/REGON
—	Seller KRS	account.routing_codes.cinX (scheme 8036)	Stopka/Rejestry/KRS
—	Seller BDO	account.routing_codes.cinX (scheme 8038)	Stopka/Rejestry/BDO

Podmiot2 (Buyer/Customer)

BT ID	Business Term	API Field (B2Brouter)	KSeF FA(3) XPath
BT-48	Buyer Tax Registration ID	invoice.contact.tin_value	PL: Podmiot2/DaneIdentyfikacyjne/NIP EU: Podmiot2/DaneIdentyfikacyjne/NrVatUE Non-EU: Podmiot2/DaneIdentyfikacyjne/NrID
—	Buyer Tax Country (EU)	invoice.contact.country (uppercased)	Podmiot2/DaneIdentyfikacyjne/KodUE (EU only)
—	Buyer Tax Country (Non-EU)	invoice.contact.country (uppercased)	Podmiot2/DaneIdentyfikacyjne/KodKraju (non-EU only)
—	No Tax ID Flag	Derived: 1 when contact.tin_value is blank	Podmiot2/DaneIdentyfikacyjne/BrakID
BT-44	Buyer Party Name	invoice.contact.name	Podmiot2/DaneIdentyfikacyjne/Nazwa
BT-55	Buyer Address Country	invoice.contact.country (uppercased)	Podmiot2/Adres/KodKraju
BT-50	Buyer Address Street	invoice.contact.address	Podmiot2/Adres/AdresL1
BT-52,53	Buyer Postal Code + City	invoice.contact.postalcode + invoice.contact.city	Podmiot2/Adres/AdresL2
BT-46-0	Buyer GLN	invoice.contact.cin_value (if cin_scheme = 88)	Podmiot2/Adres/GLN

Third Party Mapping (Podmiot3)

KSeF prend en charge plusieurs rôles de tiers via l’élément Podmiot3. Un Podmiot3 est généré lorsque des informations de livraison sont présentes ou lorsque la facture possède un objet third_party (disponible à partir de v2026-04-20).

Codes de rôle

Role Code	B2Brouter third_party.role	Description
2	delivery_recipient	Delivery recipient
3	original_supplier	Original entity (taken over/transformed)
4	additional_buyer	Additional purchaser
5	invoice_issuer	Invoice issuer on behalf of taxpayer
6	payer	Payer on behalf of purchaser
7	local_government_unit_issuer	Local government unit — issuer
8	local_government_unit_recipient	Local government unit — recipient (JST)
9	vat_group_member_issuer	VAT group member — issuer
10	vat_group_member_recipient	VAT group member — recipient (GV)
11	employee	Employee

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.

BT ID	Business Term	API Field (B2Brouter)	KSeF FA(3) XPath
BT-70	Delivery Party Name	invoice.delivery_party_name	Podmiot3/DaneIdentyfikacyjne/Nazwa
BT-71	Delivery Location ID (GLN)	invoice.delivery_location_id (if type is GLN/088)	Podmiot3/Adres/GLN
BT-75	Delivery Address Street	invoice.delivery_address	Podmiot3/Adres/AdresL1 and Fa/WarunkiTransakcji/Transport/WysylkaDo/AdresL1
BT-77,78	Delivery Postal Code + City	invoice.delivery_postalcode + invoice.delivery_city	Podmiot3/Adres/AdresL2 and Fa/WarunkiTransakcji/Transport/WysylkaDo/AdresL2
BT-80	Delivery Country	invoice.delivery_country	Podmiot3/Adres/KodKraju and Fa/WarunkiTransakcji/Transport/WysylkaDo/KodKraju
—	Third Party Role	Fixed: 2 (Recipient)	Podmiot3/Rola

Remarque : KSeF ne prend pas en charge la date de livraison (BT-72) ni les champs de période de livraison.

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

Changed in version 2026-04-20

Third-party support beyond delivery recipient.

Business Term	API Field (B2Brouter)	KSeF FA(3) XPath
Third Party Name	invoice.third_party.name	Podmiot3/DaneIdentyfikacyjne/Nazwa
Third Party Tax ID	invoice.third_party.tin_value	Podmiot3/DaneIdentyfikacyjne/NIP (PL), NrVatUE (EU), or NrID (non-EU)
Third Party Address	invoice.third_party.address	Podmiot3/Adres/AdresL1
Third Party Postal Code + City	invoice.third_party.postalcode + invoice.third_party.city	Podmiot3/Adres/AdresL2
Third Party Country	invoice.third_party.country	Podmiot3/Adres/KodKraju
Third Party Role	invoice.third_party.role → role code	Podmiot3/Rola
JST flag	invoice.apply_to_local_government_unit	Podmiot2/JST (1 when true, 2 when false)
GV flag	invoice.apply_to_vat_group_member	Podmiot2/GV (1 when true, 2 when false)

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.

BT ID	Business Term	API Field (invoice line object)	KSeF FA(3) XPath
BT-126	Invoice Line ID	position	Fa/FaWiersz/NrWierszaFa
BT-153	Item Name	description	Fa/FaWiersz/P_7
BT-130	Billed Quantity (Unit Code)	unit (check API Reference for code list)	Fa/FaWiersz/P_8A
BT-129	Billed Quantity	quantity	Fa/FaWiersz/P_8B
BT-155	Item Seller Identifier	article_code	Fa/FaWiersz/Indeks
BT-157	Item Standard Identifier (GTIN)	article_code2	Fa/FaWiersz/GTIN
BT-146	Price Amount	price	Fa/FaWiersz/P_9A
-	Discount Unit Price	Derived from line allowance_charges_attributes[]{allowance_charge_indicator: "allowance"} amount / quantity	Fa/FaWiersz/P_10
BT-131	Line Net Amount	extension_amount (if not provided, it will be calculated)	Fa/FaWiersz/P_11
—	Line Tax Amount	Computed from taxes	Fa/FaWiersz/P_11Vat
—	Tax Code	Derived from tax characteristics	Fa/FaWiersz/P_12

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.

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

BT ID	Business Term	API Field (additional item property object)	KSeF FA(3) XPath
—	Line Number Reference	Parent line’s position	Fa/DodatkowyOpis/NrWiersza
BT-160	Item Attribute Name	name (max 255 chars)	Fa/DodatkowyOpis/Klucz
BT-161	Item Attribute Value	value (max 255 chars)	Fa/DodatkowyOpis/Wartosc

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>

Propriété spéciale : unit_of_measure

La définition d’une propriété additionnelle d’article avec le nom unit_of_measure permet de spécifier un code d’unité en texte libre pour le champ P_8A de KSeF, en surchargeant la liste standard des codes d’unité.

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

Cette propriété est utilisée directement comme code d’unité de la ligne (Fa/FaWiersz/P_8A) et n’est pas émise en tant qu’élément DodatkowyOpis dans la sortie XML.

Taxes Mapping

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

BT ID	Business Term	API Field (tax object)	KSeF FA(3) Mapping
BT-118	Tax Category Code	category (check our code list)	Used to derive P_12 tax code
BT-119	Tax Rate Applicable Percent	percent	Used to derive P_12 tax code and P_13_x/P_14_x aggregations
BT-120	Tax Exemption Reason	comment	Fa/Adnotacje/Zwolnienie/P_19A. Also accepts a KSeF P_12 code (zw, np I, np II, 0 KR, 0 WDT, 0 EX, oo) to override the derived value.

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:

KSeF Field	Description	Tax Rate / Category
P_13_1	Taxable base at basic rate	23% or 22%
P_14_1	Tax amount at basic rate	23% or 22%
P_14_1W	Tax amount at basic rate converted to PLN	23% or 22% (foreign currency invoices only)
P_13_2	Taxable base at first reduced rate	8% or 7%
P_14_2	Tax amount at first reduced rate	8% or 7%
P_14_2W	Tax amount at first reduced rate converted to PLN	8% or 7% (foreign currency invoices only)
P_13_3	Taxable base at second reduced rate	5%
P_14_3	Tax amount at second reduced rate	5%
P_14_3W	Tax amount at second reduced rate converted to PLN	5% (foreign currency invoices only)
P_13_6_1	Total value of domestic zero-rated sales	0% domestic (excluding intra-EU and export)
P_13_6_2	Total value of intra-Community supply of goods at 0%	0% intra-EU goods
P_13_6_3	Total value of exports at 0%	0% export
P_13_7	Total value of exempt sales	Exempt (category E, domestic scope)
P_13_8	Total value of cross-border reverse charge (np I)	Category AE, non-domestic scope
P_13_10	Total value of domestic reverse charge	Category AE, domestic scope
P_15	Total amount due (inclusive of all taxes)	Sum of all categories

Remarque

Les champs P_14_xW (montants de taxe convertis en PLN) ne sont inclus que pour les factures en devise étrangère. La conversion utilise le exchange_rate fourni dans la facture.