UBL JSON to KSeF FA(3) Mapping Reference

This document describes how UBL JSON invoice payloads are mapped to the Polish KSeF FA(3) e-invoice format.

Invoice Header

Fa = Faktura = invoice

KodWaluty = Currency code

RodzajFaktury = Invoice type

FA(3) Field	UBL JSON	Req.	Default	Condition	Description
Fa.P_2	document > invoice > invoiceNumber JSONPath $.document.invoice.invoiceNumber	Yes			Invoice number
Fa.P_1	document > invoice > issueDate JSONPath $.document.invoice.issueDate	Yes			Invoice issue date. Formatted as date (Y-m-d)
Fa.KodWaluty	document > invoice > documentCurrencyCode JSONPath $.document.invoice.documentCurrencyCode	Yes			Currency code
Fa.RodzajFaktury	document > documentType JSONPath $.document.documentType	Yes			Invoice type. Storecove has no separate credit note. Map: invoice → VAT credit_note → KOR STRICT
Fa.RodzajFaktury		No	KOR	The document references the invoice it corrects	Invoice type. Storecove has no separate credit note

Correction Invoice

KOR = Faktura Korygujaca = correction invoice

DaneFaKorygowanej = Data of the corrected invoice

NrFaKorygowanej = Number of the corrected invoice

DataWystFaKorygowanej = Issue date of the corrected invoice

FA(3) Field	UBL JSON	Req.	Default	Condition	Description
Fa.DaneFaKorygowanej	document > invoice > references[?(@.documentType == 'billing')] JSONPath $.document.invoice.references[?(@.documentType == 'billing')]	No		The document references the invoice it corrects	The invoice each "billing" reference corrects.. Grouped by rowIndex

Fa.DaneFaKorygowanej

DaneFaKorygowanej = Data of the corrected invoice

FA(3) Field	UBL JSON	Req.	Default	Condition	Description
DataWystFaKorygowanej	$.issueDate	Yes			Issue date of the corrected invoice. Formatted as date (Y-m-d)
NrFaKorygowanej	$.documentId	Yes			Number of the corrected invoice
NrKSeF		No	1	The reference carries a KSeF identifier instead of a seller number	Flag indicating the corrected invoice was in KSeF
NrKSeFFaKorygowanej	$.documentId	No		The reference carries a KSeF identifier instead of a seller number	KSeF identifier of the corrected invoice
NrKSeFN		No	1	NOT: The reference carries a KSeF identifier instead of a seller number	Flag indicating the corrected invoice was NOT in KSeF

Seller

Podmiot1 = Subject/entity 1 (seller)

DaneIdentyfikacyjne = Identification data

NIP = Polish tax ID

Nazwa = Name

Adres = Address

KodKraju = Country code

AdresL1 = Address line 1

AdresL2 = Address line 2

FA(3) Field	UBL JSON	Req.	Default	Condition	Description
Podmiot1.DaneIdentyfikacyjne.NIP	document > invoice > accountingSupplierParty > publicIdentifiers[?search(@.scheme, 'VAT')] > id JSONPath $.document.invoice.accountingSupplierParty.publicIdentifiers[?search(@.scheme, 'VAT')].id	No			Seller tax identification number (10 digits, PL prefix stripped). Extracted via regex /^(?:[A-Z]{2})?([0-9]+)$/
Podmiot1.DaneIdentyfikacyjne.Nazwa	document > invoice > accountingSupplierParty > party > companyName JSONPath $.document.invoice.accountingSupplierParty.party.companyName	No			Seller name
Podmiot1.Adres.KodKraju	document > invoice > accountingSupplierParty > party > address > country JSONPath $.document.invoice.accountingSupplierParty.party.address.country	No			Seller country code
Podmiot1.Adres.AdresL1	document > invoice > accountingSupplierParty > party > address > street1 JSONPath $.document.invoice.accountingSupplierParty.party.address.street1	No			Seller street address
Podmiot1.Adres.AdresL2	document > invoice > accountingSupplierParty > party > address > zip JSONPath $.document.invoice.accountingSupplierParty.party.address.zip	No			Seller postal code and city. Computed: trim(source ~ ' ' ~ jsonpath(row, '$.document.invoice.accountingSupplierParty.party.address.city'))

