KSeF 2.0 National e-Invoicing System API

The KSeF 2.0 - Przewodnik dla Integratorów is a technical compendium designed for developers, analysts, and system integrators working with the National e-Invoicing System (Krajowy System e-Faktur - KSeF) version 2.0. It focuses on technical and practical aspects of communicating with the KSeF API.

Key integration areas covered include:

• Authentication: Access acquisition and session management.
• Permissions & Certificates: Managing KSeF certificates and user permissions.
• Operational Modes: Offline modes, technical corrections, interactive sessions, and batch sessions.
• Invoice Management: Downloading invoices and incremental invoice downloading.
• Security: QR codes, KSeF token management, and public encryption keys.
• System Constraints: API limits and test data scenarios.

Each topic typically includes detailed functional descriptions, code examples in C# and Java, and links to the official OpenAPI specification.

To prevent data gaps, invoices should be retrieved in adjacent time windows using the PermanentStorageHwmDate.

Key Rules for Windowing:

• Enable HWM: You must set restrictToPermanentStorageHwmDate = true in your export request.
• Continuity: Each subsequent window must start exactly where the previous one ended. The 'end moment' is defined as the dateRange.to value (if provided) or the PermanentStorageHwmDate (if dateRange.to is omitted).
• Subject Types: Invoices must be retrieved separately for each subject type (Podmiot 1, Podmiot 2, Podmiot 3, Podmiot upoważniony) to ensure completeness, as a company can appear in different roles on different invoices.
• Truncated Batches: If a batch is truncated (IsTruncated = true), the next call must start from LastPermanentStorageDate. If not truncated (IsTruncated = false), the next call starts from the returned PermanentStorageHwmDate.

KSeF API 2.0 replaces the previous permission inheritance model with an indirect permission mechanism. This allows for a clear separation between a subject's (e.g., an accounting office) own invoice management and the management of their clients' invoices.

Key Concepts:

• Indirect Granting: A client can grant a subject permission to view or issue invoices with a special option enabled that allows the subject to further delegate that permission. The subject can then grant these permissions to their own employees.
• General Permissions: A subject can grant 'general permissions' to an employee, allowing them to handle all clients of that subject, provided the clients have authorized the subject and the employee's specific scope (viewing and/or issuing) allows it.
• Decoupling: Permissions for managing a subject's own invoices are now independent of the permissions required to manage client invoices. This prevents the need for 'excessive' permissions that were required in version 1.0.
• EU Self-Invoicing: A new permission type and login context support self-invoicing for EU entities. Users can log in using a context defined by a Polish entity (identified by NIP) and an EU entity (identified by its EU VAT number), allowing authenticated representatives to issue invoices on behalf of the Polish entity.

The High Water Mark (HWM) mechanism manages starting points for subsequent incremental exports to minimize duplicates and ensure completeness. It consists of two components:

• PermanentStorageHwmDate: A stable upper boundary representing the point up to which the system guarantees data completeness.
• LastPermanentStorageDate: The date of the last invoice in the package, used specifically when a package is truncated (IsTruncated = true).

Continuation Strategy

To maintain continuity and avoid missing documents, determine the starting point for the next export using this priority hierarchy:

1. If the package is truncated (IsTruncated = true): Start the next export from LastPermanentStorageDate.
2. If the package is stable: Use PermanentStorageHwmDate as the starting point for the next window.

Note: Subsequent windows start at the same point as the previous one (adjacency); any resulting duplicates should be removed during the deduplication stage using KSeF numbers from _metadata.json.