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

Fields below `Faktura/Fa`* required
FA(3) Field	UBL JSON
	document > invoice > invoiceNumber

	document > invoice > issueDate

	document > invoice > documentCurrencyCode

	document > documentType

	Only when: The document references the invoice it corrects

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

Fields below `Faktura/Fa`
FA(3) Field	UBL JSON
	document > invoice > references[?(@.documentType == 'billing')]Only when: The document references the invoice it corrects

Fa.DaneFaKorygowanej

DaneFaKorygowanej = Data of the corrected invoice

FA(3) Field	UBL JSON
	$.issueDate

	$.documentId

	Only when: The reference carries a KSeF identifier instead of a seller number

	$.documentIdOnly when: The reference carries a KSeF identifier instead of a seller number

	Only when: NOT: The reference carries a KSeF identifier instead of a seller number

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

Fields below `Faktura/Podmiot1`
FA(3) Field	UBL JSON
	document > invoice > accountingSupplierParty > publicIdentifiers[?search(@.scheme, 'VAT')] > id

	document > invoice > accountingSupplierParty > party > companyName

	document > invoice > accountingSupplierParty > party > address > country

	document > invoice > accountingSupplierParty > party > address > street1

	document > invoice > accountingSupplierParty > party > address > zip

Buyer

Podmiot2 = Subject/entity 2 (buyer)

JST = Local government unit flag

GV = VAT group flag

Fields below `Faktura/Podmiot2`* required
FA(3) Field	UBL JSON
	document > invoice > accountingCustomerParty > party > companyName

	document > invoice > accountingCustomerParty > publicIdentifiers[?search(@.scheme, 'VAT\|IVA')] > idOnly when: Buyer is Polish or country not specified

	document > invoice > accountingCustomerParty > party > address > countryOnly when: Buyer is established in another EU member state

	document > invoice > accountingCustomerParty > publicIdentifiers[?search(@.scheme, 'VAT\|IVA')] > idOnly when: Buyer is established in another EU member state

	document > invoice > accountingCustomerParty > party > address > countryOnly when: Buyer outside the EU, identified by KodKraju and NrID

	document > invoice > accountingCustomerParty > publicIdentifiers[?search(@.scheme, 'VAT\|IVA')] > idOnly when: Buyer outside the EU, identified by KodKraju and NrID

	document > invoice > accountingCustomerParty > party > address > country

	document > invoice > accountingCustomerParty > party > address > street1

	document > invoice > accountingCustomerParty > party > address > zip

Tax Totals

Fields below `Faktura/Fa`
FA(3) Field	UBL JSON
	document > invoice > taxSubtotals[?(@.percentage == 23)] > taxableAmount

	document > invoice > taxSubtotals[?(@.percentage == 23)] > taxAmount

	document > invoice > taxSubtotals[?(@.percentage == 8)] > taxableAmount

	document > invoice > taxSubtotals[?(@.percentage == 8)] > taxAmount

	document > invoice > taxSubtotals[?(@.percentage == 5)] > taxableAmount

	document > invoice > taxSubtotals[?(@.percentage == 5)] > taxAmount

	document > invoice > taxSubtotals[?(@.category == 'intra_community')] > taxableAmount

	document > invoice > taxSubtotals[?(@.category == 'zero_rated')] > taxableAmount

	document > invoice > taxSubtotals[?(@.category == 'export')] > taxableAmount

	document > invoice > taxSubtotals[?(@.category == 'exempt')] > taxableAmount

	document > invoice > taxSubtotals[?(@.category == 'outside_scope')] > taxableAmountOnly when: Out-of-scope supply reported as "np I"

	document > invoice > taxSubtotals[?(@.category == 'outside_scope')] > taxableAmountOnly when: Out-of-scope supply reported as "np II" (article 100(1)(4) services)

	document > invoice > taxSubtotals[?(@.category == 'reverse_charge')] > taxableAmount

	document > invoice > taxSubtotals[?(@.percentage == 23)] > taxAmountPLNOnly when: jsonpath(row, '$.document.invoice.documentCurrencyCode') != 'PLN'

	document > invoice > taxSubtotals[?(@.percentage == 8)] > taxAmountPLNOnly when: jsonpath(row, '$.document.invoice.documentCurrencyCode') != 'PLN'

	document > invoice > taxSubtotals[?(@.percentage == 5)] > taxAmountPLNOnly when: jsonpath(row, '$.document.invoice.documentCurrencyCode') != 'PLN'

Total Amount

Fields below `Faktura/Fa`* required
FA(3) Field	UBL JSON
	document > invoice > amountIncludingVat

Annotations

Adnotacje = Annotations

Zwolnienie = VAT exemption

NoweSrodkiTransportu = New means of transport

PMarzy = Margin scheme (procedura marzy)

Fields below `Faktura/Fa/Adnotacje`* required
FA(3) Field	UBL JSON




	Only when: !empty(jsonpath(row, "$.document.invoice.taxSubtotals[?(@.category == 'reverse_charge')]")); Buyer is Polish or country not specified



	Only when: The invoice carries VAT-exempt lines

	document > invoice > taxSubtotals[?(@.category == 'exempt')] > taxExemptionReasonOnly when: hasExemptSale() and !isDirectiveExemption() and !isOtherExemption()

	document > invoice > taxSubtotals[?(@.category == 'exempt')] > taxExemptionReasonOnly when: hasExemptSale() and isDirectiveExemption()

	document > invoice > taxSubtotals[?(@.category == 'exempt')] > taxExemptionReasonOnly when: hasExemptSale() and isOtherExemption()

	Only when: NOT: The invoice carries VAT-exempt lines