Buyer

Podmiot2 = Subject/entity 2 (buyer)

JST = Local government unit flag

GV = VAT group flag

FA(3) Field	UBL JSON	Req.	Default	Condition	Description
Podmiot2.DaneIdentyfikacyjne.Nazwa	document > invoice > accountingCustomerParty > party > companyName JSONPath $.document.invoice.accountingCustomerParty.party.companyName	Yes			Buyer name
Podmiot2.DaneIdentyfikacyjne.NIP	document > invoice > accountingCustomerParty > publicIdentifiers[?search(@.scheme, 'VAT|IVA')] > id JSONPath $.document.invoice.accountingCustomerParty.publicIdentifiers[?search(@.scheme, 'VAT|IVA')].id	Yes		Buyer is Polish or country not specified	Buyer tax ID (Polish buyer, PL prefix stripped). Extracted via regex /^(?:[A-Z]{2})?([0-9]+)$/
Podmiot2.DaneIdentyfikacyjne.KodUE	document > invoice > accountingCustomerParty > party > address > country JSONPath $.document.invoice.accountingCustomerParty.party.address.country	Yes		Buyer is established in another EU member state	VAT country prefix of an EU buyer. Map: GR → EL
Podmiot2.DaneIdentyfikacyjne.NrVatUE	document > invoice > accountingCustomerParty > publicIdentifiers[?search(@.scheme, 'VAT|IVA')] > id JSONPath $.document.invoice.accountingCustomerParty.publicIdentifiers[?search(@.scheme, 'VAT|IVA')].id	Yes		Buyer is established in another EU member state	EU VAT identifier with the optional country prefix stripped. Extracted via regex /^(?:[A-Z]{2})?([A-Za-z0-9]+)$/
Podmiot2.DaneIdentyfikacyjne.KodKraju	document > invoice > accountingCustomerParty > party > address > country JSONPath $.document.invoice.accountingCustomerParty.party.address.country	Yes		Buyer outside the EU, identified by KodKraju and NrID	Tax ID country of a buyer outside the EU
Podmiot2.DaneIdentyfikacyjne.NrID	document > invoice > accountingCustomerParty > publicIdentifiers[?search(@.scheme, 'VAT|IVA')] > id JSONPath $.document.invoice.accountingCustomerParty.publicIdentifiers[?search(@.scheme, 'VAT|IVA')].id	Yes		Buyer outside the EU, identified by KodKraju and NrID	Other tax identifier, kept as the sender supplied it
Podmiot2.Adres.KodKraju	document > invoice > accountingCustomerParty > party > address > country JSONPath $.document.invoice.accountingCustomerParty.party.address.country	No			Buyer country code
Podmiot2.Adres.AdresL1	document > invoice > accountingCustomerParty > party > address > street1 JSONPath $.document.invoice.accountingCustomerParty.party.address.street1	No			Buyer street address
Podmiot2.Adres.AdresL2	document > invoice > accountingCustomerParty > party > address > zip JSONPath $.document.invoice.accountingCustomerParty.party.address.zip	No			Buyer postal code and city. Computed: trim(source ~ ' ' ~ jsonpath(row, '$.document.invoice.accountingCustomerParty.party.address.city'))
Podmiot2.jST		No	2		Local government unit flag (always "no")
Podmiot2.gV		No	2		VAT group flag (always "no")

Tax Totals

