UBL XML to KSeF FA(3) Mapping Reference
This document describes how UBL XML (Universal Business Language) invoice fields 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 XML |
|---|---|
| cbc:ID | |
| |
| cbc:IssueDate | |
| |
| cbc:DocumentCurrencyCode | |
| |
| cbc:InvoiceTypeCode | |
| |
| Delivery > ActualDeliveryDate | |
| |
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
GLN = Global Location Number
| FA(3) Field | UBL XML |
|---|---|
| AccountingSupplierParty > Party > PartyTaxScheme > CompanyID | |
| |
| AccountingSupplierParty > Party > PartyLegalEntity > RegistrationName | |
| |
| AccountingSupplierParty > Party > PostalAddress > Country > IdentificationCode | |
| |
| AccountingSupplierParty > Party > PostalAddress > StreetName | |
| |
| AccountingSupplierParty > Party > PostalAddress > PostalZone, AccountingSupplierParty > Party > PostalAddress > CityName | |
| |
| AccountingSupplierParty > Party > PartyIdentification[ID > @schemeID='0088'] > ID | |
| |
Buyer
Podmiot2 = Subject/entity 2 (buyer)
IDNabywcy = Buyer ID
KodUE = EU country code
NrVatUE = EU VAT number
BrakID = No ID flag
NrKlienta = Customer number
gV = VAT group flag
jST = Local government unit flag
DaneKontaktowe = Contact details
| FA(3) Field | UBL XML |
|---|---|
| AccountingCustomerParty > Party > PartyLegalEntity > RegistrationName | |
| |
| AccountingCustomerParty > Party > PostalAddress > Country > IdentificationCode | |
| |
| AccountingCustomerParty > Party > PostalAddress > StreetName | |
| |
| AccountingCustomerParty > Party > PostalAddress > PostalZone, AccountingCustomerParty > Party > PostalAddress > CityName | |
| |
| AccountingCustomerParty > Party > PartyIdentification[ID > @schemeID='0088'] > ID | |
| |
| AccountingCustomerParty > Party > PartyTaxScheme > CompanyIDOnly when: Buyer is Polish or country not specified | |
| |
| AccountingCustomerParty > Party > PartyTaxScheme > CompanyIDOnly when: Buyer is Polish or country not specified | |
| |
| AccountingCustomerParty > Party > PostalAddress > Country > IdentificationCodeOnly when: Buyer is not Polish; Buyer has a VAT ID | |
| |
| AccountingCustomerParty > Party > PartyTaxScheme > CompanyIDOnly when: Buyer is not Polish; Buyer has a VAT ID | |
| |
| Only when: Buyer is not Polish; NOT: Buyer has a VAT ID | |
| |
| AccountingCustomerParty > SupplierAssignedAccountID | |
| |
| UBLExtensions > UBLExtension > ExtensionContent > PageroExtension > RestrictedInformationParty[Key='GV-recipient'] > Key | |
| |
| UBLExtensions > UBLExtension > ExtensionContent > PageroExtension > RestrictedInformationParty[Key='JST-recipient'] > Key | |
| |
| AccountingCustomerParty > AccountingContact > Telephone | |
| |
| AccountingCustomerParty > AccountingContact > ElectronicMail | |
| |
Third Party
Podmiot3 = Subject/entity 3 (third party)
RolaInna = Other role flag
OpisRoli = Role description
| FA(3) Field | UBL XML |
|---|---|
| UBLExtensions > UBLExtension > ExtensionContent > PageroExtension > RestrictedInformationParty[Key='otherEntity'] > Party > PartyTaxScheme > CompanyID | |
| |
| UBLExtensions > UBLExtension > ExtensionContent > PageroExtension > RestrictedInformationParty[Key='otherEntity'] > Party > PartyLegalEntity > RegistrationName | |
| |
| UBLExtensions > UBLExtension > ExtensionContent > PageroExtension > RestrictedInformationParty[Key='otherEntity'] > Party > PostalAddress > Country > IdentificationCode | |
| |
| UBLExtensions > UBLExtension > ExtensionContent > PageroExtension > RestrictedInformationParty[Key='otherEntity'] > Party > PostalAddress > StreetName | |
| |
| UBLExtensions > UBLExtension > ExtensionContent > PageroExtension > RestrictedInformationParty[Key='otherEntity'] > Description | |
| |
| UBLExtensions > UBLExtension > ExtensionContent > PageroExtension > RestrictedInformationParty[Key='otherEntity'] > Description | |
| |
Correction Invoice
KOR = Faktura Korygujaca = correction invoice
PrzyczynaKorekty = Reason for correction
TypKorekty = Correction type
DaneFaKorygowanej = Data of the corrected invoice
DataWystFaKorygowanej = Issue date of the corrected invoice
NrFaKorygowanej = Number of the corrected invoice
| FA(3) Field | UBL XML |
|---|---|
| BillingReference > InvoiceDocumentReference > UBLExtensions > UBLExtension > ExtensionContent > PageroExtension > BillingReferenceExtension > Note | |
| |
| BillingReference > InvoiceDocumentReference > UBLExtensions > UBLExtension > ExtensionContent > PageroExtension > BillingReferenceExtension > RestrictedInformation[Key='correctionType'] > Value | |
| |
| BillingReference > InvoiceDocumentReferenceOnly when: Invoice references a corrected invoice | |
| |
Fa.DaneFaKorygowanej
DaneFaKorygowanej = Data of the corrected invoice
| FA(3) Field | UBL XML |
|---|---|
| cbc:IssueDate | |
| |
| cbc:ID | |
| |
| UBLExtensions > UBLExtension > ExtensionContent > PageroExtension > BillingReferenceExtension > ClearanceIDOnly when: Original invoice was registered in KSeF | |
| |
| UBLExtensions > UBLExtension > ExtensionContent > PageroExtension > BillingReferenceExtension > ClearanceIDOnly when: Original invoice was registered in KSeF | |
| |
| cbc:IDOnly when: NOT: Original invoice was registered in KSeF | |
| |
Tax Totals
| FA(3) Field | UBL XML |
|---|---|
| TaxTotal > TaxSubtotal[number(TaxCategory > Percent)=23] > TaxableAmount | |
| |
| TaxTotal > TaxSubtotal[number(TaxCategory > Percent)=23] > TaxAmount | |
| |
| TaxTotal > TaxSubtotal[number(TaxCategory > Percent)=23] > UBLExtensions > UBLExtension > ExtensionContent > PageroExtension > TaxSubtotalExtension > TaxCurrencyTaxAmount | |
| |
| TaxTotal > TaxSubtotal[number(TaxCategory > Percent)=8] > TaxableAmount | |
| |
| TaxTotal > TaxSubtotal[number(TaxCategory > Percent)=8] > TaxAmount | |
| |
| TaxTotal > TaxSubtotal[number(TaxCategory > Percent)=8] > UBLExtensions > UBLExtension > ExtensionContent > PageroExtension > TaxSubtotalExtension > TaxCurrencyTaxAmount | |
| |
| TaxTotal > TaxSubtotal[number(TaxCategory > Percent)=5] > TaxableAmount | |
| |
| TaxTotal > TaxSubtotal[number(TaxCategory > Percent)=5] > TaxAmount | |
| |
| TaxTotal > TaxSubtotal[number(TaxCategory > Percent)=5] > UBLExtensions > UBLExtension > ExtensionContent > PageroExtension > TaxSubtotalExtension > TaxCurrencyTaxAmount | |
| |
| TaxTotal > TaxSubtotal[TaxCategory > ID='Z' and TaxCategory > Name='0-KR'] > TaxableAmount | |
| |
| TaxTotal > TaxSubtotal[TaxCategory > ID='Z' and TaxCategory > Name='0-WDT'] > TaxableAmount | |
| |
| TaxTotal > TaxSubtotal[TaxCategory > ID='Z' and TaxCategory > Name='0-EX'] > TaxableAmount | |
| |
| TaxTotal > TaxSubtotal[TaxCategory > ID='E' and not(TaxCategory > TaxExemptionReasonCode='VATEX-EU-D' or TaxCategory > TaxExemptionReasonCode='VATEX-FR-F' or TaxCategory > TaxExemptionReasonCode='VATEX-FR-I' or TaxCategory > TaxExemptionReasonCode='VATEX-FR-J')] > TaxableAmount | |
| |
Total Amount
| FA(3) Field | UBL XML |
|---|---|
| LegalMonetaryTotal > PayableAmount | |
| |
Annotations
Adnotacje = Annotations
Zwolnienie = VAT exemption
NoweSrodkiTransportu = New means of transport
PMarzy = Margin scheme (procedura marzy)
P_PMarzyN = Margin scheme not applied
| FA(3) Field | UBL XML |
|---|---|
| UBLExtensions > UBLExtension > ExtensionContent > PageroExtension > RestrictedInformation[Key='checkoutMethod'] > Value | |
| |
| cbc:InvoiceTypeCode[.='389'] | |
| |
| TaxTotal > TaxSubtotal > TaxCategory > ID[.='AE']Only when: Buyer is Polish or country not specified | |
| |
| LegalMonetaryTotal > PayableAmount | |
| |
| Only when: Invoice has VAT-exempt tax (excluding margin scheme) | |
| |
| TaxTotal > TaxSubtotal[TaxCategory > ID='E' and TaxCategory > TaxExemptionReasonCode='P_19A'] > TaxCategory > TaxExemptionReason | |
| |
| TaxTotal > TaxSubtotal[TaxCategory > ID='E' and TaxCategory > TaxExemptionReasonCode='P_19B'] > TaxCategory > TaxExemptionReason | |
| |
| TaxTotal > TaxSubtotal[TaxCategory > ID='E' and TaxCategory > TaxExemptionReasonCode='P_19C'] > TaxCategory > TaxExemptionReason | |
| |
| Only when: NOT: Invoice has VAT-exempt tax (excluding margin scheme) | |
| |
| |
| UBLExtensions > UBLExtension > ExtensionContent > PageroExtension > RestrictedInformation[Key='simplifiedTriangular'] > Value | |
| |
| Only when: Any margin scheme applies | |
| |
| Only when: Margin scheme: travel services | |
| |
| Only when: Margin scheme: second-hand goods | |
| |
| Only when: Margin scheme: artworks | |
| |
| Only when: Margin scheme: collectibles and antiques | |
| |
| Only when: NOT: Any margin scheme applies | |
| |
Payment
Platnosc = Payment
FormaPlatnosci = Payment form
TerminPlatnosci = Payment term
Termin = Due date
RachunekBankowy = Bank account
NrRB = Bank account number (IBAN)
| FA(3) Field | UBL XML |
|---|---|
| PaymentMeans > PaymentMeansCode | |
| |
| cbc:DueDate | |
| |
| PaymentMeans > PayeeFinancialAccount > ID | |
| |
| PaymentMeans > PayeeFinancialAccount > FinancialInstitutionBranch > ID | |
| |
Footer
Stopka = Footer
Rejestry = Registers
KRS = Court register
REGON = Statistical register
BDO = Waste database register
| FA(3) Field | UBL XML |
|---|---|
| AccountingSupplierParty > Party > PartyIdentification[ID > @schemeID='PL:REGON'] > ID | |
| |
| AccountingSupplierParty > Party > PartyIdentification[ID > @schemeID='PL:KRS'] > ID | |
| |
| AccountingSupplierParty > Party > PartyIdentification[ID > @schemeID='PL:BDO'] > ID | |
| |
Invoice Lines
FaWiersz = Faktura wiersz = invoice line
NrWierszaFa = Invoice line number
UU_ID = Universal unique ID
P_7 = Item name
P_8A = Unit of measure
P_8B = Quantity
P_9A = Unit net price
P_11 = Line net amount
P_12 = VAT rate / tag
StanPrzed = Original line flag (correction)
KursWaluty = Exchange rate
| FA(3) Field | UBL XML |
|---|---|
| cac:InvoiceLine | |
| |
Fa.FaWiersz
FaWiersz = Faktura wiersz = invoice line
| FA(3) Field | UBL XML |
|---|---|
| cbc:ID | |
| |
| UBLExtensions > UBLExtension > ExtensionContent > PageroExtension > LineExtension > RestrictedInformation[Key='universalUniqueLineNumber'] > Value | |
| |
| Item > Name | |
| |
| InvoicedQuantity > @unitCode | |
| |
| cbc:InvoicedQuantity | |
| |
| Price > PriceAmount | |
| |
| cbc:LineExtensionAmount | |
| |
| Item > ClassifiedTaxCategory > NameOnly when: NOT: Any margin scheme applies | |
| |
| UBLExtensions > UBLExtension > ExtensionContent > PageroExtension > LineExtension > RestrictedInformation[Key='originalLine'] > Value | |
| |
| > > TaxExchangeRate > CalculationRateOnly when: Invoice currency is not PLN | |
| |