The KSeF export package and _metadata.json
When invoices are exported from KSeF (Poland's national e-invoicing system) through its API, the result is a ZIP archive holding the invoice XML files and one extra file, _metadata.json.
Why the metadata file matters
An FA(3) XML file does not contain its own KSeF number. _metadata.json does: it has an invoices array with one entry per invoice in the package. Since 27 October 2025 the file is always included.
Fields of each entry
| Field | In English | Official description (Polish) |
|---|---|---|
| ksefNumber | KSeF number of the invoice | Numer KSeF faktury. |
| invoiceNumber | Invoice number given by the issuer | Numer faktury nadany przez wystawcę. |
| issueDate | Issue date | Data wystawienia faktury. |
| invoicingDate | Date KSeF accepted the invoice for processing | Data przyjęcia faktury w systemie KSeF (do dalszego przetwarzania). |
| acquisitionDate | Date the KSeF number was assigned | Data nadania numeru KSeF. |
| permanentStorageDate | Date the invoice was permanently stored in KSeF | Data trwałego zapisu faktury w repozytorium systemu KSeF. |
| seller | Seller: nip, name | Dane identyfikujące sprzedawcę. |
| buyer | Buyer: identifier (type Nip, VatUe, Other or None), name | Dane identyfikujące nabywcę. |
| netAmount | Total net amount | Łączna kwota netto. |
| grossAmount | Total gross amount | Łączna kwota brutto. |
| vatAmount | Total VAT amount in PLN | Łączna kwota VAT wyrażona w PLN. |
| currency | Currency code | Kod waluty. |
| invoicingMode | Online or Offline | Tryb fakturowania (online/offline). |
| invoiceType | Invoice type (Vat, Zal, Kor, Roz, Upr, KorZal, KorRoz, and PEF / RR types) | Rodzaj faktury. |
| formCode | Document structure: systemCode, schemaVersion, value | Struktura dokumentu faktury. |
| isSelfInvoicing | Whether the invoice was self-billed | Czy faktura została wystawiona w trybie samofakturowania. |
| hasAttachment | Whether the invoice has an attachment | Określa, czy faktura posiada załącznik. |
| invoiceHash | SHA-256 hash of the invoice, Base64 | Skrót SHA256 faktury, zakodowany w formacie Base64. |
| hashOfCorrectedInvoice | SHA-256 hash of the corrected invoice (optional) | Skrót SHA256 korygowanej faktury, zakodowany w formacie Base64. |
| thirdSubjects | List of third parties (optional) | Lista podmiotów trzecich. |
| authorizedSubject | Authorised entity (optional) | Podmiot upoważniony. |
How the converter uses it
- It computes the SHA-256 hash of every XML file and looks it up in
invoiceHash. A match gives the KSeF number and the date it was assigned, with certainty that the file is unchanged. - If a file name carries a KSeF number but the hash differs, the workbook says so in the "File hash check" column.
- The documentation does not say how the XML files inside the package are named, so the converter does not depend on file names when the metadata is present.
Have a ZIP of KSeF XML invoices?
Turn it into an Excel workbook and PDFs. Free up to 5 files, nothing uploaded.
Source: Przyrostowe pobieranie faktur (KSeF documentation); KSeF API 2.0 OpenAPI definition, schema InvoiceMetadata. Read 2026-11-10.