FA(3) Field	UBL JSON	Req.	Default	Condition	Description
Fa.P_13_1	document > invoice > taxSubtotals[?(@.percentage == 23)] > taxableAmount JSONPath $.document.invoice.taxSubtotals[?(@.percentage == 23)].taxableAmount	No			Net amount at 23% VAT rate
Fa.P_14_1	document > invoice > taxSubtotals[?(@.percentage == 23)] > taxAmount JSONPath $.document.invoice.taxSubtotals[?(@.percentage == 23)].taxAmount	No			Tax amount at 23% VAT rate
Fa.P_13_2	document > invoice > taxSubtotals[?(@.percentage == 8)] > taxableAmount JSONPath $.document.invoice.taxSubtotals[?(@.percentage == 8)].taxableAmount	No			Net amount at 8% VAT rate
Fa.P_14_2	document > invoice > taxSubtotals[?(@.percentage == 8)] > taxAmount JSONPath $.document.invoice.taxSubtotals[?(@.percentage == 8)].taxAmount	No			Tax amount at 8% VAT rate
Fa.P_13_3	document > invoice > taxSubtotals[?(@.percentage == 5)] > taxableAmount JSONPath $.document.invoice.taxSubtotals[?(@.percentage == 5)].taxableAmount	No			Net amount at 5% VAT rate
Fa.P_14_3	document > invoice > taxSubtotals[?(@.percentage == 5)] > taxAmount JSONPath $.document.invoice.taxSubtotals[?(@.percentage == 5)].taxAmount	No			Tax amount at 5% VAT rate
Fa.P_13_6_2	document > invoice > taxSubtotals[?(@.category == 'intra_community')] > taxableAmount JSONPath $.document.invoice.taxSubtotals[?(@.category == 'intra_community')].taxableAmount	No			Net amount of intra-community supplies (0% WDT).
Fa.P_13_6_1	document > invoice > taxSubtotals[?(@.category == 'zero_rated')] > taxableAmount JSONPath $.document.invoice.taxSubtotals[?(@.category == 'zero_rated')].taxableAmount	No			Net amount at the domestic 0% rate (0 KR)
Fa.P_13_6_3	document > invoice > taxSubtotals[?(@.category == 'export')] > taxableAmount JSONPath $.document.invoice.taxSubtotals[?(@.category == 'export')].taxableAmount	No			Net amount of exports (0 EX)
Fa.P_13_7	document > invoice > taxSubtotals[?(@.category == 'exempt')] > taxableAmount JSONPath $.document.invoice.taxSubtotals[?(@.category == 'exempt')].taxableAmount	No			Net amount of VAT-exempt sales
Fa.P_13_8	document > invoice > taxSubtotals[?(@.category == 'outside_scope')] > taxableAmount JSONPath $.document.invoice.taxSubtotals[?(@.category == 'outside_scope')].taxableAmount	No		Out-of-scope supply reported as "np I"	Net amount of supplies outside Poland, other than the
Fa.P_13_9	document > invoice > taxSubtotals[?(@.category == 'outside_scope')] > taxableAmount JSONPath $.document.invoice.taxSubtotals[?(@.category == 'outside_scope')].taxableAmount	No		Out-of-scope supply reported as "np II" (article 100(1)(4) services)	Net amount of article 100(1)(4) services
Fa.P_13_10	document > invoice > taxSubtotals[?(@.category == 'reverse_charge')] > taxableAmount JSONPath $.document.invoice.taxSubtotals[?(@.category == 'reverse_charge')].taxableAmount	No			Net amount under the domestic reverse charge procedure.
Fa.P_14_1W	document > invoice > taxSubtotals[?(@.percentage == 23)] > taxAmountPLN JSONPath $.document.invoice.taxSubtotals[?(@.percentage == 23)].taxAmountPLN	No		jsonpath(row, '$.document.invoice.documentCurrencyCode') != 'PLN'
Fa.P_14_2W	document > invoice > taxSubtotals[?(@.percentage == 8)] > taxAmountPLN JSONPath $.document.invoice.taxSubtotals[?(@.percentage == 8)].taxAmountPLN	No		jsonpath(row, '$.document.invoice.documentCurrencyCode') != 'PLN'
Fa.P_14_3W	document > invoice > taxSubtotals[?(@.percentage == 5)] > taxAmountPLN JSONPath $.document.invoice.taxSubtotals[?(@.percentage == 5)].taxAmountPLN	No		jsonpath(row, '$.document.invoice.documentCurrencyCode') != 'PLN'

Total Amount

FA(3) Field	UBL JSON	Req.	Default	Condition	Description
Fa.P_15	document > invoice > amountIncludingVat JSONPath $.document.invoice.amountIncludingVat	Yes			Total payable amount

Annotations

Adnotacje = Annotations

Zwolnienie = VAT exemption

NoweSrodkiTransportu = New means of transport

PMarzy = Margin scheme (procedura marzy)

