ediverse

Type to search across standards, messages, tools and glossary.

ediverse Explore the platform

Spotlight PEPPOL BIS Billing 3.0 The EU e-invoicing mandate is here — France Sept 2026, Belgium Jan 2026, Germany 2025.

— 01

Foundations

— 02

Standards

— 03

Flagship messages

— 04

Tools

Numer KSeF — legally binding UUID

The numer KSeF is the unique identifier of each invoice validated by KSeF — a 36-character UUID assigned by the Polish State after successful clearance. This identifier legally replaces the issuer's internal sequence and becomes the legal reference for accounting, audits, litigation.

Format and structure of numer KSeF

The numer KSeF follows a structured, human-readable format that encodes several business pieces of information:

text numer-ksef-format.txt 
Format: NIP-DATE-IDENT-CHK

5260250274-20260519-7C8A3D4E5F0A1B2C-AA
└─────┬────┘ └───┬──┘ └───────┬──────┘ └┬┘
      │         │            │         │
      │         │            │         └── 2-char checksum (Polish Luhn-like)
      │         │            └── 16-char unique identifier (UUIDv4 truncated)
      │         └── Clearance date YYYYMMDD
      └── Issuer NIP (10 digits without dash)
  • Issuer NIP (10 digits). Fiscal identifier of the issuer taxpayer. Allows multi-party uniqueness: two different issuers can generate the same internal sequence, their KSeF numbers stay unique.
  • Clearance date (YYYYMMDD). Date at which KSeF actually assigned the number, in Europe/Warsaw time zone. To be distinguished from Fa/P_1 (business issue date).
  • Unique identifier (16 hex characters). Truncated UUIDv4, ensures uniqueness within a day for a given NIP. 16 hex characters = 264 possibilities, sufficient for 18 billion transactions / day / NIP — well above realistic volumes.
  • Checksum (2 characters). Luhn-like algorithm adapted to ASCII characters, allows detecting a typing error in human readings. Verified by KSeF on input on certain endpoints.

Assignment post-clearance

The assignment moment is precise and legally defined: the instant KSeF sets the status Zaakceptowana (accepted) after all XSD, Schematron and business validations.

  1. T = submission. ERP sends POST /api/online/Invoice/Send. No numer KSeF assigned yet. The returned status is W trakcie przetwarzania (in progress).
  2. T + 0.5-2s = clearance. KSeF completes validations. If OK, assignment of numer KSeF in the State database, status set to Zaakceptowana, UPO generation.
  3. T + 1-10s = made available. The number is queryable via GET /api/online/Invoice/Status/{referenceNumber}. The invoice is simultaneously accessible to the recipient via the reception service.

UPO — Urzędowe Poświadczenie Odbioru

The UPO is the official XML attestation signed by the ministry, issued after each numer KSeF assignment. It constitutes the primary legal proof of issuance, retained by KSeF but also downloadable by issuer and recipient.

xml upo-example.xml 
<?xml version="1.0" encoding="UTF-8"?>
<UPO xmlns="http://ksef.mf.gov.pl/upo/2023/12/01/">
  <Naglowek>
    <Wersja>1.0</Wersja>
    <DataWystawienia>2026-05-19T08:42:17.482Z</DataWystawienia>
  </Naglowek>

  <Faktura>
    <NumerKSeF>5260250274-20260519-7C8A3D4E5F0A1B2C-AA</NumerKSeF>
    <DataPrzeslania>2026-05-19T08:42:11Z</DataPrzeslania>
    <DataPrzyjecia>2026-05-19T08:42:17Z</DataPrzyjecia>
    <SHA>9c1185a5c5e9fc54612808977ee8f548b2258d31</SHA>
    <SystemFakturujacy>ERP X v12.4</SystemFakturujacy>
  </Faktura>

  <PodmiotWystawiajacy>
    <NIP>5260250274</NIP>
    <NazwaPelna>Spółka Sprzedaży Sp. z o.o.</NazwaPelna>
  </PodmiotWystawiajacy>

  <PodmiotOdbierajacy>
    <NIP>7010023492</NIP>
    <NazwaPelna>Klient Sp. z o.o.</NazwaPelna>
  </PodmiotOdbierajacy>

  <Signature>
    <SignedInfo>...</SignedInfo>
    <SignatureValue>aBcDeFgHiJkLmNoPqRsTuVwXyZ123456...=</SignatureValue>
  </Signature>
</UPO>

UPO technical characteristics:

  • XAdES-T signature. XML electronic signature with qualified e-IDAS timestamping.
  • Ministry certificate. Issued by CenCert (Polish State certification authority).
  • SHA-256 included. Replays the hash of the submitted FA(2) invoice — integrity proof.
  • 10-year retention. KSeF keeps the UPO 10 years (tax ordinance art. 86).
  • Download. Via GET /api/online/Invoice/Get/{numerKSeF}.

Propagation to accounting ledgers

The numer KSeF is not a temporary identifier — it must be propagated in all internal accounting and fiscal systems of the taxpayer:

  • General ledger. The numer KSeF becomes the reference of the supplier / customer document in the ledger, in replacement (or complement) of the internal number.
  • JPK_V7M. In the NrKontrahenta or NumerWlasny field per vendor convention. KAS recommendation: prefix with KSeF: to distinguish.
  • Customer / supplier accounts. Bank reconciliation and payment reminders must quote the numer KSeF, which serves as a universal identifier.
  • Corrective invoices. Any corrective must compulsorily reference the original invoice's numer KSeF in FaKor/NumerKSeFFaKor.
  • Internal and financial reporting. ERP, BI, analytics — everywhere the invoice is referenced, the numer KSeF must be pivotal.

Special cases — correctives and tryb awaryjny

Two scenarios deserve particular attention for the numer KSeF:

  1. Corrective invoices. Each corrective receives its own numer KSeF distinct from the original invoice but must explicitly reference it via FaKor/NumerKSeFFaKor. KSeF maintains a modification chain for audit. If the original invoice has no numer KSeF (pre-2026 FA outside KSeF case), the corrective uses a transitional schema.
  2. Tryb awaryjny (degraded mode). In case of KSeF unavailability, the issuer can generate a local provisional number and issue the invoice as PDF with this number. Upon restoration, they must resubmit the invoice to KSeF within 7 days; KSeF then assigns the real numer KSeF which must be communicated to the recipient and substituted throughout the accounting.

Common pitfalls

  • Confusing numer KSeF and internal number. The number FV/2026/05/0142 is the issuer sequence (useful for their internal needs). The numer KSeF is the legal identifier. Both coexist in the invoice, but legally only the numer KSeF counts.
  • Forgotten UPO storage. If KSeF becomes unavailable later, or if the issuer needs to prove issuance without KSeF access (audit, litigation), the UPO must have been kept locally. KSeF retention does not exempt the taxpayer from their own proof.
  • Quoting the wrong number in customer correspondence. Once the cleared invoice is assigned, the numer KSeF must appear in payment orders, reminders, follow-ups. The internal number can mislead multi-supplier recipients.
  • Re-generating the numer KSeF. The numer KSeF is definitive and immutable. If the original invoice is erroneous, a corrective is issued (which receives its own new numer KSeF), the first one is never overwritten.