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

KSeF inbound invoice synchronization for ERP teams

Design reliable KSeF invoice retrieval with HWM checkpoints, encrypted exports, deduplication and restart-safe ERP reconciliation.

Quick verdict:
  • One cursor per role keeps the audit trail independently explainable.
  • A premature checkpoint can conceal an accounting-data gap.
  • Demand a witnessed recovery drill before approving production.
Get Poland readiness reportOfficial sources
Last checked: 28 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

Architecture and inbound scope

The official KSeF 2.0 integrator documentation recommends incremental retrieval through asynchronous POST /invoices/exports when synchronizing KSeF with an external local database. Build that flow as distinct stages: authorize the subject, start an export for a defined window and SubjectType, poll its status, download every returned part, decrypt and unpack it, validate the package, stage records, commit them to durable storage, and only then advance the checkpoint. Keep orchestration separate from ERP posting so a tax-code or supplier-matching exception cannot corrupt transport state. Define scope for every Polish entity, environment and role before implementation. A company may occur as Subject1, Subject2, Subject3 or an authorized subject, so an inbound design limited to the buyer role can miss documents that users can legitimately access. This is practical integration guidance, not legal or tax advice; confirm the flows and permissions applicable to each entity with official documentation and qualified advisers.

Guide

HWM and PermanentStorage completeness

Use the PermanentStorage timeline for incremental completeness. PermanentStorageHwmDate is the High Water Mark: records with a PermanentStorage timestamp at or before that boundary form a closed set, while records newer than it may still appear. Setting restrictToPermanentStorageHwmDate=true creates a stable HWM synchronization window. Adjacent windows should meet at the prior endpoint, and the connector should tolerate that boundary appearing again. Do not substitute Issue or Invoicing dates: they describe the business document, not when the searchable permanent set became complete. HWM-to-HWM processing therefore favors deterministic recovery and fewer duplicates, but delays the newest invoices. Also distinguish receipt semantics from download activity: the date of receipt is the date on which KSeF assigns the KSeF number, not the time your integration downloads the XML. Store both business dates and retrieval timestamps without redefining either.

Guide

Per-role windows, checkpoints and truncation

Maintain an independent continuation point for every SubjectType, entity and environment. Never let a successful Subject1 run advance Subject2, Subject3 or authorized-subject state. For each export, persist the requested start, requested end, returned PermanentStorageHwmDate, LastPermanentStorageDate and IsTruncated value in the staged run record. If IsTruncated=true, continue from LastPermanentStorageDate because the package ended before the stable boundary. If it is false, continue from PermanentStorageHwmDate. The next window starts at the preceding endpoint rather than adding an arbitrary millisecond; boundary overlap is expected and must be deduplicated by KSeF number using _metadata.json. Use a lease or compare-and-swap version on each role checkpoint so a scheduler and manual refresh cannot advance the same stream concurrently. A common mistake is keeping one company-wide timestamp: it hides role-specific lag and can convert a partial success into missing invoices.

Guide

Encrypted export package processing

An export is asynchronous: a successful start does not mean invoice files are ready. Poll according to the documented status flow, then download all encrypted ZIP parts only after completion. Verify the expected part list, sizes or available integrity data; write downloads to a run-specific staging area. Use the export key and IV to decrypt with AES-256 as specified, assemble the parts in the documented order, unzip the result, and reject the run if a part is absent, duplicated, corrupted or cannot be decrypted. Reconcile every XML file against _metadata.json before anything reaches the ERP: flag an XML without metadata, metadata without XML, duplicate KSeF numbers and unexpected counts. Do not log access tokens, encryption keys, IVs or invoice payloads. Keep secrets in a protected secret store, restrict staging access, clear temporary material under a defined retention policy, and expose only non-sensitive run IDs, counts and error classes to monitoring.

Guide

Deduplication and an atomic ERP commit

Use the KSeF number as the idempotency and deduplication key. A supplier's business invoice number alone is unsafe because numbering may repeat across suppliers, years or source systems. Create a unique database constraint on the KSeF number and retain the package and role provenance needed for audit. The commit order matters: parse and validate into staging, apply inserts or safe updates and reconciliation records in one transaction or equivalent durable unit, mark the package committed, then atomically move the role checkpoint. If a crash occurs before commit, replay the same window; if it occurs after invoice commit but before checkpoint movement, replay and let the KSeF-number constraint absorb duplicates. Never advance state merely because files were downloaded. Where ERP posting is asynchronous, first commit a durable canonical invoice and outbox event together, then let a retryable worker post to accounts payable without altering KSeF retrieval completeness.

Guide

Backfill, freshness and manual refresh choices

