E-Invoice Finder
Menu
Landen Software Deadlines Gidsen Checker Verplichting checken
ENFRDEPLNL
Polen · KSeF-beheer

KSeF API-monitoring en incidentafhandeling voor ERP-teams

Bewaak KSeF-sessies, factuurstatus, UPO, limieten en incidenten met een ERP-draaiboek voor reconciliatie, alerts en veilig herstel.

Praktische samenvatting:
  • Reikwijdte: volg elke inzending van lokale boeking tot definitieve KSeF-uitkomst.
  • Risico: transport­succes, time-outs en sessietotalen kunnen een onzekere factuurstatus verhullen.
  • Actie: maak herstel idempotent en laat officiële API-antwoorden iedere vervolgstap bepalen.
Bekijk Polen-readinessrapportOfficiële bronnen
Laatst gecontroleerd: 27 juli 2026Officiële bronnenDuidelijke samenvattingPraktische informatie, geen juridisch advies
Officiële bronnen eerst
Controledatums zichtbaar
Gratis checker zonder registratie

Wat u moet weten

Gids

1. Monitoringmodel: één controleketen per factuur

Ontwerp KSeF API-monitoring als een controleketen tussen ERP, integratielaag en KSeF, niet als een simpele beschikbaarheidscheck. Leg bij de start het lokale ERP-factuurnummer of job-ID, de sessiereferentie, de factuurreferentie en verzend­tijdstippen vast. Vul die gegevens later aan met de teruggegeven KSeF-status en, zodra aanwezig, het KSeF-nummer. Zo kan support van een boeking naar de technische uitwisseling en terug navigeren. Een praktisch dashboard toont bijvoorbeeld: ERP-job PL-7842, sessie S…, factuurreferentie F…, verzonden om 10:14, huidige uitkomst ‘in verwerking’. De precieze waarden en statussen moeten uit de actuele API-respons komen. Vermijd payloads, tokens, privésleutels en andere credentials in logs; gebruik gemaskeerde identifiers en beperkte toegang. Zonder deze correlatie leidt een incident al snel tot handmatig zoeken, onterecht opnieuw verzenden of een onverklaarbaar verschil tussen ERP en KSeF.

Gids

2. Levenscyclus van sessie, factuur en UPO

De officiële Integrator Guide van 20 april 2026 beschrijft het bewaken van interactieve en batchsessies en het ophalen van UPO voor afzonderlijke facturen en een hele sessie. De API ondersteunt onder meer sessies opsommen, één sessie controleren, geaggregeerde factuuraantallen lezen, facturen binnen een sessie opsommen en één factuur op referentie controleren. Classificeer een inzending op basis van de actuele respons als pending/in verwerking, succesvol verwerkt of afgewezen; noem haar nooit geaccepteerd omdat alleen HTTP-transport of upload is gelukt. Een sessietotaal is nuttig voor voortgang, maar vervangt geen reconciliatie per factuur. Download een factuur- of sessie-UPO uitsluitend wanneer de respons een beschikbare UPO-referentie blootlegt. Beloof dus geen UPO vóór die beschikbaar is. Controleer na afloop of iedere lokale factuur precies één verklaarde uitkomst heeft en koppel bewijs aan het juiste dossier.

Gids

3. Observability: velden, meetwaarden en dashboard

Neem per gebeurtenis minimaal op: lokale job-ID, gemaskeerd ERP-factuurnummer, sessie- en factuurreferentie, aanvraag- en antwoordtijdstip, actuele status, KSeF-nummer indien teruggegeven, UPO-referentie indien beschikbaar, foutcategorie en laatste reconciliatie-uitkomst. Bewaar ook welke API- of OpenAPI-versie de integratie verwachtte, zonder gevoelige headers of documentinhoud te loggen. Bruikbare meetwaarden zijn aantallen per actuele uitkomst, sessie- versus factuurtotalen, niet-gereconcilieerde records, beschikbare maar nog niet opgehaalde UPO’s, 429-responsen en items in handmatige beoordeling. Een dashboard moet doorklikken naar een tijdlijn met geschoonde technische metadata. Toon onzekerheid expliciet: ‘status nog niet vastgesteld’ is veiliger dan een groen vinkje. Laat privacy- en securityteams retentie en toegang bepalen. Een veelgemaakte fout is alleen sessiesucces meten; daardoor kunnen individuele afwijzingen of ontbrekende koppelingen onzichtbaar blijven.

