E-Invoice Finder
Menu
Countries Compare software Deadlines Guides Checker Check obligation
ENFRDEPLNL
Poland · KSeF operations

KSeF API monitoring and incident response for ERP teams

Monitor KSeF API sessions, invoice status, UPO, limits and incidents with a practical ERP runbook for reconciliation, alerts and safe recovery.

Quick verdict:
  • Scope: monitor each KSeF session and every invoice through a reconciled operational record.
  • Risk: transport success, timeouts and session totals can conceal pending, rejected or uncertain invoices.
  • Action: preserve references, follow current API responses and use controlled recovery with human review.
Get Poland readiness reportOfficial sources
Last checked: 27 July 2026Based on official sourcesClear summaryBusiness guidance, not legal advice
Official sources prioritized
Last-checked dates visible
Free checker, no signup required

What you need to know

Guide

1. Build monitoring around correlation, not transport

Treat KSeF 2.0 as asynchronous: successful transport starts or advances work but does not prove that an invoice was successfully processed or assigned a KSeF number. Connect each local business event to its remote result. Preserve the local ERP invoice or job identifier, session reference, every invoice reference, request and response timestamps, and the latest returned status and KSeF number where present. Keep one-to-many relationships explicit because an export job can contain many invoices, each needing its own outcome. Structured logs may show safe correlation data such as ERP job, references and observation time, but never invoice payloads, credentials, private keys or tokens. Common mistakes are overwriting a reference during recovery, confusing session and invoice identifiers, or treating an HTTP success as acceptance. Use the current OpenAPI specification and official documentation as runtime truth because endpoints, response fields and statuses may evolve.

Guide

2. Follow session and invoice lifecycles, then retrieve UPO

The official 20 April 2026 Integrator Guide describes monitoring interactive and batch session state. The API supports listing sessions, checking one session, reading aggregated invoice counts, listing invoices in a session and checking an invoice by its reference. Represent outcomes from current responses as pending or processing, successfully processed, or rejected; do not invent meanings for undocumented codes. A session aggregate helps show progress, but never replaces invoice-level reconciliation. If 498 of 500 items are processed, identify the other two before closing the ERP job. UPO also has separate scopes: an invoice UPO relates to its invoice, while a session UPO relates to the offered session scope. Download either only when the response exposes an available UPO reference. Until then, display “UPO not yet available” rather than promising evidence or declaring failure. Archive each retrieved UPO with its scope, source reference, retrieval time and integrity controls.

Guide

3. Instrument useful fields, metrics and dashboards

A dashboard should answer what was sent, its current state, available evidence and exception owner. Capture environment, entity, local ERP/job identifier, session and invoice references, submission and latest-check times, returned status, KSeF number, documented rejection detail, UPO scope/reference, recovery state and owner. Keep logs credential-safe and access controlled. Useful views include sessions and invoices by state, unmatched ERP records, rejections, unresolved items, available UPOs not yet archived, HTTP 429 responses, unresolved-age distribution and reconciliation differences. Counts are observations, not legal conclusions. Provide drill-down to safe correlation records without exposing invoice content. Avoid misleading signals: a green availability tile can coexist with a processing backlog, while balanced session totals can hide an invoice mapped to the wrong ERP record. Reconcile identifiers as well as totals, and retain enough history to explain state changes during an incident.

Guide

4. Define alert severity and ownership by impact

Set severity from business impact, evidence and recoverability, not invented timing thresholds. Critical scenarios may include widespread inability to submit or query, duplicate-risk recovery, credential compromise or a material reconciliation gap near an internal deadline. Repeated population-wide rejections, unresolved processing or a blocking limit may warrant high priority; an isolated documented rejection can enter normal manual review. Assign owners before go-live: integration engineering for client behaviour, ERP operations for job control, finance operations for corrections, security for credentials, and an incident commander for cross-team work. Alerts should include environment, affected scope, correlation references, current documented status, last successful operation, a safe diagnostic step and the official-communications link. Group related symptoms without losing invoice-level records. Escalation must follow the organisation’s own cut-offs and risk tolerance; this guide does not invent an official SLA or interpret legal deadlines.

