KSeF 2.0-API ontwikkelaarsgids: auth, sessies, FA(3), UPO, offline

KSeF 2.0 is de REST-API van het Poolse Ministerie van Financiën voor het nationale e-factuursysteem (Krajowy System e-Faktur). Een integratie authenticeert zich met een challenge die met een gekwalificeerd certificaat wordt ondertekend of met een KSeF-token wordt versleuteld, wisselt het resultaat in voor een kortlevende JWT, opent een sessie met een zelf gegenereerde AES-sleutel, dient onder die sleutel versleutelde FA(3)-XML-facturen in, pollt hun status en downloadt de UPO — het officiële ontvangstbewijs dat een factuur haar KSeF-nummer en haar juridische bestaan geeft. Deze gids volgt die volgorde en behandelt vervolgens batchindiening, de offlinemodi, limieten en hoe de KSeF-module van KRONENWERK daarop aansluit.

Omgevingen

Er bestaan drie publieke omgevingen, en ze zijn niet onderling verwisselbaar. Alles hieronder geldt voor alle drie; de basis-URL bepaalt welke.

De API-documentatie wordt onder elke basis-URL op /docs/v2 aangeboden, en dezelfde OpenAPI-beschrijving, gidsen en officiële clientbibliotheken (C# en Java) worden door de CIRFMF-organisatie van het Ministerie op GitHub gepubliceerd. Sinds 1 oktober 2025 hebben de testomgevingen geplande onderhoudsvensters (16:00–18:00), waarin aanroepen kunnen mislukken. Dien nooit productiefacturen of echte entiteitsgegevens in op TEST of DEMO.

Authenticatie

Elke beveiligde aanroep draagt een JWT-toegangstoken. Het verkrijgen ervan is een flow in vijf stappen waarvan de eerste en de laatste stap dezelfde zijn, ongeacht de gebruikte credential.

1. Challenge. POST /auth/challenge geeft een challengewaarde en een tijdstempel terug. Die is 10 minuten geldig.
2. Identiteit bewijzen, op een van twee manieren:
   • XAdES-handtekening. Bouw een AuthTokenRequest-XML met de challenge, de contextidentificatie (NIP, interne identificatie of EU-btw-identificatie van de entiteit waarvoor u optreedt) en het type subjectidentificatie, onderteken die XAdES met een gekwalificeerd certificaat (persoonlijk of organisatorisch gekwalificeerd certificaat, Trusted Profile, een KSeF-certificaat of een certificaat van een Peppol-aanbieder), en stuur ze naar POST /auth/xades-signature.
   • KSeF-token. Voeg {ksefToken}|{timestampMs} samen, versleutel met RSA-OAEP (SHA-256, MGF1) met de gepubliceerde publieke sleutel van het Ministerie, codeer in Base64 en stuur het samen met de challenge en de context naar POST /auth/ksef-token. KSeF-tokens worden binnen KSeF uitgegeven door iemand die al een machtiging voor de entiteit heeft; ze zijn geschikt voor onbewaakte integraties.
   Beide aanroepen geven een tijdelijk authenticatietoken en een referentienummer terug.
3. Pollen. GET /auth/{referenceNumber} met het tijdelijke token totdat de status definitief is. De verificatie is asynchroon — het systeem controleert de handtekening en het certificaat tegen OCSP/CRL.
4. Inwisselen. POST /auth/token/redeem wisselt het tijdelijke token eenmalig in voor een accessToken (JWT, ongeveer 15 minuten, de exacte levensduur staat in de exp-claim) en een refreshToken (ongeveer 7 dagen).
5. Vernieuwen. POST /auth/token/refresh met het refreshtoken geeft een nieuw toegangstoken terug met de huidige machtigingen van de entiteit.

Machtigingen worden in KSeF per entiteit en per rol toegekend (uitreiken, lezen, credentials beheren, enzovoort); een toegangstoken weerspiegelt de machtigingen op het moment van uitgifte en wordt ongeldig wanneer ze worden ingetrokken. Een autorisatiebeleid kan een token beperken tot IP-adressen of -bereiken. Bewaar beide tokens als geheimen.

Interactieve sessie: indienen, status, UPO

Een interactieve sessie dient facturen één voor één in, synchroon op de lijn en asynchroon in de verwerking. Het is de modus die de meeste facturatiesoftware gebruikt.

1. Sleutel voorbereiden. Genereer een 256-bits AES-sleutel en een 128-bits IV. Versleutel de sleutel met de publieke RSA-sleutel van het Ministerie (RSAES-OAEP, MGF1 met SHA-256). De clientbibliotheken van het Ministerie bevatten een CryptographyService die dit doet.
2. Openen. POST /sessions/online met de schemaversie (FA(3) — het huidige factuurschema; FA(2) wordt in de documentatie nog genoemd) en de versleutelde sleutel. Het antwoord bevat een sessie-referenceNumber en validUntil. Een sessie leeft 12 uur, en meerdere sessies kunnen onder één toegangstoken parallel open zijn.
3. Verzenden. POST /sessions/online/{referenceNumber}/invoices met de factuur versleuteld met AES-256-CBC met PKCS#7-padding en Base64-gecodeerd, plus de SHA-256-hash en de grootte van zowel het onversleutelde als het versleutelde bestand. Het antwoord bevestigt de ontvangst; de validatie tegen het schema en de bedrijfsregels start onmiddellijk en asynchroon.
4. Pollen. GET /sessions/{referenceNumber}/invoices somt de status van elke factuur op: aanvaard met een KSeF-nummer, of afgewezen met een reden. Poll met back-off, niet in een strakke lus.
5. Sluiten. POST /sessions/online/{referenceNumber}/close beëindigt de sessie en activeert de generatie van de verzamel-UPO.
6. De UPO ophalen. De UPO (Urzędowe Poświadczenie Odbioru) is een ondertekend XML-document dat de aanvaarde facturen opsomt met hun KSeF-nummers en aanvaardingstijdstempels. Bewaar ze bij de facturen: ze is het bewijs dat de factuur in juridische zin is uitgereikt.

Het KSeF-nummer, niet uw interne nummer, is wat de koper in zijn eigen KSeF-inbox ziet en wat een betalingsreferentie mogelijk moet vermelden. De uitreikingsdatum voor btw-doeleinden is de datum waarop de factuur door KSeF is aanvaard, die kan verschillen van de datum in de FA(3) — een punt dat voor elk specifiek geval professionele bevestiging vereist.

Batchsessie

Een batchsessie dient veel facturen in als één versleutelde ZIP. Ze is geschikt voor maandafsluitingen en migraties.

1. Plaats de FA(3)-XML-bestanden in een ZIP.
2. Splits het ZIP-binaire bestand in delen van maximaal 100 MB, op volgorde genummerd.
3. Versleutel elk deel met AES-256-CBC volgens hetzelfde sleutelschema als hierboven; bereken de SHA-256 en de grootte van elk versleuteld deel.
4. POST /sessions/batch met de versleutelde sleutel, de ZIP-metadata, de schemaversie en de lijst van delen. Het antwoord geeft een referenceNumber terug en, per deel, een upload-URL, methode en headers.
5. Upload elk deel als ruwe binaire data naar zijn URL. Het uploadvenster is 20 minuten per aangegeven deel, gepoold.
6. POST /sessions/batch/{referenceNumber}/close, poll daarna de sessiestatus en download de verzamel-UPO zoals bij een interactieve sessie.

Beide sessietypes aanvaarden tot 10.000 facturen. Een factuur mag maximaal 1 MB groot zijn, of 3 MB met een bijlage.

Facturen lezen

De ontvangstzijde is symmetrisch. POST /invoices/query/metadata geeft factuurmetadata terug voor een subjecttype (uitreiker, ontvanger, enzovoort) en een datumbereik, gepagineerd met pageOffset en pageSize. GET /invoices/ksef/{ksefNumber} downloadt één factuur op KSeF-nummer. Voor bulkophaling start POST /invoices/exports een asynchrone export onder een door u aangeleverde versleutelingssleutel, en GET /invoices/exports/{referenceNumber} rapporteert de voortgang en levert het versleutelde pakket. Een integratie die elke inkoopfactuur moet zien, pollt de metadataquery incrementeel in plaats van herhaaldelijk te exporteren.

Offlinemodi

Drie modi laten een belastingplichtige toe buiten KSeF uit te reiken en achteraf in te dienen. Elke modus heeft een eigen aanleiding en termijn, en elke is juridisch verschillend.

Een offlinefactuur is een normale FA(3) met twee afgedrukte of ingesloten QR-codes: KOD I, waarmee de koper de factuur in KSeF kan verifiëren, en KOD II, die de identiteit van de uitreiker bevestigt op basis van zijn KSeF-certificaat. Stel bij de latere indiening offlineMode: true in op het verzendverzoek, in beide sessietypes. Als KSeF tijdens het indieningsvenster onbeschikbaar wordt, begint de termijn opnieuw en kan ze oplopen tot 7 werkdagen na het einde van de storing.

Limieten en fouten

Het Ministerie documenteert limieten per context (de entiteit waarvoor u optreedt) en per credential in plaats van per API-sleutel: 10.000 facturen per sessie, 1 MB of 3 MB per factuur, 100 MB per batchdeel, en plafonds voor certificaataanvragen en actieve certificaten per identificatie (voor een NIP, 300 aanvragen en 100 actieve certificaten op het moment van lezen). Er bestaan limieten op de aanvraagfrequentie — de documentatie zegt dat het systeem het aantal verzoeken beperkt om de stabiliteit te beschermen — en die worden in een afzonderlijk document over rate limits beschreven; ontwerp voor HTTP 429 met retry en back-off in plaats van voor een vast cijfer.

Fouten komen terug als een HTTP-status met een JSON-body die het probleem beschrijft: 400 voor misvormde verzoeken, 401 voor een ontbrekend of verlopen token, 403 voor een machtiging die het token niet draagt, en validatiefouten per factuur die in de sessiestatus worden gerapporteerd in plaats van op de verzendaanroep. Schemafouten (de XML komt niet overeen met FA(3)) en semantische fouten (een NIP die niet bestaat, een datum buiten het toegestane venster, een duplicaat) komen in verschillende stadia naar boven; lees de statusvermelding voor elke factuur in plaats van op een 2xx bij de upload te vertrouwen.

Hoe KRONENWERK dit afhandelt

NOG NIET GEREED De KSeF 2.0-module van KRONENWERK implementeert de hierboven beschreven flow: tokenauthenticatie (challenge, versleuteld KSeF-token, inwisselen, vernieuwen), een interactieve sessie met een per sessie gegenereerde AES-sleutel, FA(3)-generatie en -indiening, statuspolling, UPO-ophaling en het lezen van ontvangen facturen. Ze is per configuratie omgevingsafhankelijk — dezelfde code richt zich volgens de instellingen op TEST, DEMO of productie — en ze is niet gebruikt tegen de productie-KSeF. Om die reden verkoopt KRONENWERK momenteel geen abonnementen aan Poolse ondernemingen, en niets op deze pagina mag worden gelezen als aanvaarding in productie. FA(3)-generatie zelf is ONDERSTEUND MET BEPERKINGEN: de XML wordt bij uitreiking aangemaakt en tegen het schema gecontroleerd, maar de verzending en het daaruit voortvloeiende KSeF-nummer en de UPO hangen ervan af dat de module in productie bewezen is. De publieke API stelt geen KSeF-operaties bloot: POST /invoices/drafts maakt een concept aan, het uitreiken gebeurt in het product, en geen enkel endpoint dient FA(3) in, geeft een KSeF-nummer terug of haalt een UPO op. Zie KSeF-integratie voor wat de API biedt, KSeF uitgelegd en FA(3) voor het formaat, en de Polen-hub en de landenpagina voor de actuele status.