Gids

4. Alerts, ernst en eigenaarschap

Definieer ernst op bedrijfsimpact en bewijs, zonder zelf verzonnen KSeF-tijdslimieten. Een waarschuwing kan passen bij oplopende wachtrijen of meerdere 429-responsen terwijl reconciliatie nog werkt. Een hogere ernst past bij groeiende aantallen onverklaarde facturen, mislukte authenticatie voor alle jobs of een discrepantie tussen ERP en KSeF. Reserveer de zwaarste route voor aantoonbare brede uitval of een officieel gecommuniceerde storing met materiële procesimpact. Wijs vooraf een technisch eigenaar, finance-operations-eigenaar, securitycontact en beslisser voor bedrijfscontinuïteit aan. Elke alert moet de betrokken referenties, laatste betrouwbare respons, omvang, impact en aanbevolen volgende controle bevatten. Laat drempels aansluiten op actuele officiële limieten, eigen volumes en risicobereidheid; kopieer geen willekeurige pollingfrequentie uit een voorbeeld. Documenteer wie mag pauzeren, hervatten of naar handmatige beoordeling sturen, zodat snelheid niet ten koste gaat van controle.

Gids

5. HTTP 429, limieten en duplicaatveilig herstel

KSeF kent API- en contextlimieten. De officiële documentatie noemt als standaard maximaal 10.000 facturen in een interactieve of batchsessie, maar actuele of individuele limieten kunnen verschillen en zijn opvraagbaar. Behandel daarom de huidige officiële documentatie en API als runtime-waarheid. Bij HTTP 429 vereist de officiële incrementele-downloadrichtlijn dat Retry-After wordt gerespecteerd. Centraliseer begrenzing per context, voorkom concurrerende workers die elkaar versterken en gebruik gecontroleerde back-off zonder zelf vaste aantallen of intervallen als KSeF-regel te presenteren. Maak opdrachten idempotent met een stabiele lokale sleutel en een statusmachine. Na een time-out is de uitkomst onzeker: zoek eerst de bestaande sessie of factuur op en reconcileer referenties en status. Alleen wanneer het bewijs aangeeft dat een nieuwe poging passend is, mag herstel verdergaan. Blind opnieuw verzenden kan dubbele facturen, extra belasting en moeilijk bewijs veroorzaken.

Gids

6. Afwijzing, handmatige beoordeling en reconciliatie

Stuur een afgewezen of onverklaard item naar een dead-letter- of handmatige-beoordelingswachtrij met geschoonde foutmetadata, eigenaar en auditspoor. Splits technische herstelbaarheid van inhoudelijke correctie: een tijdelijke transportfout vraagt een andere behandeling dan een actuele API-respons die de factuur als afgewezen toont. De medewerker vergelijkt lokale job, factuurreferentie, sessiestatus, individuele factuurstatus en eventueel KSeF-nummer. Daarna legt die vast of het record wordt gecorrigeerd, opnieuw aangeboden volgens de geldende procedure, of geëscaleerd. Reconcileer periodiek beide richtingen: iedere ERP-inzending moet een verklaarde KSeF-uitkomst hebben en iedere gevonden KSeF-factuur moet aan een lokale registratie zijn gekoppeld. Vergelijk sessieaggregaten met de lijst van individuele facturen, maar gebruik het totaal niet als vervanging. Test ook ontbrekende callbacks, vertraagde verwerking en herstel na credentialrotatie. Dit is operationele guidance, geen juridisch of fiscaal advies.

Gids