Guide

5. Respect HTTP 429, limits and duplicate-safe recovery

KSeF has API and context limits. Official incremental-download guidance explicitly requires handling HTTP 429 and Retry-After, so pause the affected flow as instructed instead of hammering the service. Default context limits allow at most 10,000 invoices in an interactive or batch session, but current or individual limits can differ and can be queried. Discover applicable limits rather than hard-coding assumptions. Use bounded concurrency, back-pressure and durable checkpoints. Do not invent a polling interval or retry count; base operation on current guidance, returned instructions, workload and internal controls. Never automatically resend an invoice with an uncertain outcome after a timeout or broken connection. First query known session and invoice references, list session invoices when needed, and reconcile against the local ledger. Resend only through an approved path when evidence supports it. Stable correlation keys, idempotent local job control and a dead-letter queue reduce duplicate risk. A timeout is a client observation, not the server’s final outcome.

Guide

6. Route rejections through correction and reconciliation

A rejected invoice should become a controlled business exception, not an endless technical retry. Preserve its invoice reference, documented rejection detail, observation time and ERP identifier; route it to the team able to correct the data or configuration. Link any corrected attempt to the original without replacing either evidence trail. A manual-review view should present safe metadata, the documented response, ownership and authorised actions, while protected invoice data remains in the source system. Reconcile the ERP ledger with KSeF at invoice level: expected records, observed references, processed outcomes, KSeF numbers, rejected and unresolved items, and archived UPO evidence. Compare this result with session aggregates as a control only. If a session reports 100 items but the ERP ledger matches 99 references, investigate before closure. Maintain a dead-letter queue for cases automation cannot resolve, record resolution evidence and test that correction does not create a second local posting.

Guide

7. Keep official outage modes behind an explicit decision boundary

Official material distinguishes offline24 chosen by the taxpayer, offline operation during announced unavailability, emergency mode during an officially announced failure, and total failure. These are not interchangeable technical fallback labels. Switching legal operating modes must follow current official communications and the organisation’s approved tax, legal and operational procedure—not an engineer’s inference from a timeout, HTTP error or alarm. A timeout alone does not authorise an official outage mode. During disruption, preserve evidence, restrict automatic resubmission, check KSeF technical communications and record who approved each decision. Separate technical containment, such as pausing workers and protecting queues, from the accountable business decision to use an official mode. Monitor communications because announcements and procedures can change. This is operational information, not legal or tax advice. After recovery, reconcile locally retained documents with remote results before releasing queues, especially where an earlier submission remains uncertain.

Guide

8. Tabletop example: timeout with uncertain invoice state

Scenario: a batch worker sends a session, records its session and invoice references, then times out while checking progress. Some invoices are processed, others pending, and one has no recent outcome. The worker stops automatic resend and marks the job uncertain. The incident lead gathers the local job identifier, references, timestamps, last responses, aggregate counts, invoice results, returned KSeF numbers and available UPO references, while confirming logs contain no credentials or payloads. The team queries the session and uncertain invoice through the current API and obeys any HTTP 429 Retry-After response. Finance compares the remote list with the ERP ledger. With no official failure communication, nobody switches outage mode because of the timeout. A later processed result is captured without resend; a rejection enters controlled correction; an unresolved item remains quarantined with an owner. The drill succeeds when every item is reconciled, decisions have evidence and the team can explain why no duplicate arose.

Guide

9. Select vendors by evidence and turn findings into action

