Skip to main content

Convert Polish KSeF invoices to Peppol UBL

The Transfer API converts a Polish KSeF invoice to a Peppol UBL document. You send the invoice in KSeF FA(3), the XML format defined by the Polish Ministry of Finance, and the response is the same invoice in Peppol UBL: UBL 2.1 following Peppol BIS Billing 3.0. KSeF (Krajowy System e-Faktur) is the Polish e-invoicing system.

Use it to import into your ERP, as Peppol UBL, the invoices your suppliers issued to your legal entities. The Polish invoicing API collects them from KSeF. Your system does two things:

  1. Download the FA(3) from the Polish invoicing API.
  2. Send it to the Transfer API and read the UBL from the response.

Before you start​

ServiceSandboxProduction
Polish invoicing APIhttps://pl-sandbox.api.acubeapi.comhttps://pl.api.acubeapi.com
Transfer APIhttps://transfer-sandbox.api.acubeapi.comhttps://transfer.api.acubeapi.com

Get the FA(3)​

The conversion needs the FA(3) as KSeF delivered it. Download it from the Polish invoicing API:

GET /invoices/fa87d11a-22c6-11ed-861d-0242ac120002?rawContent=true
Authorization: Bearer <your-token>
Accept: application/xml
  • rawContent=true is required. Without it, the same call returns A-Cube's record of the invoice in XML, not the FA(3).
  • Send Accept: application/xml. With Accept: application/json, the same call returns the FA(3) converted to JSON.

To list the invoices received for your legal entities, see Receive an invoice in the Polish invoicing documentation. The record of each invoice has its uuid and its KSeF number (ksefReferenceNumber).

Convert the FA(3)​

Send the FA(3) in base64, in a JSON body, to the Transfer API:

POST /invoices/convert
Authorization: Bearer <your-token>
Content-Type: application/json
Accept: application/xml

{
"from": "ksef_fa3",
"to": "peppol_ubl",
"content": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPEZha3R1cmEg...",
"metadata": {
"ksef_number": "9999999999-20260215-0123456789AB-CD"
}
}
FieldRequiredValue
fromYesksef_fa3, the format of content.
toYespeppol_ubl, the format of the response.
contentYesThe FA(3) as you downloaded it, in standard base64 (RFC 4648) with padding and without line breaks or spaces. Decoded, it must be well-formed XML encoded in UTF-8.
metadata.ksef_numberNoThe ksefReferenceNumber of the invoice. The FA(3) does not contain its own KSeF number: the conversion writes this value in the UBL. It is copied as it is, without format checks.

metadata carries data of the document that is not in content. ksef_number is the only key accepted with from=ksef_fa3. Any other key returns 422.