7. Officiële storingcommunicatie en de grens met offline- en noodmodi

Volg de technische mededelingen van het Poolse ministerie en leg de geraadpleegde boodschap, het tijdstip en de genomen beslissing vast. De officiële documentatie onderscheidt offline24, door de belastingplichtige gekozen volgens de geldende regels; offline tijdens aangekondigde onbeschikbaarheid; noodmodus tijdens een officieel aangekondigde storing; en totale uitval. Deze regimes zijn niet onderling uitwisselbaar. Een time-out, trage verwerking of lokaal netwerkprobleem bewijst niet dat een officiële storingsmodus geldt en geeft op zichzelf geen toestemming om daarnaar over te schakelen. Laat de aangewezen bedrijfs- of compliance-eigenaar officiële communicatie en goedgekeurde procedures beoordelen voordat de juridische modus wijzigt. Engineers mogen verkeer veilig pauzeren, bewijs verzamelen en escaleren, maar geen regime afleiden uit technische symptomen. Oefen vooraf hoe wachtrijen, nummering, bewijs en latere synchronisatie per goedgekeurd scenario worden behandeld.

Gids

8. Tabletopvoorbeeld: time-out na een batchinzending

Stel: een ERP-worker verzendt een batch en ontvangt na transport een time-out. Het dashboard kent lokale job JOB-2607, het aanmaaktijdstip en de gebruikte context, maar heeft nog geen definitieve uitkomst. De incidentleider markeert de batch als ‘onzeker’, pauzeert automatische herverzending en bewaart credential-veilige requestmetadata. Het team controleert officiële technische mededelingen, vraagt via de actuele API sessies op en zoekt de bekende sessiereferentie of andere beschikbare correlatie. Vervolgens leest het de sessiestatus, aggregaten en factuurlijst en controleert elke factuurreferentie afzonderlijk. Beschikbare UPO’s worden gekoppeld; pending items blijven gevolgd, afwijzingen gaan naar beoordeling en ontbrekende koppelingen naar reconciliatie. Het bewijsdossier bevat tijdlijn, geschoonde responsen, aantallen vóór en na, beslisser en herstelactie. Pas na die controle beslist de eigenaar over vervolgstappen. De oefening slaagt wanneer geen duplicaat ontstaat en elke factuur een verklaarde status of eigenaar heeft.

Gids

9. Leverancierskeuze en eerstvolgende acties

Vraag een ERP- of integratieleverancier om een demonstratie met echte foutpaden, niet alleen een happy flow. Beoordeel of het product sessie- én factuurstatus bewaakt, referenties duurzaam correleert, UPO pas na beschikbaarheid downloadt, Retry-After volgt, actuele limieten kan opvragen en onzekere uitkomsten zonder automatische duplicaten herstelt. Controleer verder credential-safe logging, rollen en audittrail, dead-letter-queues, exporteerbare reconciliatie, dashboards, incidentrunbooks en aantoonbare tests voor offline- en noodscenario’s. Vraag hoe snel veranderingen in OpenAPI, statussen en officiële communicatie worden verwerkt, zonder een niet-officiële SLA als KSeF-eis te behandelen. Laat finance, engineering, security en compliance gezamenlijk accepteren. Begin daarna met een inventaris van identifiers en datastromen, bouw een statusmatrix op basis van de actuele documentatie, voer een tabletop uit en sluit gevonden hiaten voordat productievolume wordt verhoogd.

Checklist

Leg voor iedere inzending lokale job-ID, sessiereferentie, factuurreferentie, tijdstippen en teruggegeven KSeF-nummer/status vast.

Scheid pending/in verwerking, succesvol verwerkt en afgewezen op basis van de actuele API-respons.

Reconcileer iedere factuur afzonderlijk; vertrouw niet alleen op geaggregeerde sessieaantallen.

Download een UPO pas wanneer de respons een beschikbare UPO-referentie geeft.

Maskeer logs en sluit factuurpayloads, credentials, privésleutels en tokens uit.