For the first run, choose an approved backfill start date, process bounded windows and use the same truncation and commit rules as daily operation. An empty package is still a meaningful completed window when its HWM and role are recorded correctly. Routine HWM-to-HWM runs minimize duplicate work and provide stable completeness, but they intentionally wait for the closed boundary. If users need a fresher view, offer a separate “to now” refresh that overlaps from the prior HWM and deduplicates locally; do not treat its newest endpoint as a completeness checkpoint. Serialize it with the scheduled stream or give it read-only provisional status until the stable run catches up. Respect HTTP 429 and Retry-After. Current official guidance describes no more than 20 export starts per hour and at least 15 minutes between starts for a subject type, but the current API documentation is the runtime truth and limits can change. Do not invent a tighter polling or export schedule.

Guide

Monitoring, reconciliation and security controls

Monitor each entity and SubjectType separately: age of the last committed HWM, export starts and completions, truncated-window count, package parts expected and received, XML-to-metadata differences, duplicate KSeF numbers, invoices staged and committed, ERP outbox backlog, 429 responses and retry delay. Alert on lack of progress rather than only on failed requests; a connector returning empty windows with a frozen checkpoint is not healthy. Reconcile three levels: the export metadata against decrypted XML, canonical storage against committed package records, and ERP outcomes against the canonical queue. Produce a non-sensitive run manifest with window boundaries, role, counts, hashes where appropriate and commit ID. Apply least privilege to KSeF credentials and storage, separate test and production, rotate secrets without logging them, and audit manual runs. Avoid dashboards that expose counterparties, amounts or payload fragments when operational counts and identifiers are sufficient.

Guide

Failure drills and a worked continuation example

Test the first backfill, an empty window, a truncated package, a duplicate exactly on a shared boundary, a missing or corrupted part, decryption failure, 429 with Retry-After, and crashes immediately before and after the atomic commit. Also test the same KSeF number appearing through role overlap and a manual refresh racing the scheduler. For example, suppose Subject2 starts at 08:00, the export reports an HWM of 10:00, IsTruncated=true and LastPermanentStorageDate=09:12. After package validation and durable commit, save 09:12 as that role's continuation point and start its next window at 09:12; the repeated boundary item is harmless because the KSeF number is unique. If the following export is not truncated and returns an HWM of 10:15, advance to 10:15 only after commit. A crash before either commit leaves the earlier checkpoint intact, while a crash just after invoice commit causes a safe replay rather than a gap.

Guide

Vendor decision criteria and next actions

Ask vendors to demonstrate the official export flow, not merely show downloaded invoices in a screen. Require evidence of separate SubjectType checkpoints, PermanentStorageHwmDate handling, the IsTruncated branch, complete encrypted multipart processing, _metadata.json reconciliation, KSeF-number idempotency, atomic checkpoint movement and Retry-After behavior. Inspect how they represent provisional “to now” results, prevent concurrent runs, recover without operator edits and preserve non-sensitive audit evidence. Reject claims that an invoice number from the supplier is a sufficient key or that Issue date proves retrieval completeness. Next, inventory entities and roles, agree the backfill boundary and freshness target, draw the state transition, define database uniqueness and staging retention, and run the failure matrix with production-like volumes. Record observed recovery time and reconciliation differences, then accept the connector only when every rerun converges without missing invoices or moving a checkpoint ahead of durable data.

Guide

Practical question summary

For KSeF inbound invoice synchronization with HWM and deduplication: Most KSeF questions are about who must use the system, whether current accounting software is ready, how authentication works, how corrections are handled, whether ecommerce or ERP needs API integration, and how accountants access invoice data. This guide focuses on those operational decisions.

Guide

Decision framework for businesses

For KSeF inbound invoice synchronization with HWM and deduplication: A KSeF-ready workflow should show who creates invoices, who submits them, who monitors status, who handles rejection or correction, how invoices are archived and how the accountant sees the records.

Guide

How to use this guide

Use this guide to decide whether KSeF inbound invoice synchronization with HWM and deduplication affects your Poland workflow and which evidence is still missing. Start with KSeF authentication, structured invoice submission, invoice status handling, then test submit a KSeF invoice and simulate an API rejection before comparing software.

Guide

Data and terms to prepare

For KSeF inbound invoice synchronization with HWM and deduplication, the important terms are KSeF inbound invoice synchronization with HWM and deduplication, Poland, KSeF authentication, structured invoice submission, invoice status handling, corrections and rejections, accounting or ecommerce integration. Clean these fields in customer, supplier, tax and accounting records before rollout; otherwise validation and support issues appear during daily invoicing.

Guide

Software proof to request

For KSeF inbound invoice synchronization with HWM and deduplication, ask vendors to show show KSeF authentication, submission status, corrections, permissions and accounting export using your examples. The demo should cover submit a KSeF invoice, simulate an API rejection, create a correction, verify user permissions and explain who handles errors, corrections, archive access and accountant handoff for KSeF authentication, structured invoice submission, invoice status handling.

Guide

Evidence before rollout

