Camps JSON de factura a XML KSeF FA(3)

Disponible des de la versió 2025-10-13

Aquesta guia detalla el mapeig entre els camps de la B2Brouter Invoice API, els corresponents Business Terms (BT) definits per l’estàndard europeu de facturació electrònica (EN 16931) i les rutes XML del format KSeF FA(3) (sistema nacional polonès de factura electrònica).

El seu objectiu és ajudar a entendre com les dades de factura enviades en format JSON via Invoice API corresponen a l’estructura XML KSeF FA(3). Només s’hi inclouen els camps que realment es mapen durant la generació del tax report.

Nota

KSeF utilitza un esquema XML específic de Polònia (variant FA 3, versió d’esquema 1-0E), molt diferent dels formats EN 16931 com UBL o CII. No tots els Business Terms EN 16931 tenen un equivalent directe a KSeF, i KSeF introdueix camps específics de Polònia que no existeixen a l’estàndard europeu.

Nota

La informació del venedor/proveïdor (Podmiot1) s’omple automàticament des de la configuració del teu compte. La informació del comprador/client (Podmiot2) s’omple des del contacte de la factura. Si necessites control directe sobre tots els camps, valora utilitzar la Tax Report API.

Mapeig a nivell de capçalera

BT ID	Business Term	Camp API (B2Brouter)	XPath KSeF FA(3)
BT-1	Número de factura	invoice.number	Fa/P_2
BT-2	Data d’emissió	invoice.date	Fa/P_1
BT-3	Codi de tipus de factura	invoice.type_document; derivat: per defecte VAT, KOR si és rectificativa, ZAL si és bestreta, UPR si és simplificada	Fa/RodzajFaktury
BT-5	Moneda de la factura	invoice.currency	Fa/KodWaluty
BT-7	Data del punt d’impost	invoice.tax_point_date	Fa/P_6
BT-9	Data de venciment	invoice.due_date	Fa/Platnosc/TerminPlatnosci/Termin
BT-25	Número de la factura precedent	invoice.invoice_references[reference_type=amend].number (v2026-04-20+) o invoice.amended_number	Fa/DaneFaKorygowanej/NrFaKorygowanej
BT-26	Data de la factura precedent	invoice.invoice_references[reference_type=amend].date (v2026-04-20+) o invoice.amended_date	Fa/DaneFaKorygowanej/DataWystFaKorygowanej
—	Tipus de canvi	invoice.exchange_rate	Fa/KursWalutyZ
BT-10	Referència del comprador	invoice.buyer_reference	Podmiot2/NrKlienta
BT-13	Referència de comanda	invoice.ponumber	Fa/WarunkiTransakcji/Zamowienia/NrZamowienia
BT-92	Data de comanda	invoice.order_date	Fa/WarunkiTransakcji/Zamowienia/DataZamowienia
BT-14	Referència de comanda de venda	invoice.sales_order_reference	Fa/DodatkowyOpis (parella clau-valor)
BT-16	Referència d’albarà	invoice.delivery_note_number	Fa/WZ
—	Codi d’efecte de rectificació	invoice.amend_code_tax o tax_report_setting.credit_note_code	Fa/TypKorekty (només per a tipus KOR)

Mapeig a nivell de pagament

BT ID	Business Term	Camp API (B2Brouter)	XPath KSeF FA(3)
BT-9	Data de venciment	invoice.due_date	Fa/Platnosc/TerminPlatnosci/Termin
BT-81	Codi de mitjà de pagament	invoice.payment_method	Fa/Platnosc/FormaPlatnosci
BT-84	IBAN del compte del beneficiari	invoice.bank_account.iban	Fa/Platnosc/RachunekBankowy/NrRB
BT-84-0	Número de compte del beneficiari	invoice.bank_account.number	Fa/Platnosc/RachunekBankowy/NrRB
BT-85	Nom del compte del beneficiari	invoice.bank_account.name	Fa/Platnosc/RachunekBankowy/NazwaBanku
BT-86	BIC del compte del beneficiari	invoice.bank_account.bic	Fa/Platnosc/RachunekBankowy/SWIFT
—	Indicador de pagada	Derivat: 1 quan payable_amount = 0 i total > 0	Fa/Platnosc/Zaplacono
—	Data de pagament (quan està pagada)	invoice.due_date	Fa/Platnosc/DataZaplaty