Vraag actuele contextlimieten op en respecteer bij HTTP 429 de teruggegeven Retry-After.

Blokkeer automatische herverzending zolang de eerdere uitkomst onzeker is.

Routeer afwijzingen en onverklaarde records naar een toegewezen handmatige-beoordelingswachtrij.

Koppel keuzes voor offline- of noodmodus uitsluitend aan officiële communicatie en goedgekeurde procedures.

Oefen incidenten en herstel met aantoonbare reconciliatie, auditspoor en duplicaatcontrole.

Veelgestelde vragen

Hoe controleert een ERP-team de KSeF-status?

Bewaar eerst de lokale job-ID, sessiereferentie en iedere factuurreferentie. Gebruik vervolgens de actuele API om sessies op te sommen of één sessie te bekijken, lees de aggregaten en factuurlijst en controleer waar nodig een individuele factuur op referentie. Baseer de classificatie uitsluitend op de huidige respons.

Wanneer kan een UPO worden gedownload?

Pas wanneer de API-respons een beschikbare UPO-referentie exposeert. Asynchrone verwerking betekent dat zo’n referentie niet direct na transport aanwezig hoeft te zijn. Toon tot die tijd een eerlijke tussenstatus en beloof gebruikers geen document op een zelfgekozen moment.

Wat is het verschil tussen een factuur-UPO en een sessie-UPO?

De officiële guide beschrijft UPO-ophaling voor een afzonderlijke factuur en voor een hele sessie. Koppel het gekozen bewijs aan het juiste niveau en bewaar de bijbehorende referentie. Een sessiedocument ontslaat het team niet van reconciliatie van iedere individuele factuuruitkomst.

Welke gegevens moeten voor incidentonderzoek worden bewaard?

Bewaar correlatie-identifiers, tijdstippen, actuele statussen, teruggegeven KSeF-nummers, UPO-referenties, foutcategorieën en beslissingen. Log geen factuurpayload, token, credential of privésleutel. Stem bewaartermijnen en toegangsrechten af met security, privacy en de verantwoordelijke bedrijfsfunctie.

Hoe gaan we om met pending of afgewezen facturen?

Pending of in verwerking blijft een onvoltooide uitkomst die via de actuele API wordt gevolgd. Een afgewezen factuur gaat met geschoonde foutmetadata naar inhoudelijke of technische beoordeling. Pas na analyse bepaalt de bevoegde eigenaar of correctie, herstel of escalatie passend is.

Wat doen we bij HTTP 429?

Respecteer Retry-After, beperk gelijktijdige workers en raadpleeg de actuele individuele of contextlimieten. Leg de gebeurtenis als meetwaarde vast en voorkom een retry-storm. De officiële documenten, OpenAPI en actuele respons blijven leidend; verzin geen universeel interval of maximaal aantal pogingen.

Kunnen we na een time-out veilig opnieuw verzenden?

Niet automatisch. Een time-out laat de verwerkingsuitkomst onzeker. Zoek eerst de sessie of factuur op, vergelijk referenties en reconcileer met KSeF. Hervat alleen wanneer het verkregen bewijs en de goedgekeurde procedure dat ondersteunen; zo verklein je het risico op duplicaten.

Activeert een KSeF-storing automatisch offline- of noodmodus?

Nee. Een technisch symptoom, waaronder alleen een time-out, machtigt geen officiële storingsmodus. Volg de technische mededelingen en goedgekeurde procedures. De officiële documentatie onderscheidt offline24, aangekondigde onbeschikbaarheid, officieel aangekondigde noodmodus en totale uitval; laat de bevoegde eigenaar de toepasselijke route bepalen.

Belangrijke regels, formaten en termen

Europese CommissieEN 16931Richtlijn 2014/55/EUgestructureerde elektronische factuurKSeF API-monitoring en incidentendraaiboekPolen

Lees verder

Officiële bronnen

We geven voorrang aan officiële overheids- en EU-bronnen waar beschikbaar en tonen controledatums zichtbaar.