FA(3) Field	UBL JSON	Req.	Default	Condition	Description
Fa.Adnotacje.P_16		No	2		Self-billing annotation (always "no")
Fa.Adnotacje.P_17		No	2		Self-billing invoice (always "no")
Fa.Adnotacje.P_18		No	1	!empty(jsonpath(row, "$.document.invoice.taxSubtotals[?(@.category == 'reverse_charge')]")) Buyer is Polish or country not specified	Reverse charge annotation. Only the domestic procedure is
Fa.Adnotacje.P_18A		No	-		Explicit split payment; omitted means not applicable.. Computed: row['_crawler'].find('$.document.invoice.SplitPayment') === [] ? '2' : (jsonpath(row, '$.document.invoice.SplitPayment') === 1 ? '1' : 'unsupported'). Map: 1 → 1 2 → 2 STRICT
Fa.Adnotacje.Zwolnienie.P_19		No	1	The invoice carries VAT-exempt lines	VAT exemption present. Article 106e(1)(19) of the Polish VAT act
Fa.Adnotacje.Zwolnienie.P_19A	document > invoice > taxSubtotals[?(@.category == 'exempt')] > taxExemptionReason JSONPath $.document.invoice.taxSubtotals[?(@.category == 'exempt')].taxExemptionReason	Yes		hasExemptSale() and !isDirectiveExemption() and !isOtherExemption()	Exemption under the Polish VAT act
Fa.Adnotacje.Zwolnienie.P_19B	document > invoice > taxSubtotals[?(@.category == 'exempt')] > taxExemptionReason JSONPath $.document.invoice.taxSubtotals[?(@.category == 'exempt')].taxExemptionReason	Yes		hasExemptSale() and isDirectiveExemption()	Exemption under directive 2006/112/EC
Fa.Adnotacje.Zwolnienie.P_19C	document > invoice > taxSubtotals[?(@.category == 'exempt')] > taxExemptionReason JSONPath $.document.invoice.taxSubtotals[?(@.category == 'exempt')].taxExemptionReason	Yes		hasExemptSale() and isOtherExemption()	Exemption under another legal basis
Fa.Adnotacje.Zwolnienie.P_19N		No	1	NOT: The invoice carries VAT-exempt lines	No VAT exemption
Fa.Adnotacje.NoweSrodkiTransportu.P_22N		No	1		New means of transport not applicable
Fa.Adnotacje.P_23		No	2		Simplified triangular transaction (always "no")
Fa.Adnotacje.PMarzy.P_PMarzyN		No	1		Margin scheme not applied

Delivery notes and additional notes

FA(3) Field	UBL JSON	Req.	Default	Condition	Description
Fa.WZ		No	-		Computed: row['_crawler'].find("$.document.invoice..references[?(@.documentType == 'despatch_advice')].documentId"). Transform: unique

Transaction conditions

WarunkiTransakcji = Transaction conditions

Umowy = Contracts

Zamowienia = Orders

NrPartiiTowaru = Goods batch numbers

FA(3) Field	UBL JSON	Req.	Default	Condition	Description
Fa.WarunkiTransakcji.Umowy	document > invoice > references[?(@.documentType == 'contract')] JSONPath $.document.invoice.references[?(@.documentType == 'contract')]	No		!empty(jsonpath(row, "$.document.invoice.references[?(@.documentType == 'contract')]"))	Contract the invoice relates to. Grouped by $.documentId
Fa.WarunkiTransakcji.Zamowienia	document > invoice > references[?(@.documentType == 'purchase_order')] JSONPath $.document.invoice..references[?(@.documentType == 'purchase_order')]	No		!empty(jsonpath(row, "$.document.invoice..references[?(@.documentType == 'purchase_order')]"))	Purchase orders the invoice refers to. Grouped by $.documentId
Fa.WarunkiTransakcji.NrPartiiTowaru		No	-	!empty(jsonpath(row, "$.document.invoice..references[?(@.documentType == 'line_document_reference')]"))	Batch numbers, sent per line as line_document_reference. Computed: row['_crawler'].find("$.document.invoice..references[?(@.documentType == 'line_document_reference')].documentId"). Transform: unique
Fa.DodatkowyOpis	document > invoice > notes[*] JSONPath $.document.invoice.notes[*]	No		!empty(jsonpath(row, '$.document.invoice.notes'))	Grouped by rowIndex
Fa.DodatkowyOpis[legacyNote].Klucz		No	Note	empty(jsonpath(row, '$.document.invoice.notes')) and !empty(jsonpath(row, '$.document.invoice.note'))
Fa.DodatkowyOpis[legacyNote].Wartosc	document > invoice > note JSONPath $.document.invoice.note	No		empty(jsonpath(row, '$.document.invoice.notes'))