Nota: KSeF no admet dades de targeta (BT-87, BT-88), mandats de domiciliació (BT-89), referències de creditor (BT-90), text de termes de pagament (BT-20) ni informació de remesa (BT-83).

Mapeig de parts

Aquest mapeig està descrit per a una factura emesa. Si vols mapar una factura rebuda, intercanvia Podmiot1 i Podmiot2.

Podmiot1 (venedor/proveïdor)

El Podmiot1 s’omple automàticament a partir de la configuració del teu compte. Això inclou el nom de l’empresa, el NIP i l’adreça.

BT ID	Business Term	Camp API (B2Brouter)	XPath KSeF FA(3)
—	Prefix de país del venedor	account.country en majúscules	Podmiot1/PrefiksPodatnika
BT-31	ID fiscal del venedor (NIP)	account.tin_value sense prefix de país	Podmiot1/DaneIdentyfikacyjne/NIP
BT-27	Nom del venedor	account.name	Podmiot1/DaneIdentyfikacyjne/Nazwa
BT-40	País del venedor	account.country en majúscules	Podmiot1/Adres/KodKraju
BT-35	Carrer del venedor	account.address	Podmiot1/Adres/AdresL1
BT-37,38	Codi postal i ciutat del venedor	account.postalcode + account.city	Podmiot1/Adres/AdresL2
BT-29-0	GLN del venedor	account.cin_value (si cin_scheme = 88)	Podmiot1/Adres/GLN
BT-42	Telèfon del venedor	account.phone	Podmiot1/DaneKontaktowe/Telefon
BT-43	Correu del venedor	account.email	Podmiot1/DaneKontaktowe/Email
—	REGON del venedor	account.routing_codes.cinX (scheme 8037)	Stopka/Rejestry/REGON
—	KRS del venedor	account.routing_codes.cinX (scheme 8036)	Stopka/Rejestry/KRS
—	BDO del venedor	account.routing_codes.cinX (scheme 8038)	Stopka/Rejestry/BDO

Podmiot2 (comprador/client)

BT ID	Business Term	Camp API (B2Brouter)	XPath KSeF FA(3)
BT-48	ID fiscal del comprador	invoice.contact.tin_value	PL: Podmiot2/DaneIdentyfikacyjne/NIP; UE: NrVatUE; fora UE: NrID
—	País fiscal del comprador (UE)	invoice.contact.country en majúscules	Podmiot2/DaneIdentyfikacyjne/KodUE
—	País fiscal del comprador (fora UE)	invoice.contact.country en majúscules	Podmiot2/DaneIdentyfikacyjne/KodKraju
—	Indicador sense ID fiscal	Derivat: 1 quan contact.tin_value és buit	Podmiot2/DaneIdentyfikacyjne/BrakID
BT-44	Nom del comprador	invoice.contact.name	Podmiot2/DaneIdentyfikacyjne/Nazwa
BT-55	País del comprador	invoice.contact.country en majúscules	Podmiot2/Adres/KodKraju
BT-50	Carrer del comprador	invoice.contact.address	Podmiot2/Adres/AdresL1
BT-52,53	Codi postal i ciutat del comprador	invoice.contact.postalcode + invoice.contact.city	Podmiot2/Adres/AdresL2
BT-46-0	GLN del comprador	invoice.contact.cin_value (si cin_scheme = 88)	Podmiot2/Adres/GLN

Mapeig de tercers (Podmiot3)

KSeF admet múltiples rols de tercers mitjançant l’element Podmiot3. Es genera un Podmiot3 quan hi ha informació de lliurament o quan la factura té un objecte third_party.

Codis de rol