Keep official links, screenshots, test invoices and the decision reason for KSeF inbound invoice synchronization with HWM and deduplication. For KSeF inbound invoice synchronization with HWM and deduplication, the implementation file should prove how KSeF authentication, structured invoice submission, invoice status handling, corrections and rejections were checked, not just that a tool was selected.

Guide

Decision checkpoint

Do not close KSeF inbound invoice synchronization with HWM and deduplication until someone can explain KSeF inbound invoice synchronization with HWM and deduplication in Poland, name the workflow owner, show one tested invoice scenario and describe how the team avoids choosing software for Poland before proving the real KSeF inbound invoice synchronization with HWM and deduplication workflow.

Checklist

Inventory every entity, environment and SubjectType that needs an independent retrieval stream.

Base incremental windows on PermanentStorage and enable stable HWM restriction for routine synchronization.

Persist returned HWM, LastPermanentStorageDate and IsTruncated before selecting the next endpoint.

Download every export part and verify completeness before decrypting or unpacking the package.

Reconcile XML files and KSeF numbers against _metadata.json before ERP ingestion.

Enforce a unique KSeF-number constraint instead of deduplicating by business invoice number.

Commit canonical invoices and checkpoint movement atomically, with a retryable ERP outbox.

Separate stable HWM runs from overlapping provisional refreshes and prevent concurrent checkpoint writers.

Honor HTTP 429 and Retry-After while checking current official limits at runtime.

Run the full failure matrix and retain non-sensitive reconciliation evidence for every release.

FAQ

How should an ERP download incoming invoices from KSeF?

Use the asynchronous POST /invoices/exports flow recommended in the official KSeF 2.0 integrator documentation for synchronization with a local database. Start a role-specific export window, wait for completion, download and decrypt every part, reconcile XML against _metadata.json, commit durably, and only then advance that role's continuation point.

What does HWM mean in KSeF invoice retrieval?

The High Water Mark, returned as PermanentStorageHwmDate, is the completeness boundary for PermanentStorage. Records at or before it are a closed set; newer records can still appear. With restrictToPermanentStorageHwmDate=true, a routine run can process a stable endpoint rather than treating a changing “now” as complete.

Which checkpoint should be saved after an export?

If IsTruncated=true, continue from LastPermanentStorageDate. Otherwise continue from PermanentStorageHwmDate. Save the applicable endpoint only after the package and invoices are durably committed, and keep separate state for every entity, environment and SubjectType.

How can we avoid both duplicate and missing KSeF invoices?

Begin each adjacent window at the preceding endpoint and expect boundary overlap. Reconcile _metadata.json and enforce uniqueness by KSeF number, not by the supplier's business invoice number. Never skip forward by an invented time increment or move a checkpoint after download but before durable storage.

How does synchronization resume safely after a crash?

A crash before the atomic commit must leave the previous checkpoint unchanged, so the connector replays that window. A crash after invoice storage but before checkpoint movement may also replay it; the unique KSeF-number constraint makes that retry idempotent. A canonical store plus transactional outbox can retry ERP posting independently.

When should we use HWM-to-HWM versus a “to now” refresh?

Use HWM-to-HWM for the authoritative incremental stream because it trades some freshness for a closed, reproducible set. Use a “to now” refresh only when users need newer provisional records; overlap from the prior HWM, deduplicate locally, and do not promote the changing endpoint to the stable checkpoint.

How should encrypted KSeF export ZIP parts be processed?

After export completion, obtain every listed part, verify that none is missing or corrupt, decrypt with AES-256 using the export key and IV, assemble in the documented order, and unzip in protected staging. Reconcile the resulting XML files with _metadata.json and reject the run on any unexplained count or identity mismatch.

Which tests matter most when selecting a KSeF integration vendor?

Require live evidence for backfill, empty and truncated windows, shared-boundary duplicates, corrupted or missing parts, decryption failure, 429 and Retry-After, crashes on both sides of commit, role overlap and concurrent manual refresh. Also verify that secrets and payloads stay out of logs and that reruns converge without data loss.

What do businesses usually ask about KSeF?

For KSeF inbound invoice synchronization with HWM and deduplication: They ask about software readiness, API integration, authentication, corrections, accountant access and ecommerce workflows.

What is the most practical KSeF risk?

For KSeF inbound invoice synchronization with HWM and deduplication: The practical risk is late discovery that permissions, corrections or invoice status handling do not match the business process.

What should I test first for KSeF inbound invoice synchronization with HWM and deduplication?

For KSeF inbound invoice synchronization with HWM and deduplication, start with submit a KSeF invoice, simulate an API rejection, create a correction because those scenarios reveal whether the workflow is practical.

What is the main risk for KSeF inbound invoice synchronization with HWM and deduplication?

The main risk is choosing software for Poland before proving the real KSeF inbound invoice synchronization with HWM and deduplication workflow.

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 inbound invoice synchronization with HWM and deduplication

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.