Delivery notes and additional notes

Fields below `Faktura/Fa`
FA(3) Field	UBL JSON

Transaction conditions

WarunkiTransakcji = Transaction conditions

Umowy = Contracts

Zamowienia = Orders

NrPartiiTowaru = Goods batch numbers

Fields below `Faktura/Fa`
FA(3) Field	UBL JSON
	document > invoice > references[?(@.documentType == 'contract')]Only when: !empty(jsonpath(row, "$.document.invoice.references[?(@.documentType == 'contract')]"))

	document > invoice > references[?(@.documentType == 'purchase_order')]Only when: !empty(jsonpath(row, "$.document.invoice..references[?(@.documentType == 'purchase_order')]"))

	Only when: !empty(jsonpath(row, "$.document.invoice..references[?(@.documentType == 'line_document_reference')]"))

	document > invoice > notes[*]Only when: !empty(jsonpath(row, '$.document.invoice.notes'))

	Only when: empty(jsonpath(row, '$.document.invoice.notes')) and !empty(jsonpath(row, '$.document.invoice.note'))

	document > invoice > noteOnly when: empty(jsonpath(row, '$.document.invoice.notes'))

Fa.WarunkiTransakcji.Umowy

Umowy = Contracts

FA(3) Field	UBL JSON
	$.documentId

	$.issueDate

Fa.WarunkiTransakcji.Zamowienia

Zamowienia = Orders

FA(3) Field	UBL JSON
	$.documentId

	$.issueDate

Fa.DodatkowyOpis

FA(3) Field	UBL JSON


	$

Payment

Fields below `Faktura/Fa/Platnosc`* required
FA(3) Field	UBL JSON
	document > invoice > dueDate

	document > invoice > paymentMeansArray[?(@.code == 'credit_transfer' \|\| @.code == 'sepa_credit_transfer')]Only when: !empty(jsonpath(row, "$.document.invoice.paymentMeansArray[?(@.code == 'credit_transfer' \|\| @.code == 'sepa_credit_transfer')]"))

	document > invoice > paymentMeansIbanOnly when: !hasPaymentMeans()

	document > invoice > paymentMeansBicOnly when: !hasPaymentMeans() and !empty(jsonpath(row, '$.document.invoice.paymentMeansIban'))

	Only when: knownPaymentMethod()

	Only when: !knownPaymentMethod() and (hasPaymentMeans() or !empty(jsonpath(row, '$.document.invoice.paymentMeansCode')))

	Only when: !knownPaymentMethod() and (hasPaymentMeans() or !empty(jsonpath(row, '$.document.invoice.paymentMeansCode')))

	Only when: !empty(jsonpath(row, '$.document.invoice.prepaidAmount')) or hasDatedPayment()

	document > invoice > prepaidPayments[0] > dateOnly when: hasDatedPayment() and paidInFull()

	Only when: hasDatedPayment() and !paidInFull()

	document > invoice > prepaidPayments[0] > amountOnly when: hasDatedPayment() and !paidInFull()

	document > invoice > prepaidPayments[0] > dateOnly when: hasDatedPayment() and !paidInFull()

Fa.Platnosc.RachunekBankowy

FA(3) Field	UBL JSON
	$.account

	$.branche_codeOnly when: jsonpath(row, '$.branche_code') matches '/^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$/'

	$.holder

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

Fields below `Faktura/Fa`
FA(3) Field	UBL JSON
	document > invoice > invoiceLines[*]

Fa.FaWiersz

FaWiersz = Faktura wiersz = invoice line

FA(3) Field	UBL JSON
	_index

	$.name

	references[?(@.documentType == 'line_sellers_item_identification')] > documentId

	$.quantity

	$.itemPrice

	$.amountExcludingVat

	tax > percentage

	Only when: !empty(row['_root'].find('$.document.invoice.accountingCurrencyExchangeRate')) and row['_root'].find('$.document.invoice.documentCurrencyCode')[0] != 'PLN'

Invoice Header​

Correction Invoice​

Fa.DaneFaKorygowanej​

Seller​

Buyer​

Tax Totals​

Total Amount​

Annotations​

Delivery notes and additional notes​

Transaction conditions​

Fa.WarunkiTransakcji.Umowy​

Fa.WarunkiTransakcji.Zamowienia​

Fa.DodatkowyOpis​

Payment​

Fa.Platnosc.RachunekBankowy​

Invoice Lines​

Fa.FaWiersz​

Invoice Header

Correction Invoice

Fa.DaneFaKorygowanej

Seller

Buyer

Tax Totals

Total Amount

Annotations

Delivery notes and additional notes

Transaction conditions

Fa.WarunkiTransakcji.Umowy

Fa.WarunkiTransakcji.Zamowienia

Fa.DodatkowyOpis

Payment

Fa.Platnosc.RachunekBankowy

Invoice Lines

Fa.FaWiersz