Codi de rol	third_party.role de B2Brouter	Descripció
2	delivery_recipient	Destinatari del lliurament
3	original_supplier	Entitat original
4	additional_buyer	Comprador addicional
5	invoice_issuer	Emissor de la factura en nom del contribuent
6	payer	Pagador en nom del comprador
7	local_government_unit_issuer	Unitat de govern local emissora
8	local_government_unit_recipient	Unitat de govern local receptora (JST)
9	vat_group_member_issuer	Membre emissor del grup d’IVA
10	vat_group_member_recipient	Membre receptor del grup d’IVA (GV)
11	employee	Empleat

Lliurament (rol 2)

La informació de lliurament es mapeja a Podmiot3 amb codi de rol 2 quan invoice.delivery_address és present. L’adreça de lliurament també es duplica sota Fa/WarunkiTransakcji/Transport/WysylkaDo.

BT ID	Business Term	Camp API (B2Brouter)	XPath KSeF FA(3)
BT-70	Nom de la part de lliurament	invoice.delivery_party_name	Podmiot3/DaneIdentyfikacyjne/Nazwa
BT-71	ID de la ubicació de lliurament (GLN)	invoice.delivery_location_id (si és GLN/088)	Podmiot3/Adres/GLN
BT-75	Carrer de lliurament	invoice.delivery_address	Podmiot3/Adres/AdresL1 i Fa/WarunkiTransakcji/Transport/WysylkaDo/AdresL1
BT-77,78	Codi postal i ciutat de lliurament	invoice.delivery_postalcode + invoice.delivery_city	Podmiot3/Adres/AdresL2 i Fa/WarunkiTransakcji/Transport/WysylkaDo/AdresL2
BT-80	País de lliurament	invoice.delivery_country	Podmiot3/Adres/KodKraju i Fa/WarunkiTransakcji/Transport/WysylkaDo/KodKraju
—	Rol del tercer	Fix: 2	Podmiot3/Rola

Nota: KSeF no admet data de lliurament (BT-72) ni camps de període de lliurament.

JST / GV / altres rols (3–11) — v2026-04-20+

Canviat a la versió 2026-04-20

Suport de tercers més enllà del destinatari de lliurament.

Business Term	Camp API (B2Brouter)	XPath KSeF FA(3)
Nom del tercer	invoice.third_party.name	Podmiot3/DaneIdentyfikacyjne/Nazwa
ID fiscal del tercer	invoice.third_party.tin_value	Podmiot3/DaneIdentyfikacyjne/NIP, NrVatUE o NrID
Adreça del tercer	invoice.third_party.address	Podmiot3/Adres/AdresL1
Codi postal i ciutat del tercer	invoice.third_party.postalcode + invoice.third_party.city	Podmiot3/Adres/AdresL2
País del tercer	invoice.third_party.country	Podmiot3/Adres/KodKraju
Rol del tercer	invoice.third_party.role → codi de rol	Podmiot3/Rola
Indicador JST	invoice.apply_to_local_government_unit	Podmiot2/JST (1 si és cert, 2 si és fals)
Indicador GV	invoice.apply_to_vat_group_member	Podmiot2/GV (1 si és cert, 2 si és fals)

Mapeig a nivell de línia de factura (FaWiersz)

Tots els atributs següents són propietats dels objectes continguts a invoice.invoice_lines_attributes[].

Per a factures normals (VAT, KOR, UPR, ROZ), les línies es renderitzen com a elements FaWiersz. Per a factures de bestreta (ZAL, KOR_ZAL), es renderitzen com a ZamowienieWiersz.

BT ID	Business Term	Camp API (objecte de línia)	XPath KSeF FA(3)
BT-126	ID de línia de factura	position	Fa/FaWiersz/NrWierszaFa
BT-153	Nom de l’article	description	Fa/FaWiersz/P_7
BT-130	Codi d’unitat	unit	Fa/FaWiersz/P_8A
BT-129	Quantitat facturada	quantity	Fa/FaWiersz/P_8B
BT-155	Identificador del venedor	article_code	Fa/FaWiersz/Indeks
BT-157	Identificador estàndard (GTIN)	article_code2	Fa/FaWiersz/GTIN
BT-146	Import del preu	price	Fa/FaWiersz/P_9A
—	Preu unitari descomptat	Derivat de allowance_charges_attributes[]{allowance_charge_indicator: "allowance"} dividit per quantity	Fa/FaWiersz/P_10
BT-131	Import net de línia	extension_amount (si no es proporciona, es calcula)	Fa/FaWiersz/P_11
—	Import fiscal de línia	Calculat a partir d’impostos	Fa/FaWiersz/P_11Vat
—	Codi fiscal	Derivat de les característiques fiscals	Fa/FaWiersz/P_12