RequestRule
Content-Typeapplication/json. Any other type returns 415.
AcceptMust allow application/xml, for example application/xml or */*. Otherwise the response is 406.
BodyA JSON object with the fields above, up to 5 MiB: about 3.7 MiB of FA(3) before base64.

The conversion is synchronous. Nothing is stored and nothing is sent: the response is the only result, so you can repeat the call.

Response​

On success the response is 200 with the UBL document, Content-Type: application/xml.

The root element and the type code depend on the FA(3) type: see Document types. How the conversion fills the UBL, and when it refuses an invoice, is described in Conversion rules.

Errors​

Errors are application/problem+json, as in the rest of the Transfer API. Each status and when it occurs is in the API reference: Convert an invoice.

A 422 means the conversion refused the request or the invoice. The reasons are in violations: see Violations.

Violations​

A 422 looks like this:

{
"type": "/errors/conversion_rejected",
"title": "Conversion rejected",
"status": 422,
"detail": "The invoice was not converted: `violations` holds the reasons. Nothing was stored.",
"violations": [
{
"code": "PAYABLE_TOTAL_MISMATCH",
"field": "Fa/P_15",
"value": "1.01",
"message": "The invoice total (P_15) is 54.64 and net plus VAT is 53.63: the gap is over 1.00",
"context": {"invoice_total": "54.64", "net_plus_vat": "53.63"},
"occurred_at": null
}
]
}

The fields of a violation are those described in The violation object. Here field is the path of the FA(3) element, occurred_at is null, and the message is in English.

Four codes concern the request:

CodefieldWhen
CONVERSION_NOT_SUPPORTEDfrom or tofrom or to is missing or has a value other than ksef_fa3 and peppol_ubl.
METADATA_KEY_NOT_ACCEPTEDmetadata.<key>A metadata key other than ksef_number.
CONTENT_NOT_BASE64contentcontent is not standard base64 with padding, or it has line breaks or spaces. value is null.
CONTENT_NOT_WELL_FORMEDcontentcontent is missing or empty, or decoded it is not well-formed XML encoded in UTF-8. value is null.

Every other code concerns the content of the invoice. See Violation codes.

When an invoice cannot be converted​

A 422 for the content of the invoice does not go away on retry: sending the same FA(3) again gives the same answer. Keep the violations and register the invoice in your ERP in another way.

For a 500 or 503, send the same request again later.

Conversion rules​

Peppol and KSeF do not describe an invoice in the same way. The conversion keeps the amounts KSeF accepted. When the FA(3) does not fit a Peppol rule, the conversion either adds an adjustment that the UBL can carry, or it refuses the invoice with a 422.

FA(3) terms​

FA(3) elements have Polish names. This page uses these:

FA(3) elementMeaning
RodzajFakturyThe invoice type, for example VAT or KOR.
FaWierszAn invoice line.
P_8A, P_8BUnit of measure and quantity of a line.
P_9ANet unit price of a line.
P_11, P_11ANet and gross amount of a line.
P_12VAT rate of a line, for example 23 or zw (exempt).
P_13_xNet total of one VAT box of the invoice. Each box is a rate or a VAT treatment, for example P_13_1 for 23% and 22%.
P_14_xVAT of the box P_13_x. P_14_xW is the same VAT in PLN, for invoices in another currency.
P_15Total amount of the invoice.
Podmiot1, Podmiot2Seller and buyer.
NIPThe Polish tax ID.

Document types​

RodzajFakturyUBL document
VAT, invoiceInvoice, type code 380.
ZAL, advance invoiceInvoice, type code 386.
ROZ, final invoice after advancesInvoice, type code 380.
KOR, correctionCreditNote, type code 381.
KOR_ZAL, correction of an advance invoiceCreditNote, type code 381.
UPR, simplified invoiceNot converted: DOCUMENT_TYPE_NOT_SUPPORTED.
KOR_ROZ, correction of a final invoiceNot converted: DOCUMENT_TYPE_NOT_SUPPORTED.

The conversion reads FA(3) only. A FA(2) invoice gets INPUT_FORMAT_VERSION_NOT_SUPPORTED.

A CreditNote has cac:CreditNoteLine lines with cbc:CreditedQuantity, and its due date is in cac:PaymentMeans/cbc:PaymentDueDate. The rest of the document has the same structure as an Invoice.

VAT​

Each P_13_x becomes a cac:TaxSubtotal with the amounts of the FA(3) header.

FA(3) boxVAT categoryExemption reason
P_13_1, 23% and 22%S
P_13_2, 8% and 7%S
P_13_3, 5%S
P_13_4, flat rate for taxi drivers, 4% and 3%S
P_13_6_1, domestic 0%Z
P_13_6_2, intra-community supply at 0%KVATEX-EU-IC
P_13_6_3, export at 0%GVATEX-EU-G
P_13_7, exemptEThe text of the legal basis, see below.
P_13_9, P_13_10, reverse charge and supplies not taxed in Poland (np II)AEVATEX-EU-AE
P_13_11, margin schemeEVATEX-EU-F, -I or -J, see below.
P_13_5, OSSNot converted: OSS_NOT_SUPPORTED.
P_13_8, supplies outside Poland (np I)Not converted: SUPPLY_OUTSIDE_COUNTRY_NOT_SUPPORTED.
  • Some invoicing programs fill every P_13_x, with zero when the invoice has no line at that rate. A box at zero, with zero VAT and no line with an amount at that rate, counts as missing. It gets no TaxSubtotal. A P_13_5 or P_13_8 at zero does not cause a refusal.
  • A box can hold two rates, such as 23% and 22% in P_13_1. The rate comes from P_12 of the lines. If the lines have both rates, the UBL has two subtotals. The second rate gets the sum of its lines and the VAT computed on that sum. The first rate keeps the rest of the FA(3) amounts.
  • For an exempt supply, the reason is the text of P_19A, P_19B or P_19C, the legal basis of the exemption. KSeF also accepts an exempt total with the flag P_19N instead of a legal basis. The reason is then the text Zwolnienie z VAT.
  • For the margin scheme, the margin flag of the FA(3) (PMarzy) picks VATEX-EU-F (second-hand goods), VATEX-EU-I (works of art) or VATEX-EU-J (collector's items and antiques). Without a flag the code is VATEX-EU-F. Travel agents have no VATEX code: their reason is the text procedura marży dla biur podróży.
  • Peppol accepts one subtotal for each VAT category and rate. P_13_9 with P_13_10, or P_13_7 with P_13_11, gets VAT_COMBINATION_NOT_SUPPORTED.
  • In an invoice in another currency, the amounts stay in the invoice currency. cbc:TaxCurrencyCode is PLN, and a second cac:TaxTotal holds the sum of the P_14_xW. It is there only if that sum is not zero. The exchange rate is not carried.

Rate totals and lines​

The FA(3) gives the net total of each rate in the header, and each line is rounded on its own. The two can differ by a few cents, while Peppol requires the subtotal to match the lines.

  • For each VAT category and rate, the conversion compares the TaxSubtotal with the sum of the lines as written in the UBL.
  • A gap becomes a document cac:AllowanceCharge with the VAT category and rate of that total. It is a charge when the total is over the sum of the lines, and an allowance when it is under.
  • cbc:LineExtensionAmount is the sum of the lines. cbc:TaxExclusiveAmount stays the sum of the P_13_x.
  • Up to 0.02 for each line of that rate, the reason is Zaokrąglenie (rounding). This is the tolerance Peppol gives a line.
  • Over that tolerance the invoice is still converted, because KSeF accepted it. The reason is Różnica między sumą wierszy a wartością netto (difference between the sum of the lines and the net value).
  • For a box split between two rates, the tolerance counts the lines of both rates.
  • A total with no lines at its rate gets VAT_RATE_TOTAL_MISMATCH. So do lines with no total at their rate, and a box split between two rates, when the gap is over the tolerance.

Totals and payment​

  • cbc:TaxInclusiveAmount is the sum of the P_13_x and the P_14_x. The difference with P_15 goes to cbc:PayableRoundingAmount, up to 1.00. Over 1.00 the invoice gets PAYABLE_TOTAL_MISMATCH.
  • An invoice already paid (Zaplacono = 1, or ZnacznikZaplatyCzesciowej = 2) has the whole total in cbc:PrepaidAmount and a cbc:PayableAmount of 0.
  • With partial payments (ZnacznikZaplatyCzesciowej = 1), the amount to pay is the amount due of the FA(3) settlement (Rozliczenie/DoZaplaty, or P_15 if it is missing) minus the payments. If the payments exceed the total, the amount to pay is negative.
  • cbc:PrepaidAmount is P_15 minus the amount to pay. It is negative when the settlement adds a charge, for example a deposit.
  • cbc:DueDate comes from the payment term date (Termin). A term written in words (TerminOpis) is not carried.
  • The sums are rounded to two decimals at the end. They are exact up to 999,999,999,999.99.

The payment form (FormaPlatnosci) becomes cbc:PaymentMeansCode:

FormaPlatnosciPayment formPaymentMeansCode
1Cash10
2Card48
3Voucher1
4Cheque20
5Credit1
6Bank transfer30
7Mobile payment68

A bank transfer without a bank account has no cac:PaymentMeans.

Lines​

  • Only the lines with an amount (P_11 or P_11A) are converted. The cbc:ID of a line is its position.
  • A line without a quantity has quantity 1. If the unit price is missing too, the price is the amount divided by the quantity.
  • The price is always positive, and the sign goes on the quantity. The sign comes from the unit price if the FA(3) has one, otherwise from the amount.
  • If quantity times price is more than 0.02 away from the amount, the difference becomes an allowance (Rabat, discount) or a charge (Dopłata, surcharge) of the line.
  • For a line with only the gross amount and a rate, the net is gross × 100 / (100 + rate).
  • The unit of measure (P_8A) is converted with a fixed table, for example szt to H87 (piece) and kg to KGM. A unit already written as a UN/ECE code of that table, or as EA, stays as it is. Any other value becomes C62 (one).

Corrections​

This applies to KOR and KOR_ZAL.

  • The CreditNote has the amounts of the FA(3) with the opposite sign. A correction that lowers the invoice by 200 is a CreditNote of 200. A correction that raises it is a CreditNote with negative amounts.
  • A FA(3) correction can list each line twice: before the correction (StanPrzed = 1) and after it. The line before counts with the opposite sign of the other lines, so the pair gives the difference. Some issuers write those lines already negative. When the lines read as written are closer to the sum of the P_13_x, the conversion reads them as written.
  • cbc:Note is the reason for the correction (PrzyczynaKorekty).
  • Each corrected invoice (DaneFaKorygowanej) becomes a cac:BillingReference with its number and date. Its KSeF number goes to a cac:AdditionalDocumentReference with the description KSeF number of corrected invoice, after the one with the KSeF number of the correction itself.
  • A CreditNote has no cbc:DueDate. The payment term goes to cac:PaymentMeans/cbc:PaymentDueDate, so it is there only with a payment form.
  • A correction with P_13_x and no line with an amount, for example a discount on the turnover of a period, gets one line for each P_13_x. Each line has quantity 1, or -1 when the credited amount is negative, unit C62, the reason for the correction as its name (Korekta if it is missing), and the VAT category and rate of that total.
  • A correction with no P_13_x changes only data, for example the name of the buyer. There is nothing to credit: it gets CORRECTION_WITHOUT_AMOUNTS.

Advance and final invoices​

  • A ZAL (advance invoice) becomes an Invoice with type code 386. Its P_13_x are the advance received. If it has no line with an amount, it gets one line for each P_13_x, as a correction without lines does, with the name Zaliczka (advance).
  • A ROZ (final invoice) becomes an Invoice with type code 380. Its lines are the whole supply, and its P_13_x are what is left after the advances. For each rate the difference is a document allowance with the reason Otrzymane zaliczki (advances received).
  • Each advance invoice of a ROZ (FakturaZaliczkowa) becomes a cac:BillingReference with the number of the advance invoice, or its KSeF number when the FA(3) has only that.
  • A KOR_ZAL becomes a CreditNote and follows the rules of corrections.

Header and parties​

  • The KSeF number of the invoice comes from metadata.ksef_number of the request. It goes to a cac:AdditionalDocumentReference with the description KSeF number. Without it, the element is not there.
  • cbc:EndpointID of seller and buyer is PL followed by the NIP, with schemeID="9945". The same value is in cac:PartyTaxScheme/cbc:CompanyID. A buyer without a Polish NIP gets INPUT_FIELD_MISSING.
  • cbc:BuyerReference is the customer number of the buyer (NrKlienta). Peppol requires a buyer reference or an order number: if the FA(3) has neither, it is the invoice number.
  • Postal code and city come from the second address line when it has the form 00-000 City. In any other case the line stays as it is.
  • A VAT invoice has no header cbc:Note.

FA(3) data not carried​

  • Third parties (Podmiot3), additional descriptions (DodatkowyOpis), attachments (Zalacznik), the place of issue (P_1M), and the REGON and BDO registration numbers.
  • The exchange rate (KursWaluty), the name of the bank, and the dates of the payments.
  • On the lines: the GTU and CN codes and the delivery date of the line (P_6A).
  • On a correction: the delivery note (WZ).
  • On a ZAL: the order (Zamowienie) and the partial advances (ZaliczkaCzesciowa).

The UBL has no cbc:AccountingCost, no cac:DeliveryLocation and no cac:AdditionalItemProperty, and it has no PDF attachment.

Violation codes​

A 422 for the content of the invoice has one violation for each reason. field is the path of the FA(3) element, or null when no single element is wrong. The object is described in Violations.

CodefieldWhen
INPUT_FORMAT_INVALIDnullThe document is not a FA(3) invoice, or it violates the FA(3) XML schema, for example with an amount that is not a number, a date that does not exist or a missing Podmiot2. For a schema error, the message quotes the first error, and context has its line and the count of errors.
INPUT_FORMAT_VERSION_NOT_SUPPORTEDNaglowek/WariantFormularzaThe document is a FA(2) invoice.
DOCUMENT_TYPE_NOT_SUPPORTEDFa/RodzajFakturyThe type is UPR or KOR_ROZ.
INPUT_FIELD_MISSINGThe missing elementThe buyer has no Polish NIP, needed for the Peppol endpoint 9945:PL<NIP>. Or a VAT, ZAL or ROZ invoice has no P_13_x. Or a VAT or ROZ invoice has no line with an amount.
INPUT_VALUE_NOT_ALLOWEDFa/FaWiersz/P_12A line has the rate np I, which has no VAT category. context.row is the line.
OSS_NOT_SUPPORTEDFa/P_13_5OSS invoice.
SUPPLY_OUTSIDE_COUNTRY_NOT_SUPPORTEDFa/P_13_8Supply outside Poland (np I).
VAT_COMBINATION_NOT_SUPPORTEDFa/P_13_10 or Fa/P_13_11P_13_9 with P_13_10, or P_13_7 with P_13_11.
CORRECTION_WITHOUT_AMOUNTSFa/RodzajFakturyA KOR or KOR_ZAL with no P_13_x.
VAT_RATE_TOTAL_MISMATCHnullA rate has a total and no lines. Or the gap is over the tolerance, and the rate has lines and no total, or shares its box with a second rate. value is the gap. context has category, percent, lines, lines_total and rate_total.
PAYABLE_TOTAL_MISMATCHFa/P_15P_15 is more than 1.00 away from net plus VAT. value is the gap. context has invoice_total and net_plus_vat.

Sending the same FA(3) again gives the same violations. See When an invoice cannot be converted.

Known limits​

  • Some invoices that Peppol could represent are refused: OSS, a buyer without a Polish NIP, the rate np I, and P_13_9 with P_13_10.
  • UPR and KOR_ROZ are not converted.
  • An invoice with the payment term written in words, or with no term, has neither cbc:DueDate nor cac:PaymentTerms. Validators that apply the EN 16931 rule BR-CO-25 reject such a UBL when it has an amount to pay.
  • A UN/ECE unit code outside the table becomes C62.
  • A ROZ with no line with an amount gets a 422. So does a ROZ with lines at a rate whose P_13_x is left out because the advances covered it in full. With that P_13_x at zero, it is converted.
  • A ZAL not marked as paid has the advance as the amount to pay.
  • A ZAL at 7% or 22% gets 8% or 23%. The rate comes from the lines, and a ZAL has its rates on the order lines.

Example​

A correction (KOR) that lowers the price of a refrigerator by 200 PLN gross becomes this CreditNote. The parties and some elements are left out. The data comes from the FA(3) examples of the Polish Ministry of Finance, and the KSeF numbers are test values.

<CreditNote xmlns="urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2"
xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">
<cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0</cbc:CustomizationID>
<cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID>
<cbc:ID>FK2026/03/200</cbc:ID>
<cbc:IssueDate>2026-03-15</cbc:IssueDate>
<cbc:CreditNoteTypeCode>381</cbc:CreditNoteTypeCode>
<cbc:Note>obniżka ceny o 200 zł z uwagi na uszkodzenia estetyczne</cbc:Note>
<cbc:DocumentCurrencyCode>PLN</cbc:DocumentCurrencyCode>
<cbc:BuyerReference>fdfd778343</cbc:BuyerReference>
<cac:BillingReference>
<cac:InvoiceDocumentReference>
<cbc:ID>FV2026/02/150</cbc:ID>
<cbc:IssueDate>2026-02-15</cbc:IssueDate>
</cac:InvoiceDocumentReference>
</cac:BillingReference>
<cac:AdditionalDocumentReference>
<cbc:ID>9999999999-20260215-0123456789AB-CD</cbc:ID>
<cbc:DocumentDescription>KSeF number</cbc:DocumentDescription>
</cac:AdditionalDocumentReference>
<cac:AdditionalDocumentReference>
<cbc:ID>9999999999-20230908-8BEF280C8D35-4D</cbc:ID>
<cbc:DocumentDescription>KSeF number of corrected invoice</cbc:DocumentDescription>
</cac:AdditionalDocumentReference>
<cac:AccountingSupplierParty>
<cac:Party>
<cbc:EndpointID schemeID="9945">PL9999999999</cbc:EndpointID>
<!-- ... -->
</cac:Party>
</cac:AccountingSupplierParty>
<cac:AccountingCustomerParty>
<cac:Party>
<cbc:EndpointID schemeID="9945">PL1111111111</cbc:EndpointID>
<!-- ... -->
</cac:Party>
</cac:AccountingCustomerParty>
<cac:TaxTotal>
<cbc:TaxAmount currencyID="PLN">37.40</cbc:TaxAmount>
<cac:TaxSubtotal>
<cbc:TaxableAmount currencyID="PLN">162.60</cbc:TaxableAmount>
<cbc:TaxAmount currencyID="PLN">37.40</cbc:TaxAmount>
<cac:TaxCategory>
<cbc:ID>S</cbc:ID>
<cbc:Percent>23</cbc:Percent>
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>
</cac:TaxScheme>
</cac:TaxCategory>
</cac:TaxSubtotal>
</cac:TaxTotal>
<cac:LegalMonetaryTotal>
<cbc:LineExtensionAmount currencyID="PLN">162.60</cbc:LineExtensionAmount>
<cbc:TaxExclusiveAmount currencyID="PLN">162.60</cbc:TaxExclusiveAmount>
<cbc:TaxInclusiveAmount currencyID="PLN">200.00</cbc:TaxInclusiveAmount>
<cbc:PayableAmount currencyID="PLN">200.00</cbc:PayableAmount>
</cac:LegalMonetaryTotal>
<cac:CreditNoteLine>
<cbc:ID>1</cbc:ID>
<cbc:CreditedQuantity unitCode="H87">1</cbc:CreditedQuantity>
<cbc:LineExtensionAmount currencyID="PLN">162.60</cbc:LineExtensionAmount>
<cac:Item>
<cbc:Name>lodówka Zimnotech mk1</cbc:Name>
<cac:ClassifiedTaxCategory>
<cbc:ID>S</cbc:ID>
<cbc:Percent>23</cbc:Percent>
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>
</cac:TaxScheme>
</cac:ClassifiedTaxCategory>
</cac:Item>
<cac:Price>
<cbc:PriceAmount currencyID="PLN">162.6</cbc:PriceAmount>
</cac:Price>
</cac:CreditNoteLine>
</CreditNote>

The FA(3) lowers the invoice by 200, so the CreditNote credits 200 with positive amounts. The original invoice is in cac:BillingReference, and its KSeF number in the second cac:AdditionalDocumentReference.