Evaluate connectors on operational proof, not a generic KSeF checkbox. Ask vendors to demonstrate separate session and invoice monitoring, reference preservation, invoice-level reconciliation, UPO retrieval only when a reference is available, and clear pending, processed and rejected outcomes. Verify configurable HTTP 429/Retry-After handling, current-limit discovery, back-pressure, durable checkpoints, dead-letter and manual-review queues, credential-safe logging and role-based access. Require evidence that uncertain submissions are queried before resend and that a generic timeout cannot activate an official outage mode. Review how the product tracks OpenAPI and official-documentation changes, tests upgrades and preserves auditable history. Next, map the ERP flow, assign correlation fields and owners, test a mixed-outcome session, simulate throttling, rehearse uncertain-state recovery and run an outage-communications tabletop. Record each gap with an owner and acceptance evidence. Require exportable reconciliation and incident records so a future vendor change does not strand operational history.

Checklist

Persist the local ERP or job identifier, session reference and every invoice reference as separate correlated fields.

Record submission and observation timestamps, the current returned status and any assigned KSeF number.

Reconcile every invoice result against the ERP ledger instead of relying only on session aggregates.

Retrieve and archive invoice or session UPO only after an available UPO reference is exposed.

Build dashboards for unresolved, rejected, unmatched and UPO-pending records without exposing invoice content.

Assign named owners for integration, ERP, finance, security and cross-team incident decisions.

Handle HTTP 429 according to Retry-After and query current applicable limits rather than hard-coding them.

Quarantine uncertain submissions and query their state before considering any resend.

Require official communications and approved procedures before switching an offline or emergency mode.

Run reconciliation, throttling and outage tabletop drills, then retain evidence of findings and fixes.

FAQ

How do I check an invoice’s status in KSeF?

Preserve its invoice reference and query the invoice using the current documented API. Interpret only the fields and statuses defined by the current OpenAPI and official guidance, and correlate the result with the local ERP record, session reference, timestamps and any returned KSeF number.

When is a KSeF UPO available?

A UPO should be downloaded only when the relevant API response exposes an available UPO reference. Until then, describe it as not yet available; do not promise that it exists or treat its temporary absence as proof of rejection.

What is the difference between an invoice UPO and a session UPO?

They apply to different scopes. An invoice UPO relates to the invoice outcome, while a session UPO relates to the session scope offered by KSeF. Store the scope and source reference with each downloaded document and do not use a session artifact to skip invoice-level matching.

What should an ERP store for KSeF monitoring?

Store the local ERP or job identifier, session reference, each invoice reference, timestamps, latest returned status, KSeF number when present, rejection information, UPO reference and scope when available, and review ownership. Keep invoice payloads, credentials, private keys and tokens out of logs.

How should pending and rejected invoices be handled?

Keep pending or processing invoices under observation using current API responses without inventing a deadline. Route rejected invoices to a controlled correction and manual-review process, preserve the original evidence, and link any corrected attempt rather than overwriting history.

What should a client do after HTTP 429?

Respect the Retry-After instruction in the current response and apply back-pressure to the affected work. Query current applicable limits and avoid fixed assumptions about retry counts or polling intervals; official and individual limits can differ.

Is it safe to resend an invoice after a timeout?

Not automatically. A timeout does not reveal the server’s final result, so first query the known session and invoice references and reconcile them with the local ledger. Keep uncertain items quarantined until evidence supports an approved next action.

Does a timeout allow us to use an offline or emergency mode?

No. A timeout alone does not authorise an official outage mode. Follow current KSeF technical communications and the organisation’s approved procedure, with the accountable business owner deciding how official offline, emergency or failure guidance applies.

Key regulations, formats and terms

PolandKSeFKrajowy System e-FakturPolish Ministry of Financepodatki.gov.plstructured invoiceAPI authenticationinvoice correctionsaccounting softwareVATSMEecommerceEuropean CommissioneInvoicingEN 16931Directive 2014/55/EUstructured electronic invoiceVAT automationcross-border tradeKSeF API monitoring and incident-response runbook

Poland — Country hub

Poland

Open country hub →

Use the country hub to see every related deadline, checklist, format guide and software comparison for this market.

Continue reading

Official sources

We prioritize official government and EU sources where available and keep last-checked dates visible for mandate-sensitive pages.