Mapeig de propietats addicionals d’ítem (DodatkowyOpis per línia)

Cada línia de factura pot portar propietats addicionals clau-valor que es mapegen a elements DodatkowyOpis a nivell de línia.

BT ID	Business Term	Camp API	XPath KSeF FA(3)
—	Referència del número de línia	position de la línia pare	Fa/DodatkowyOpis/NrWiersza
BT-160	Nom de l’atribut	name (màx. 255 car.)	Fa/DodatkowyOpis/Klucz
BT-161	Valor de l’atribut	value (màx. 255 car.)	Fa/DodatkowyOpis/Wartosc

Exemple JSON:

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

Resultat XML KSeF:

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

Propietat especial: unit_of_measure

Si estableixes una propietat addicional amb nom unit_of_measure, pots especificar un codi d’unitat en text lliure per al camp P_8A, sobreescrivint la codelist estàndard.

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

Aquesta propietat es consumeix directament com a codi d’unitat de la línia (Fa/FaWiersz/P_8A) i no s’emet com a element DodatkowyOpis.

Mapeig d’impostos

Tots els atributs següents són propietats dels objectes continguts a invoice.invoice_lines_attributes[].taxes_attributes[].

BT ID	Business Term	Camp API (objecte d’impost)	Mapatge KSeF FA(3)
BT-118	Codi de categoria fiscal	category	S’utilitza per derivar el codi fiscal P_12
BT-119	Percentatge d’impost aplicable	percent	S’utilitza per derivar P_12 i les agregacions P_13_x/P_14_x
BT-120	Motiu d’exempció fiscal	comment	Fa/Adnotacje/Zwolnienie/P_19A; també accepta un codi KSeF P_12 (zw, np I, np II, 0 KR, 0 WDT, 0 EX, oo) per sobreescriure el valor derivat

Agregació de desglossaments fiscals (P_13_x / P_14_x)

KSeF requereix que els imports fiscals s’agreguin per tipus a nivell de capçalera. Aquests camps es calculen automàticament a partir dels tax breakdowns de la factura:

Camp KSeF	Descripció	Tipus / categoria fiscal
P_13_1	Base imposable al tipus general	23% o 22%
P_14_1	Quota al tipus general	23% o 22%
P_14_1W	Quota al tipus general convertida a PLN	23% o 22% (factures en moneda estrangera)
P_13_2	Base imposable al primer tipus reduït	8% o 7%
P_14_2	Quota al primer tipus reduït	8% o 7%
P_14_2W	Quota al primer tipus reduït convertida a PLN	8% o 7% (factures en moneda estrangera)
P_13_3	Base imposable al segon tipus reduït	5%
P_14_3	Quota al segon tipus reduït	5%
P_14_3W	Quota al segon tipus reduït convertida a PLN	5% (factures en moneda estrangera)
P_13_6_1	Valor total de vendes domèstiques al 0%	0% domèstic
P_13_6_2	Valor total de lliuraments intracomunitaris de béns al 0%	0% intra-UE
P_13_6_3	Valor total d’exportacions al 0%	0% exportació
P_13_7	Valor total de vendes exemptes	Exemptes (categoria E, àmbit domèstic)
P_13_8	Valor total de reverse charge transfronterer	Categoria AE, àmbit no domèstic
P_13_10	Valor total de reverse charge domèstic	Categoria AE, àmbit domèstic
P_15	Import total degut	Suma de totes les categories

Nota

Els camps P_14_xW només s’inclouen per a factures en moneda estrangera. La conversió utilitza l’exchange_rate proporcionat a la factura.