Fa.WarunkiTransakcji.Umowy

Umowy = Contracts

FA(3) Field	UBL JSON	Req.	Default	Condition	Description
NrUmowy	$.documentId	Yes
DataUmowy	$.issueDate	No			Formatted as date (Y-m-d)

Fa.WarunkiTransakcji.Zamowienia

Zamowienia = Orders

FA(3) Field	UBL JSON	Req.	Default	Condition	Description
NrZamowienia	$.documentId	Yes
DataZamowienia	$.issueDate	No			Formatted as date (Y-m-d)

Fa.DodatkowyOpis

FA(3) Field	UBL JSON	Req.	Default	Condition	Description
Klucz		No	Note
Wartosc	$	Yes

Payment

FA(3) Field	UBL JSON	Req.	Default	Condition	Description
Fa.Platnosc.TerminPlatnosci[0].Termin	document > invoice > dueDate JSONPath $.document.invoice.dueDate	No			Formatted as date (Y-m-d)
Fa.Platnosc.RachunekBankowy	document > invoice > paymentMeansArray[?(@.code == 'credit_transfer' || @.code == 'sepa_credit_transfer')] JSONPath $.document.invoice.paymentMeansArray[?(@.code == 'credit_transfer' || @.code == 'sepa_credit_transfer')]	No		!empty(jsonpath(row, "$.document.invoice.paymentMeansArray[?(@.code == 'credit_transfer' || @.code == 'sepa_credit_transfer')]"))	Grouped by rowIndex
Fa.Platnosc.RachunekBankowy[0].NrRB	document > invoice > paymentMeansIban JSONPath $.document.invoice.paymentMeansIban	No		!hasPaymentMeans()
Fa.Platnosc.RachunekBankowy[0].SWIFT	document > invoice > paymentMeansBic JSONPath $.document.invoice.paymentMeansBic	No		!hasPaymentMeans() and !empty(jsonpath(row, '$.document.invoice.paymentMeansIban'))
Fa.Platnosc.FormaPlatnosci		No	-	knownPaymentMethod()	Computed: empty(jsonpath(row, '$.document.invoice.paymentMeansArray')) ? jsonpath(row, '$.document.invoice.paymentMeansCode') : jsonpath(row, '$.document.invoice.paymentMeansArray[0].code'). Map: cash → 1 card → 2 bank_card → 2 credit_card → 2 bank_cheque → 4 cashiers_cheque → 4 credit_transfer → 6 sepa_credit_transfer → 6 STRICT
Fa.Platnosc.PlatnoscInna		No	1	!knownPaymentMethod() and (hasPaymentMeans() or !empty(jsonpath(row, '$.document.invoice.paymentMeansCode')))
Fa.Platnosc.OpisPlatnosci		No	-	!knownPaymentMethod() and (hasPaymentMeans() or !empty(jsonpath(row, '$.document.invoice.paymentMeansCode')))	Computed: empty(jsonpath(row, '$.document.invoice.paymentMeansArray')) ? [jsonpath(row, '$.document.invoice.paymentMeansCode')] : row['_crawler'].find('$.document.invoice.paymentMeansArray[*].code'). Transform: arrayReduce
Fa.Platnosc.Zaplacono		No	-	!empty(jsonpath(row, '$.document.invoice.prepaidAmount')) or hasDatedPayment()	Computed: (!empty(jsonpath(row, '$.document.invoice.prepaidAmount')) or (!empty(jsonpath(row, '$.document.invoice.prepaidPayments')) and row['_crawler'].find('$.document.invoice.prepaidAmount') !== [])) ? 'prepaidAmount has no payment date; supply one prepaidPayments item with amount and date instead' : (!empty(jsonpath(row, '$.document.invoice.prepaidPayments[1]')) ? 'only one prepaidPayments item is supported' : (jsonpath(row, '$.document.invoice.prepaidPayments[0].amount') > 0 and jsonpath(row, '$.document.invoice.prepaidPayments[0].amount') <= jsonpath(row, '$.document.invoice.amountIncludingVat') ? (jsonpath(row, '$.document.invoice.prepaidPayments[0].amount') == jsonpath(row, '$.document.invoice.amountIncludingVat') ? '1' : 'partial') : 'prepaidPayments amount must be positive and not exceed the invoice total')). Map: 1 → 1 partial → `` STRICT
Fa.Platnosc.DataZaplaty	document > invoice > prepaidPayments[0] > date JSONPath $.document.invoice.prepaidPayments[0].date	Yes		hasDatedPayment() and paidInFull()	Formatted as date (Y-m-d). Computed: source.format('Y-m-d') == jsonpath(row, '$.document.invoice.prepaidPayments[0].date') and source.format('Y-m-d') <= jsonpath(row, '$.document.invoice.issueDate') ? source.format('Y-m-d') : 'invalid prepaidPayments date: must be a real date on or before issueDate'. Formatted as date (Y-m-d)
Fa.Platnosc.ZnacznikZaplatyCzesciowej		No	1	hasDatedPayment() and !paidInFull()
Fa.Platnosc.ZaplataCzesciowa[0].KwotaZaplatyCzesciowej	document > invoice > prepaidPayments[0] > amount JSONPath $.document.invoice.prepaidPayments[0].amount	No		hasDatedPayment() and !paidInFull()
Fa.Platnosc.ZaplataCzesciowa[0].DataZaplatyCzesciowej	document > invoice > prepaidPayments[0] > date JSONPath $.document.invoice.prepaidPayments[0].date	Yes		hasDatedPayment() and !paidInFull()	Formatted as date (Y-m-d). Computed: source.format('Y-m-d') == jsonpath(row, '$.document.invoice.prepaidPayments[0].date') and source.format('Y-m-d') <= jsonpath(row, '$.document.invoice.issueDate') ? source.format('Y-m-d') : 'invalid prepaidPayments date: must be a real date on or before issueDate'. Formatted as date (Y-m-d)

