KSeF 2.0 uitgelegd: authenticatie, sessies, UPO, offlinemodi, QR-codes

KSeF 2.0 is de versie van het Poolse nationale e-factuursysteem die sinds 1 februari 2026, toen KSeF 1.0 werd uitgeschakeld, als enige van kracht is. Software authenticeert met een gekwalificeerde handtekening of een KSeF-token en ontvangt JWT-toegangstokens, opent een interactieve of batchsessie, verzendt AES-versleutelde FA(3)-XML en krijgt per factuur een KSeF-nummer van 35 tekens en per sessie een officieel ontvangstbewijs (UPO) terug. Offlinemodi, QR-codes en KSeF-certificaten dekken de gevallen waarin de factuur de koper buiten het systeem bereikt.

Wat er is veranderd van KSeF 1.0 naar 2.0

KSeF 2.0 is een nieuw API-contract, geen patch: authenticatie werd losgekoppeld van sessies, JWT-tokens vervingen de oude sessiegebonden aanmelding, versleuteling werd in elke modus verplicht, namen werden RESTful gemaakt, en er werd een certificaatmodule toegevoegd.

Het eigen overzicht van het ministerie voor integrators somt de belangrijkste wijzigingen op: authenticatie als onafhankelijke stap die herbruikbare, vernieuwbare en intrekbare tokens oplevert; één initialisatiemodel voor zowel POST /sessions/online als POST /sessions/batch, elk met een formuliercode en een versleutelde AES-sleutel; verplichte versleuteling aan clientzijde van elke factuur met RSA-OAEP (SHA-256, MGF1-SHA-256) ter bescherming van de sessiesleutel; consistente identificaties (NIP, PESEL, fingerprint) als expliciete enums; en interne KSeF-certificaten voor authenticatie en offline-uitreiking. De API is beschreven in OpenAPI 3.0.4 met interactieve documentatie op api.ksef.mf.gov.pl/docs/v2, en het ministerie publiceert opensource-clientbibliotheken voor C# en Java.

Omgevingen: test, demo, productie

Er bestaan drie openbare omgevingen, en alleen productie heeft rechtsgevolg.

De tijdlijn van het ministerie: open API-tests begonnen op 30 september 2025, de demo-API opende op 15 oktober 2025, de testomgeving van KSeF 1.0 werd op 1 september 2025 gesloten, en productie-KSeF 2.0 ging live op 1 februari 2026 na een technische onderbreking van 26 tot 31 januari. URL's die de API teruggeeft, verwijzen altijd naar de omgeving die is aangeroepen. Gepland onderhoud aan de testomgevingen kan tussen 16:00 en 18:00 plaatsvinden, en alleen wijzigingen die voor integratie relevant zijn, worden in de changelog aangekondigd.

Authenticatie: handtekening, KSeF-token, certificaten

Elke beveiligde aanroep vereist een JWT-accessToken. Om er een te verkrijgen, bewijst de client wie hij is (het authenticerende subject) en voor wie hij handelt (de context, meestal een NIP), en controleert KSeF of het subject ten minste één actief recht in die context heeft.

1. Challenge. POST /auth/challenge geeft een challenge terug die 10 minuten geldig is.
2. Identiteitsbewijs, op een van twee manieren:
   • XAdES-handtekening. De client bouwt een AuthTokenRequest-XML (challenge, contextidentificatie — NIP, interne ID of NIP-VAT-EU-combinatie — en subjectidentificatietype certificateSubject of certificateFingerprint, optioneel een beleid voor toegestane IP-adressen) en ondertekent die. Aanvaarde ondertekenaars: een gekwalificeerd certificaat van een natuurlijke persoon met PESEL of NIP, een gekwalificeerd organisatiezegel met de NIP, een handtekening via Trusted Profile, een KSeF-certificaat, of een certificaat van een Peppol-dienstverlener. Zelfondertekende certificaten worden alleen op TEST aanvaard.
   • KSeF-token. Een JSON-verzoek met een eerder gegenereerd systeemtoken. Tokens worden gegenereerd met POST /tokens na ten minste één XAdES-authenticatie, dragen een lijst van rechten zoals InvoiceRead, InvoiceWrite, CredentialsRead, CredentialsManage, en zijn vertrouwelijke geheimen.
3. Tokens. Het antwoord levert een accessToken en een refreshToken; toegangstokens verlopen, kunnen worden vernieuwd zonder opnieuw te authenticeren en worden automatisch ingetrokken wanneer de rechten verloren gaan. Sessies worden opgesomd onder GET /auth/sessions en ingetrokken met DELETE /auth/sessions/current of op referentienummer.

