KSeF-integratie: hoe de KSeF 2.0-module van KRONENWERK werkt

KRONENWERK bevat een KSeF 2.0-module die zich authenticeert met het KSeF-token van een belastingplichtige, een onlinesessie opent, FA(3)-facturen indient die zijn versleuteld met de sleutel van het ministerie, pollt naar het KSeF-nummer, de UPO ophaalt en inkomende facturen leest. De module is gebouwd en getest tegen de omgevingen van het ministerie, maar is niet gebruikt tegen de productieomgeving van KSeF, en KRONENWERK verkoopt momenteel geen abonnementen aan Poolse ondernemingen totdat dat is aangetoond. Voor verzending is de status NOG NIET GEREED. Uw integratie zou de gewone API eromheen gebruiken — klanten, concepten, webhooks — en er wordt niets KSeF-specifieks via de API blootgesteld.

Wat KSeF is, in één alinea

KSeF (Krajowy System e-Faktur) is het centrale clearance-systeem van Polen: een gestructureerde factuur in het FA(3)-schema wordt ingediend bij het systeem van het ministerie van Financiën, dat ze valideert, een KSeF-nummer toekent en een officieel ontvangstbewijs (UPO, urzędowe poświadczenie odbioru) teruggeeft. Zolang dat nummer niet bestaat, is het bestand juridisch geen factuur. Dit maakt Polen anders dan Duitsland, waar een conform bestand dat via om het even welke weg wordt verstuurd aan de verplichting voldoet, en dan België, waar de weg het Peppol-netwerk is. Achtergrond staat op KSeF uitgelegd; het schema op FA(3); de hub op e-facturatie in Polen.

Wat de KSeF 2.0-module van KRONENWERK doet

De module implementeert de KSeF API 2.0 zoals gepubliceerd in de OpenAPI-specificatie van het ministerie (paden en veldnamen zijn daaruit overgenomen, niet uit het geheugen). Ze werkt per belastingplichtige: elke aanroep gebeurt in de context van één NIP met het KSeF-token van die belastingplichtige, en toegangstokens worden per NIP gecachet en vernieuwd voordat ze verlopen.

Er bestaan twee authenticatiemethoden van het ministerie; de module gebruikt de KSeF-tokenmethode, waarbij een JSON-document met een eerder verkregen systeemtoken wordt verstuurd in plaats van een met XAdES ondertekend XML-verzoek. Het token behoort tot de onderneming en wordt binnen KSeF aan haar uitgegeven; KRONENWERK bewaart het verzegeld en gebruikt het alleen om te authenticeren. Het ministerie documenteert beide methoden en merkt op dat zelfondertekende certificaten alleen in de testomgeving worden aanvaard.

Waarom ze omgevingsafhankelijk is en nog niet gereed

Het ministerie publiceert drie omgevingen, en de module is telkens tegen precies één ervan geconfigureerd:

De module van KRONENWERK is beproefd tegen de niet-productieomgevingen van het ministerie. Ze is niet gebruikt tegen de productieomgeving van KSeF, waar een indiening een rechtshandeling is waarvan de fiscale positie van een andere partij afhangt. Zolang geen echte indiening met een echte UPO is gedaan en geverifieerd, markeert KRONENWERK verzending als Nog niet gereed en verkoopt het geen abonnementen aan Poolse ondernemingen. Dit is een uitspraak over bewijs, niet over codedekking: het verschil tussen "de client doorstaat zijn tests" en "het ministerie heeft onze factuur aanvaard" is het verschil dat telt, en het is nog niet overbrugd.

De FA(3)-generatie zelf — de XML produceren uit de feiten van een concept en ze aan het schema valideren — is Ondersteund met beperkingen: het document wordt geproduceerd, maar een FA(3)-bestand zonder KSeF-nummer is geen factuur, dus het nut ervan wordt begrensd door de verzendstatus hierboven.

Hoe een ontwikkelaar de API eromheen zou gebruiken

Niets op de KRONENWERK-API is KSeF-specifiek. Als de Poolse route beschikbaar komt, ziet een integratie er precies uit als een voor elk ander land: het KSeF-werk zit binnen het uitreiken en verzenden, die beide in het product blijven.