Fa.Platnosc.RachunekBankowy

FA(3) Field	UBL JSON	Req.	Default	Condition	Description
NrRB	$.account	Yes
SWIFT	$.branche_code	No		jsonpath(row, '$.branche_code') matches '/^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$/'
OpisRachunku	$.holder	No

Invoice Lines

FaWiersz = Faktura wiersz = invoice line

NrWierszaFa = Invoice line number

P_7 = Item name

P_8B = Quantity

P_9A = Unit net price

P_11 = Line net amount

P_12 = VAT rate

FA(3) Field	UBL JSON	Req.	Default	Condition	Description
Fa.FaWiersz	document > invoice > invoiceLines[*] JSONPath $.document.invoice.invoiceLines[*]	No			Invoice lines. Grouped by rowIndex

Fa.FaWiersz

FaWiersz = Faktura wiersz = invoice line

FA(3) Field	UBL JSON	Req.	Default	Condition	Description
NrWierszaFa	_index	No			Invoice line number
P_7	$.name	No			Item name
Indeks	references[?(@.documentType == 'line_sellers_item_identification')] > documentId JSONPath $.references[?(@.documentType == 'line_sellers_item_identification')].documentId	No			Seller's item code
P_8B	$.quantity	No			Quantity
P_9A	$.itemPrice	No			Unit net price
P_11	$.amountExcludingVat	No			Line net amount
P_12	tax > percentage JSONPath $.tax.percentage	No			Supply outside the scope of Polish VAT. Which of the two
KursWaluty		No	-	!empty(row['_root'].find('$.document.invoice.accountingCurrencyExchangeRate')) and row['_root'].find('$.document.invoice.documentCurrencyCode')[0] != 'PLN'	Exchange rate supplied by the sender, never derived. Computed: row['_root'].find('$.document.invoice.accountingCurrencyExchangeRate')[0]