KSeF-certificaten worden door het systeem zelf uitgegeven en zijn geen gekwalificeerde certificaten. Een certificaat draagt precies één type: Authentication (key usage digital signature) om in te loggen, of Offline (key usage non-repudiation) om de tweede QR-code op offlinefacturen te ondertekenen; het kan niet beide. Aanvragen (/certificates/enrollments) is alleen mogelijk na een XAdES-authenticatie, in eigen naam van het subject, met een PKCS#10-CSR, en een certificaat is ten hoogste twee jaar geldig. Standaardlimieten: 300 aanvragen en 100 actieve certificaten per NIP, 12 en 6 per PESEL of fingerprint.

De rechten zelf worden in het systeem toegekend: een bedrijf zonder gekwalificeerd zegel wijst een natuurlijke persoon aan via formulier ZAW-FA, en die persoon kent vervolgens verdere rechten toe, bijvoorbeeld aan een accountant of aan het certificaat van een software-integrator.

Sessies: interactief en batch

Een interactieve sessie verzendt facturen één voor één en past bij facturatiesoftware; een batchsessie verzendt een ZIP van maximaal 10.000 facturen in versleutelde delen van ten hoogste 100 MB en past bij bulkuploads. Beide beginnen met dezelfde JSON: de formuliercode (schemaversie) en de AES-sleutel van de sessie, versleuteld met de openbare sleutel van het ministerie.

Interactief