1. Maak de Poolse klant aan met POST /customers, inclusief country: "PL" en de NIP van de koper in vatId. FA(3) identificeert de koper aan de hand van de NIP, en een klant zonder NIP kan niet via KSeF worden gefactureerd.
2. Start het concept met POST /invoices/drafts en een Idempotency-Key.
3. Een persoon vervolledigt en reikt het concept uit in het product. De Poolse module rendert de FA(3)-XML en valideert ze; het nummer wordt verbruikt en invoice.issued wordt in de wachtrij geplaatst.
4. De persoon verzendt de uitgereikte factuur vanuit het product. De module authenticeert met het KSeF-token van de onderneming dat in Instellingen → Verzending is opgeslagen, opent een sessie, dient in, pollt, sluit, en slaat het KSeF-nummer en de UPO op. Een onbekende uitkomst blokkeert het opnieuw versturen totdat een afstemmingsquery aan KSeF heeft gevraagd of het document al aanwezig is.
5. Uw endpoint ontvangt invoice.issued, later invoice.paid of invoice.cancelled. Het KSeF-nummer, de UPO en de verzendstatus worden in het product getoond en staan vandaag niet op de API.

Wat de onderneming moet configureren wanneer de route beschikbaar is: stamgegevens van de rechtspersoon met haar NIP (afgeleid uit het fiscaal nummer), het KSeF-token ingevoerd in Instellingen → Verzending — KRONENWERK valideert het onmiddellijk door een geauthenticeerde aanroep te doen met precies het token dat het zojuist heeft opgeslagen, en weigert een token te bewaren dat niet werkt — en, voor uw integratie, een API-sleutel met customers:write, customers:read, invoices:write, invoices:read en companies:read plus een webhook-endpoint. De algemene API-mechanismen staan op de pagina over de boekhoud-API en de pagina over de factuur-API.

Basisbeginselen van KSeF API 2.0, met bronnen

Als u in plaats daarvan een rechtstreekse integratie overweegt, is het materiaal van het ministerie de primaire bron, en dit is waar u begint.

• Integratorgids: de gids van het ministerie (gedateerd 5 mei 2026 in de huidige revisie) behandelt authenticatie, machtigingen, KSeF-certificaten, offline-modi, QR-codes, interactieve en batchsessies, het ophalen van facturen, incrementeel ophalen, beheer van KSeF-tokens, encryptiesleutels, limieten en testgegevens, met voorbeelden in C# en Java uit zijn open-source referentieclients. github.com/CIRFMF/ksef-docs.
• OpenAPI: elke omgeving serveert haar eigen specificatie onder /docs/v2; die van de testomgeving staat op api-test.ksef.mf.gov.pl/docs/v2. Fouten zijn RFC 7807-probleemdocumenten met detail en een errors[]-lijst.
• Authenticatie: verkrijg een challenge (tien minuten geldig), stuur dan ofwel een XML-AuthTokenRequest ondertekend met XAdES met een gekwalificeerd certificaat of een KSeF-certificaat, ofwel een JSON-document met een KSeF-token; poll de status; wissel in voor een JWT-toegangstoken en een vernieuwingstoken. De authenticerende partij moet ten minste één actieve machtiging hebben voor de gekozen context (een NIP, een interne identificatie of een samengestelde EU-btw-identificatie). uwierzytelnianie.md.
• Sessies: een interactieve sessie neemt facturen één voor één aan en geeft per factuur een status terug; het sluiten van de sessie start de generatie van een verzamel-UPO. Een batchsessie is afzonderlijk gedocumenteerd voor bulkindiening. Publieke sleutels voor het versleutelen van de sessiesleutel en het KSeF-token worden door het ministerie gepubliceerd en roteren.
• Omgevingen en onderhoud: TEST en DEMO mogen nooit productiefacturen of echte partijgegevens ontvangen; het ministerie plant onderhoud aan de testomgevingen van 16:00 tot 18:00 uur en publiceert wijzigingen die de API raken in zijn changelog. srodowiska.md.

De KSeF-gids voor ontwikkelaars gaat dieper in op het schema en het sessiemodel.

Hoe KRONENWERK hiermee omgaat

Nog niet gereed voor verzending. De KSeF 2.0-module — token-authenticatie, sessie, FA(3)-indiening, UPO-ophaling en ontvangst — is gebouwd en omgevingsafhankelijk, en is niet gebruikt tegen de productieomgeving van KSeF. KRONENWERK verkoopt momenteel geen abonnementen aan Poolse ondernemingen totdat dat is aangetoond, en niets op deze pagina mag worden gelezen als een impliciete aanvaarding door de overheid of in productie. FA(3)-generatie is Ondersteund met beperkingen. De API stelt geen KSeF-specifiek endpoint, gebeurtenis of veld bloot; wanneer de route is aangetoond, zullen integraties dezelfde klant-, concept- en webhook-aanroepen gebruiken als overal elders. De landenpagina van Polen staat op Polen; de e-facturatiescope van het product op e-facturatie.