1. Genereer een 256-bits AES-sleutel en een 128-bits IV; versleutel de sleutel met RSA-OAEP met de actuele openbare sleutel van GET /security/public-key-certificates.
2. POST /sessions/online met de formuliercode (FA(3)) en de versleutelde sleutel. Het antwoord geeft een referenceNumber en validUntil; een sessie leeft 12 uur en er kunnen er meerdere parallel open zijn.
3. POST /sessions/online/{referenceNumber}/invoices met elke factuur versleuteld met AES-256-CBC (PKCS#7-padding), de hash en de grootte ervan. Het antwoord geeft een documentreferentienummer terug.
4. Poll GET /sessions/{referenceNumber} en GET /sessions/{referenceNumber}/invoices voor de status per factuur, het KSeF-nummer en de factuur-UPO.
5. POST /sessions/online/{referenceNumber}/close. Het sluiten start de asynchrone generatie van de verzamel-UPO voor de sessie.

Batch

De client zipt de XML-bestanden, splitst de ZIP binair in delen van ten hoogste 100 MB vóór versleuteling, versleutelt elk deel, beschrijft de delen in fileParts bij het openen van POST /sessions/batch, uploadt ze naar de teruggegeven URL's en sluit de sessie. Het ministerie beveelt aan een SHA-256-hash per oorspronkelijke XML vast te leggen, zodat KSeF-statussen aan lokale documenten kunnen worden gekoppeld. Standaardlimieten per context: 1 MB per factuur (3 MB met bijlage), 10.000 facturen per sessie, 500 per verzamelidentificatie.

KSeF-nummer en UPO

Het KSeF-nummer is het bewijs dat een factuur bestaat; de UPO (Urzędowe Poświadczenie Odbioru) is het officiële ontvangstbewijs van een sessie en de facturen erin.

Het nummer bestaat altijd uit 35 tekens: NIP-YYYYMMDD-XXXXXXXXXXXX-CC — de tiencijferige NIP van de verkoper, de datum waarop de factuur ter verwerking is aanvaard, een twaalf tekens lang hexadecimaal technisch deel en een controlegetal van twee tekens (CRC-8, polynoom 0x07, beginwaarde 0x00). Software kan een nummer offline valideren door het controlegetal opnieuw te berekenen. Het mag niet worden verward met het eigen factuurnummer van de verkoper in veld P_2.

Voordat KSeF een nummer toekent, controleert het twee dingen: dat de XML aan het actuele schema voldoet, en dat de verzender het recht heeft in die context uit te reiken. Een afgewezen bestand is geen factuur; het wordt hersteld en opnieuw ingediend, niet "gecorrigeerd" met een creditnota. Voor een onlinefactuur is de uitreikingsdatum de verzenddatum, zolang veld P_1 daarmee overeenstemt, ook als het nummer pas de volgende dag arriveert.

Offlinemodi

Vier modi laten het uitreiken doorgaan wanneer de verbinding of het systeem niet beschikbaar is; bij drie daarvan moet de factuur achteraf naar KSeF worden verzonden, met offlineMode: true, binnen een wettelijke termijn.

In offlinemodi is de uitreikingsdatum de datum in P_1, niet de verzenddatum. Behalve in de noodmodus ontvangt de koper de factuur in KSeF en krijgt hij vóór verzending geen kopie overhandigd; in de noodmodus wordt het FA(3)-bestand op een overeengekomen manier aan de koper geleverd en achteraf genummerd. Als een aangekondigde storing binnen het offline24- of onbeschikbaarheidsvenster valt, verschuift de termijn naar 7 werkdagen na het einde van die storing. Een buiten KSeF uitgereikte factuur mag nooit binnen KSeF opnieuw worden uitgereikt — dat creëert twee facturen voor één verkoop.

QR-codes op visualisaties

Een visualisatie die buiten KSeF wordt overhandigd — pdf, afdruk, e-mailbijlage — draagt een QR-code zodat iedereen de factuur in het systeem kan verifiëren; offlinefacturen dragen er twee.

• KOD I verwijst naar de verificatiepagina en laat de houder de factuur controleren en, met aanvullende gegevens, downloaden. Eronder staat het KSeF-nummer wanneer dat bekend is, of het woord OFFLINE voordat het nummer is toegekend.
• KOD II bevestigt de identiteit van de uitreiker voor offlinefacturen. Hij wordt ondertekend met een Offline-KSeF-certificaat; een Authentication-certificaat kan niet worden gebruikt. KSeF verifieert dat het certificaat bestaat, geldig is, niet ingetrokken en niet geblokkeerd is, en dat het subject ervan actieve uitreikingsrechten in de context heeft.

Codes worden lokaal door de client gegenereerd uit de factuurgegevens (ISO/IEC 18004:2024) en de host van de link volgt de omgeving. Een visualisatie mag pas aan de koper worden overhandigd zodra de factuur in KSeF is geregistreerd, behalve in de noodmodus.

Facturen ontvangen

Kopers halen facturen op uit KSeF in plaats van ze per e-mail te ontvangen. De API biedt factuurquery's en incrementele download van nieuw uitgereikte facturen in de context van de koper, en het ministerie bevestigt dat software ze automatisch mag ophalen. Buitenlandse kopers zonder NIP kunnen niet inloggen en krijgen in plaats daarvan een kopie met KOD I toegestuurd. Het FA(3)-bestand dat terugkomt, is gedocumenteerd op de FA(3)-schemapagina.

Hoe KRONENWERK hiermee omgaat

Nog niet gereed voor verzending. De KSeF 2.0-module van KRONENWERK — tokenauthenticatie, interactieve sessie, FA(3)-indiening, UPO-ophaling en ontvangst — is gebouwd en omgevingsafhankelijk, en is niet gebruikt tegen het productie-KSeF. FA(3)-generatie en schemavalidatie zijn Ondersteund met beperkingen. KRONENWERK verkoopt geen abonnementen aan Poolse bedrijven totdat de indiening in productie is bewezen; zie de Polen-hub en de landenpagina Polen.

Het ontwerp volgt de regel die het systeem oplegt: een factuur is in KRONENWERK niet "uitgereikt" totdat KSeF een nummer heeft teruggegeven, en een indiening waarvan het antwoord verloren ging, wordt afgestemd door KSeF te vragen wat het bezit in plaats van opnieuw te verzenden, omdat een blinde herhaling een tweede wettelijke factuur zou creëren. Ontwikkelaars die hun eigen systemen integreren, kunnen dit vergelijken met KSeF-integratie en de stapsgewijze KSeF-gids. Deze pagina beschrijft het systeem van het ministerie; het is geen fiscaal of juridisch advies.

Veelgestelde vragen

Heb ik een gekwalificeerde handtekening nodig om de KSeF-API te gebruiken?

Voor de eerste authenticatie wel — een gekwalificeerd certificaat, een gekwalificeerd zegel, een handtekening via Trusted Profile of een KSeF-certificaat. Daarna kan software een KSeF-token of een KSeF-Authentication-certificaat gebruiken.

Wat is het verschil tussen het KSeF-nummer en de UPO?

Het KSeF-nummer is de identificatie van 35 tekens die aan elke aanvaarde factuur wordt toegekend; de UPO is het officiële ontvangstbewijs dat voor een sessie wordt gegenereerd, beschikbaar nadat de sessie is gesloten, en ook per factuur.

Wat betekent offline24?

De belastingplichtige reikt een FA(3)-factuur uit zonder verbinding en moet ze uiterlijk de eerstvolgende werkdag naar KSeF verzenden; de koper ontvangt ze in KSeF, en de visualisatie draagt twee QR-codes.

Kan ik op de testomgeving met echte gegevens testen?

Nee. Het ministerie zegt dat TEST-gegevens tussen integrators worden gedeeld en dat willekeurige NIP's en geanonimiseerde gegevens moeten worden gebruikt; DEMO gebruikt echte inloggegevens, maar heeft geen rechtsgevolg.

Wordt elke factuur versleuteld?

Ja. In KSeF 2.0 wordt elke factuur, interactief of batch, aan clientzijde versleuteld met een AES-sleutel die zelf met de openbare sleutel van het ministerie wordt versleuteld wanneer de sessie wordt geopend.